Chat

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

Send a message to an agent

post

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.

Authorizations

AuthorizationstringRequired

API key sent as Bearer token. Two types:

• Master key (g_master_...): full access to all agents and endpoints.
• Agent key (g_agent_...): scoped to a single agent with specific permissions.

Path parameters

idstring · uuidRequired

Body

messagestring · max: 32000Required

The user message to send to the agent.

Example: What's the weather in Madrid?

sessionKeystring · max: 255Optional

Reuse an existing session. Must start with api:. If omitted, a new session key is generated automatically.

Example: api:550e8400-e29b-41d4-a716-446655440000Pattern: ^api:[a-zA-Z0-9\-]+$

streambooleanOptional

If true, the response is an SSE stream (text/event-stream). If false (default), waits for the full response and returns JSON.

Default: false

Responses

200

Sync response with the full assistant message

successbooleanOptionalExample: true

401

Unauthorized — Invalid or missing API key

application/json

402

Payment Required — Insufficient credits

application/json

403

Forbidden — Key lacks the required scope

application/json

404

Agent not found

application/json

409

Agent is not running

application/json

422

Validation error

application/json

502

Gateway error — agent is unreachable or returned an error

application/json

post/agents/{id}/chat

POST /api/v1/agents/{id}/chat HTTP/1.1
Host: api.guayaba.run
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 114

{
  "message": "What's the weather in Madrid?",
  "sessionKey": "api:550e8400-e29b-41d4-a716-446655440000",
  "stream": false
}

{
  "success": true,
  "data": {
    "sessionKey": "api:550e8400-e29b-41d4-a716-446655440000",
    "message": {
      "role": "assistant",
      "content": "The weather in Madrid is sunny, 24°C."
    }
  }
}