# 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"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.guayaba.run/documentation/api-reference/chat.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.