Endpoints

All routes below assume the default path: 'agent' (set via AgentModule.forRoot) — replace the /agent prefix if you configured a different one. See Frontend for a client walkthrough and packages/dashboard for the console SPA.

ChatCopy Anchor Link

regenerate: true re-runs the last exchange instead of appending a new user message: the loop truncates everything after the thread's last user message and re-answers it. It requires an existing threadId — there's no last exchange to redo on a fresh thread — and, like the ownership-scoped routes below, the caller must own that thread. message is ignored: the stored user message is the one answered, and it is never stored twice. A backend that serves these routes itself does the same, including dropping whatever its runner keeps of the replaced answer.

uiCapabilities lists the generative-UI components this client renders, by exact version. Omitted, every catalog component is offered and sent; components: [] is text only; anything else is intersected with the server catalog, and components left out arrive as their text. It is stored with a queued message. See One answer, every surface.

model applies to that turn only — a send never stores it on the thread, new or existing. Pinning is PATCH /agent/threads/:id { model } (below), and only a pin outlives the turn.

Errors answer their status with a JSON body { message, code? }. The React client's AgentHttpError carries status, code, the parsed body, and the server's message as its own message, so a hook that shows error.message shows the server's words; <AgentProvider onHttpError> sees every error answer before it is thrown.

GET /agent/chat/:runId/stream and POST /agent/chat/:runId/cancel are both ownership-scoped: each resolves the acting actor and checks they own the run currently streaming — 403 if it belongs to someone else, 404 if nobody is streaming that run. A finished run is a 404 rather than a replay of its buffer: ownership is derived from the thread's active stream, which the runner clears as the run ends, so reconnect while the turn is live (which is what activeRunId on a thread tells a client).

Every event frame carries an SSE id: — strictly increasing (this library uses the frame's 1-based position in the run), the same on every attach — so a client that dropped can resume with ?after=<last id>. See Sequence numbers and reconnecting.

A turn's attachments may carry only a mediaId — see Attachments below.

AG-UICopy Anchor Link

Mounted only with adapters: [agUiAdapter()] — see AG-UI.

Message queueCopy Anchor Link

A send on a thread whose turn is still running is queued (per-thread FIFO, persisted) and runs when that turn settles — Typing ahead. ChatQueueState is { items: { id; content; attachments?; agentName?; model?; interrupt?; createdAt; updatedAt }[]; paused: { reason: 'run_failed' | 'cancelled' | 'quota_exceeded' | 'start_failed'; message?; at } | null }. Every route is ownership-gated like the thread routes.

mode: 'auto' (default) streams on an idle thread and queues on a busy one; 'queue' always queues (and starts at once when idle — the 202 then carries runId); 'interrupt' queues at the head and cancels the running turn. A queued message runs under its own id (messageId = the run id). The running turn's stream carries a queue frame on every change, and a final one with started: { messageId, runId } when it hands the thread over.

AttachmentsCopy Anchor Link

Always mounted; live whenever something is bound to AGENT_ATTACHMENT_STAGING (501 otherwise). The body is aborted mid-stream past a hard 32 MiB ceiling (HARD_MAX_ATTACHMENT_BYTES) — the configured maxBytes narrows that at request time and cannot raise it. Both size gates answer 413; a type outside allowedContentTypes answers 415. The limits come from the staging store's describe() when it declares them (AgentMediaAttachmentsModule), else AgentModule's attachments option — and GET /agent/config serves them. With AgentMediaAttachmentsModule, the resumable /agent/attachments/uploads routes are the documented upload path.

POST /agent/chat names uploads as attachments: [{ mediaId }] — refs only; an entry with any other key is refused with 400, and so are more than MAX_ATTACHMENTS_PER_MESSAGE (10) entries (maxPerMessage on GET /agent/config). With nothing bound to AGENT_ATTACHMENT_STAGING, a send that carries attachments answers 501. GET /agent/threads/:id re-mints each attachment's url by mediaId.

GET answers the question GET /agent/threads/:id cannot: an upload that was never sent belongs to no thread. It is scoped to the resolved actor and nothing else, bounded to ATTACHMENT_PAGE_SIZE (50), and answers 501 when the bound staging store implements no list. There is deliberately no threadId filter — a thread's attachments already ride on its messages in the thread payload, so a second ownership path would be new risk for information the client already holds. Entries carry no url: resolve mints those per turn so they can be short-lived, and a listing that returned one per row would undo that just to render a file list.

Resumable uploads (@dudousxd/nestjs-agent/media)Copy Anchor Link

Mounted by AgentMediaAttachmentsModule (not by AgentModule). The bytes go to nestjs-media's own tus endpoint (PATCH /media/uploads/:uploadId), never through these routes. See File uploads.

AgentsCopy Anchor Link

ModelsCopy Anchor Link

A turn runs on the send's model, else the thread's pinned model (PATCH /agent/threads/:id), else the provider's default. Any model the catalog does not list as available for the actor and agent is refused with 400 — when it is pinned, and again on every turn that runs on it, since availability can change in between. Without a catalog, every request naming a model is refused.

A catalog that answers locked: { model, reason? } locks the agent to that model: every turn runs on it whatever the send or the thread's pin names, and a send naming another model is refused with 400 (the reason in the message). List the other models as unavailable too, so an older client cannot pick them. lockedModel on the agent's GET /agent/agents entry says the same before a chat starts.

ThreadsCopy Anchor Link

All :id routes are ownership-scoped: they resolve the acting actor and check they own the thread — 403 if it belongs to someone else, 404 if it doesn't exist.

MessagesCopy Anchor Link

Rates a message in one of the caller's threads; value: null clears the rating. The rating comes back on the message in GET /agent/threads/:id (feedback). 403 for another actor's message, 404 for an unknown one, 400 for any other value or a comment over 2000 characters, 501 on a store without threadOfMessage + setMessageFeedback (both bundled stores have them).

Tool-callsCopy Anchor Link

Approving/rejecting signals the run's AgentRunner (approved: true, or approved: false with an optional reason) — see Human-in-the-loop & durability. The caller must be the call's recorded approver (403 otherwise — the thread's owner for requester, a holder of the role otherwise) and the request must not have lapsed (410). All four routes answer 409 { code: 'run_not_active', message } when the run that asked has ended — it failed, was cancelled, or its worker is gone — instead of signalling a run that will never read the decision. remember: true approves later calls of the same tool in the same thread; via (1–64 chars, default 'web') is recorded as the surface the decision came through. answer/skip settle a parked question set on the same channel — see Asking the user. An omitted question (or an omitted answers entirely) takes the request's own pre-picked default, resolved server-side, so an empty body is a valid confirmation; answers are checked against the parked questions (400 answers["<id>"] <reason> for a value a typed question's rules refuse, an off-list pick, or a required question left without an answer or default); skip is recorded as a rejection rather than as an answer. answer/skip take via like approve/reject, and the settled outcome records answeredBy (the actor) and answeredVia.

All four bodies are validated before anything is signalled — a human reply is journaled and re-read on every replay of the run it settles, so a payload the loop cannot read is a run that fails identically forever rather than one failed request. toolCallId must be a non-empty string; answers must be an object of questionId → array of strings (at most 100 questions, 100 values each, 4096 characters per value); reason must be a string of at most 4096 characters. Anything else is a 400.

The run is derived server-side from the toolCallId — the call's own runId where the row carries one, falling back to its thread's active stream — so no run id is sent, and that is also how a delegated sub-agent's action tool routes to its own child run. All four routes are ownership-scoped: the acting actor must own the tool call — 403 if it belongs to someone else, 404 if it doesn't exist.

Action proposalsCopy Anchor Link

Used with actionApprovalMode: 'independent' — see Action proposals. Mounted with the other routes, in either mode. On a store without proposal support there are none: the list answers 200 [], and approve / reject answer 501.

The thread's owner sees every proposal; anyone else sees those the approval policy lets them decide. Deciding needs the same permission (403 otherwise), and the thread's tenant must be the caller's (403). 404 for an unknown thread or proposal. A body field other than the one listed is a 400. X-Action-Proposals-Next is URI-encoded JSON: decode it and pass it back as after; an invalid cursor is a 400. The decision is recorded with via: 'web'.

QuotaCopy Anchor Link

GET /agent/quota is the bound QuotaProvider's report. The default, LedgerQuotaProvider, reads the usage ledger: a day window and a month window when the store implements usageBetween, with the ceilings quota: { limits } sets. blocked names the first exhausted window. quota: { warnAt: 0.8 } adds a soft limit: every window with a ceiling carries warnAt, and warning names the fullest window past it (never while blocked). A window leaves usedTokens out when its budget does not count tokens (a USD-only spend cap) instead of reporting 0.

When the host configured quota (limits or a provider), a blocked report also gates POST /agent/chat: the send is refused with 429 and { code: 'quota_exceeded', period, message } before the turn starts. See Cost & governance.

Client configCopy Anchor Link

Server facts a client would otherwise repeat in its own config. useAgentConfig() reads it once per backend; useAttachments (and chat.composer.files) take their accept / maxBytes / maxFiles defaults from it.

Dashboard JSON APICopy Anchor Link

Mounted by AgentDashboardModule.forRoot({ apiBasePath }) (default /ai-gateway/api, i.e. <basePath>/api under the default /ai-gateway UI base). Requires AGENT_GOVERNANCE_QUERIES to be bound by a store adapter (e.g. MikroOrmAgentStoreModule). The console's sections now live on hash routes (/ai-gateway#/reliability, #/approvals, …), deep-linkable on full page load.

The inbox lists blocking approvals (tool calls in pending_approval). Pending action proposals are not in it; decide those through the thread's action-proposal routes or AGENT_APPROVAL_PORT.approveActionProposal.

When the dashboard is configured with dashboardAuth, it also mounts <basePath>/auth/*, outside its own guards: GET/POST /auth/login (a server-rendered login form) and POST /auth/logout for the login mode, POST /auth/session (the host frontend exchanges its own auth for the dashboard cookie) and GET /auth/session-required for the session mode. A mode's routes 404 when it is not listed in auth.modes, and all of them 404 without dashboardAuth. See packages/dashboard.

GovernancePage<T> is { rows: T[]; page: number; pageSize: number; total: number } (real COUNT + offset, deterministic id tiebreaks); an unknown where field 400s naming it. LiveAgentEvent is { event: string; ts: number; payload: Record<string, unknown> } — see Diagnostics events for the event names and payload shapes.