Chat with agent (SSE streaming)

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Request Body

application/json

Chat request payload

TypeScript Definitions

Use the request body type in TypeScript.

ai_service_cookie?string

Session cookie for AI service affinity

capabilities?array<string>

Capability flags enabled for this request

compiled_system_prompt?string

Pre-compiled system prompt

continuation_token?string

Token for multi-turn continuation

game_context?object

Optional caller-specific game context (custom_fields, game_state_json)

instance_id?string

Optional agent instance identifier

interaction_role?string

Interaction role (owner or non_owner)

language?string

Language code (e.g. en, ja, zh)

max_turns?integer

Maximum agentic turns

messages*array<>

Conversation messages

model?string

LLM model override (playground)

provider?string

LLM provider override (playground)

request_type?string

Request type (chat, narrate, etc.)

retrieval_sync?boolean

Route retrieval through the full agentic pipeline (multi-query expansion + reranker + sufficiency loop) synchronously. Use when correctness matters more than TTFC: benchmarks (LongMemEval), dashboard debugging, tools where partial recall is worse than slow recall. Chat hot path defaults to the simpler single-shot planner.

session_id?string

Session identifier (auto-created if empty)

skill_levels?object

Per-skill level overrides keyed by skill name

skip_context_build?boolean

Skip context engine build

skip_server_history_cache?boolean

Skip the Platform's Redis session message cache (read AND write) for this turn. Set true when the caller is the authoritative source of conversation history (e.g., orchestrator-owned ScyllaDB transcript). Without this, caller-supplied history is double-loaded against the Platform's cache.

timezone?string

User IANA timezone (e.g. America/New_York)

tool_capabilities?object

Tool capability toggles (web_search, remember_name, image_generation)

tool_definitions?array<any>

Session-level custom tool definitions

user_display_name?string

Optional display name for the user

user_id?string

ID of the user chatting

Response Body

`text/event-stream`

`application/problem+json`

curl -X POST "https://loading/api/v1/agents/string/chat" \  -H "Content-Type: application/json" \  -d '{    "messages": [      {        "content": "string",        "role": "string"      }    ]  }'

{
  "$schema": "/api/v1/schemas/ChatSSEChunk.json",
  "build_duration_ms": 0,
  "choices": [
    {
      "delta": {
        "content": "string"
      },
      "finish_reason": "string",
      "index": 0
    }
  ],
  "data": null,
  "enriched_context": null,
  "error": {
    "message": "string"
  },
  "message_index": 0,
  "phase": "string",
  "side_effects": null,
  "tool": "string",
  "type": "string",
  "used_fast_path": true
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Queue an asynchronous chat request

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Request Body

application/json

Chat request payload

TypeScript Definitions

Use the request body type in TypeScript.

ai_service_cookie?string

Session cookie for AI service affinity

capabilities?array<string>

Capability flags enabled for this request

compiled_system_prompt?string

Pre-compiled system prompt

continuation_token?string

Token for multi-turn continuation

game_context?object

Optional caller-specific game context (custom_fields, game_state_json)

instance_id?string

Optional agent instance identifier

interaction_role?string

Interaction role (owner or non_owner)

language?string

Language code (e.g. en, ja, zh)

max_turns?integer

Maximum agentic turns

messages*array<>

Conversation messages

model?string

LLM model override (playground)

provider?string

LLM provider override (playground)

request_type?string

Request type (chat, narrate, etc.)

retrieval_sync?boolean

session_id?string

Session identifier (auto-created if empty)

skill_levels?object

Per-skill level overrides keyed by skill name

skip_context_build?boolean

Skip context engine build

skip_server_history_cache?boolean

timezone?string

User IANA timezone (e.g. America/New_York)

tool_capabilities?object

Tool capability toggles (web_search, remember_name, image_generation)

tool_definitions?array<any>

Session-level custom tool definitions

user_display_name?string

Optional display name for the user

user_id?string

ID of the user chatting

Response Body

`application/json`

curl -X POST "https://loading/api/v1/agents/string/chat/async" \  -H "Content-Type: application/json" \  -d '{    "messages": [      {        "content": "string",        "role": "string"      }    ]  }'

{
  "$schema": "/api/v1/schemas/AsyncChatStartOutputBody.json",
  "processing_id": "string",
  "status": "string"
}

Empty

Poll an async chat result

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

processingId*string

Processing ID returned by POST /chat/async

Response Body

`application/json`

`application/problem+json`

curl -X GET "https://loading/api/v1/agents/string/chat/result/string"

{
  "$schema": "/api/v1/schemas/AsyncChatResultOutputBody.json",
  "created_at": "2019-08-24T14:15:22Z",
  "error": "string",
  "phase": "string",
  "response": "string",
  "side_effects": null,
  "status": "string",
  "tool": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Playground chat with agent (SSE streaming)

Authorization

AuthorizationBearer <token>

API key issued to a Sonzai project. Format: Bearer sk_....

In: header

Path Parameters

agentId*string

Agent UUID or URL-encoded agent name

Request Body

application/json

Chat request payload

TypeScript Definitions

Use the request body type in TypeScript.

ai_service_cookie?string

Session cookie for AI service affinity

capabilities?array<string>

Capability flags enabled for this request

compiled_system_prompt?string

Pre-compiled system prompt

continuation_token?string

Token for multi-turn continuation

game_context?object

Optional caller-specific game context (custom_fields, game_state_json)

instance_id?string

Optional agent instance identifier

interaction_role?string

Interaction role (owner or non_owner)

language?string

Language code (e.g. en, ja, zh)

max_turns?integer

Maximum agentic turns

messages*array<>

Conversation messages

model?string

LLM model override (playground)

provider?string

LLM provider override (playground)

request_type?string

Request type (chat, narrate, etc.)

retrieval_sync?boolean

session_id?string

Session identifier (auto-created if empty)

skill_levels?object

Per-skill level overrides keyed by skill name

skip_context_build?boolean

Skip context engine build

skip_server_history_cache?boolean

timezone?string

User IANA timezone (e.g. America/New_York)

tool_capabilities?object

Tool capability toggles (web_search, remember_name, image_generation)

tool_definitions?array<any>

Session-level custom tool definitions

user_display_name?string

Optional display name for the user

user_id?string

ID of the user chatting

Response Body

`text/event-stream`

`application/problem+json`

curl -X POST "https://loading/api/v1/agents/string/playground/chat" \  -H "Content-Type: application/json" \  -d '{    "messages": [      {        "content": "string",        "role": "string"      }    ]  }'

{
  "$schema": "/api/v1/schemas/ChatSSEChunk.json",
  "build_duration_ms": 0,
  "choices": [
    {
      "delta": {
        "content": "string"
      },
      "finish_reason": "string",
      "index": 0
    }
  ],
  "data": null,
  "enriched_context": null,
  "error": {
    "message": "string"
  },
  "message_index": 0,
  "phase": "string",
  "side_effects": null,
  "tool": "string",
  "type": "string",
  "used_fast_path": true
}

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example"
}

Chat

200text/event-stream

defaultapplication/problem+json

200application/json

202

200application/json

defaultapplication/problem+json

200text/event-stream

defaultapplication/problem+json

`text/event-stream`

`application/problem+json`

`application/json`

`application/json`

`application/problem+json`

`text/event-stream`

`application/problem+json`