REST API: chat
Request synchronous or streaming chat responses from a backend service.
The Chat API has two endpoints: a regular response endpoint and a streaming endpoint. Use the regular endpoint when your backend can wait for a complete response. Use the streaming endpoint when your backend can forward progressive output to an authorized client and manage disconnects and backpressure. In both cases, keep the AgentStack API key on the server. Before you send a model-backed request, validate the caller.
An API key needs the write scope. An OAuth access token, such as the token an MCP client or Vercel Connect holds, needs the mcp:chat scope, which is never granted by default: the client must request it, and the user approves it on the consent screen. The user who approved the token also needs permission to view agents. A token without mcp:chat answers 403 with INSUFFICIENT_SCOPE, even when it holds mcp:write. A user without that permission gets 403 with PERMISSION_DENIED. A token chats with an agent of the user's active MCP organization, and the turn spends that organization's credits. See OAuth access tokens.
A chat request is billable, stateful work, not a harmless probe. Limit user input. Set a timeout in your own service. If your workflow cannot tolerate a second response, do not replay a request automatically after an ambiguous network failure. If you expose streaming to a browser, proxy the stream through your backend. Do not give the browser direct access to the key.
Both endpoints require an application/json request body. The body must have an
agentId and a message. The message must contain a non-whitespace character.
It can contain at most 4,000 characters. An empty, whitespace-only, missing, or
incorrectly typed field returns 400 VALIDATION_ERROR. A message over the limit
returns 413 MESSAGE_TOO_LONG. The optional sessionId must be a UUID.
Omit sessionId to start a new conversation; the response returns the new
session's ID. Send that ID with the next message to continue the same
conversation. The agent then sees the session's most recent 20 messages,
including the new one, so it can answer questions about earlier turns.
See the generated reference for the exact message and agent parameters. For an embedded visitor experience, use the supported widget. For an internal tooling workflow, use the REST envelope, rate-limit headers, and error codes in the REST guides.