> For the complete documentation index, see [llms.txt](https://docs.guayaba.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guayaba.run/documentation/api-reference/chat.md).

# Chat

Send messages to an agent. Supports sync and SSE streaming. Requires `chat` scope.

## Send a message to an agent

> Sends a chat message to the agent. By default returns a sync JSON response with\
> the full assistant reply. Set \`stream: true\` to receive Server-Sent Events (SSE)\
> with incremental deltas.\
> \
> \*\*Sessions\*\*: If no \`sessionKey\` is provided, a new session is created with an\
> \`api:\` prefix. Reuse the returned \`sessionKey\` to continue a conversation.\
> \
> \*\*Billing\*\*: Each message costs 1 credit (base) plus the LLM cost charged by the runtime.\
> \
> Requires \`chat\` scope on agent keys. Master keys have implicit access.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Chat","description":"Send messages to an agent. Supports sync and SSE streaming. Requires `chat` scope."}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"Payment Required — Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"required_credits":{"type":"integer"},"available_credits":{"type":"integer"}}}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/agents/{id}/chat":{"post":{"tags":["Chat"],"summary":"Send a message to an agent","description":"Sends a chat message to the agent. By default returns a sync JSON response with\nthe full assistant reply. Set `stream: true` to receive Server-Sent Events (SSE)\nwith incremental deltas.\n\n**Sessions**: If no `sessionKey` is provided, a new session is created with an\n`api:` prefix. Reuse the returned `sessionKey` to continue a conversation.\n\n**Billing**: Each message costs 1 credit (base) plus the LLM cost charged by the runtime.\n\nRequires `chat` scope on agent keys. Master keys have implicit access.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":32000,"description":"The user message to send to the agent."},"sessionKey":{"type":"string","maxLength":255,"pattern":"^api:[a-zA-Z0-9\\-]+$","description":"Reuse an existing session. Must start with `api:`. If omitted, a new\nsession key is generated automatically.\n"},"stream":{"type":"boolean","default":false,"description":"If `true`, the response is an SSE stream (`text/event-stream`).\nIf `false` (default), waits for the full response and returns JSON.\n"}}}}}},"responses":{"200":{"description":"Sync response with the full assistant message","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"sessionKey":{"type":"string"},"message":{"type":"object","properties":{"role":{"type":"string"},"content":{"type":"string"}}}}}}}},"text/event-stream":{"schema":{"type":"string","description":"SSE stream (when `stream: true`). Events:\n- `{\"type\":\"session\",\"sessionKey\":\"api:...\"}` — first event\n- Gateway events forwarded as-is (deltas, tool calls, etc.)\n- `{\"type\":\"done\",\"sessionKey\":\"api:...\"}` — terminal event\n"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/ScopeForbidden"},"404":{"description":"Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Agent is not running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"502":{"description":"Gateway error — agent is unreachable or returned an error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
