Server integrations
Agents API reference
Manage Agents, mint short-lived browser credentials for managed Agent sessions, and find the related conversation, document, calendar, transcription, and streaming-session routes. API keys and shared authentication errors are covered in the API reference.
Start here
Agent routes and regions
Agent routes use the same /v1 hosts and workspace API keys as the rest of the API. See the API reference for base URLs and the key setup steps.
Japan endpoints run the API and managed Agent in Tokyo. ASR and LLM provider locations depend on the selected provider; region selection does not move the database or guarantee Japan data residency.
For POST /v1/agents/:agentId/sessions, pass "region": "jp" or "region": "us"
to select the Agent runtime. Omit it to use that API endpoint's default. A region
change requires a new idempotency key. An unavailable selected region returns
an error. The Web Live settings offer the same Region selection.
Workspace API key
A permanent awp_ credential created in the Dashboard. Lives only on your backend; manages Agents and mints Agent session tokens.
Agent session tokens
Agent session tokens (15 minutes) let a browser start one managed conversation. Your backend mints them with the workspace key.
Reliability
Agent authentication errors
Agent routes use the shared error shape and the authentication and account errors. These codes are specific to Agents.
| Status · code | When it happens | Fix |
|---|---|---|
| 403 · capability_disabled | The workspace does not have Agents enabled — “The agents capability is disabled for this organization.” | Contact Narya to enable the capability for your workspace. |
| 403 · session_token_agent_mismatch | A session token was used to start a session for a different Agent than it was minted for. | Mint the token with the same agentId the browser connects to. |
Routes
Agent endpoint index
These routes cover Agents, managed sessions, and related products. Voice and TTS routes are listed in the API reference.
# Agents (workspace API key)
GET /v1/agents # latest published configurations
GET /v1/agents/drafts # editable drafts
POST /v1/agents
GET /v1/agents/{agentId} # latest publication
GET /v1/agents/{agentId}/draft # current editable draft
PATCH /v1/agents/{agentId}
DELETE /v1/agents/{agentId}
POST /v1/agents/{agentId}/publish
# Text conversations (workspace API key)
POST /v1/agents/{agentId}/messages
GET /v1/agents/{agentId}/messages
# Agent documents (workspace API key)
GET /v1/agents/{agentId}/documents
POST /v1/agents/{agentId}/documents
GET /v1/agents/{agentId}/documents/{documentId}
PUT /v1/agents/{agentId}/documents/{documentId}
DELETE /v1/agents/{agentId}/documents/{documentId}
# Google Calendar links (per end user)
POST /v1/google-calendar/oauth-requests
GET /v1/google-calendar/connections/{endUserId}
DELETE /v1/google-calendar/connections/{endUserId}
# Agent sessions
POST /v1/agents/{agentId}/session-tokens # key → 15-minute browser token
POST /v1/agents/{agentId}/sessions # session token (SDK calls this)
GET /v1/agent-sessions/{sessionId} # workspace API key
# Avatar catalog
GET /v1/avatars
GET /v1/avatars/{avatarId}/preview
# Realtime transcription & translation
POST /v1/realtime-transcription-tokens # key → 2-minute browser token
WS /v1/realtime-transcription
GET /v1/realtime-transcription-sessions
GET /v1/realtime-transcription-sessions/{sessionId}
POST /v1/realtime-translation-preview # SSE preview
# Streaming session reporting
POST /v1/streaming-sessions
PATCH /v1/streaming-sessions/{sessionId}
POST /v1/streaming-sessions/{sessionId}/events
GET /v1/streaming-sessions
GET /v1/streaming-sessions/{sessionId}/eventsAgents
Look up Agents
Your backend resolves the human-chosen slug to the stable agent id once, then uses the id everywhere. Agent create, patch and read use character_card, a complete V3 envelope. Patching that field replaces the whole card. New integrations should use the V3 fields inside character_card.data. For existing /v1 clients, responses also derive display_name, description, persona, and instructions from the card. Legacy create and patch requests remain supported: these fields map to data.name, data.creator_notes, data.description, and data.system_prompt. Legacy partial updates preserve all other card fields; an explicit empty string clears the corresponding field. Do not mix legacy character fields with character_card in one write. Session rules belong to the published Agent; arbitrary legacy overrides.persona and overrides.systemPrompt are rejected. Installed Streamer Assistant clients remain compatible: the API converts their recognized systemPrompt envelope into validated broadcaster identity and dated-note context, discards its rule text, and retains the published Agent. New clients send context directly. Modern operator tests can use overrides.characterCard to replace the complete session card.
Agent GET and list responses use the latest published snapshot for every configuration field, including legacy character aliases. Unpublished Agents are omitted from the default list and return 409 agent_not_published on GET. The explicit /draft and /drafts routes return editable snapshots. Create and patch responses return the saved draft. draft_revision remains editing metadata, so a different revision from active_publication.revision never blocks runtime use.
curl https://aniwaffle.com/v1/agents \
--header 'Authorization: Bearer awp_your_key_here'{
"agents": [
{
"id": "22222222-2222-4222-8222-222222222222",
"slug": "support-guide",
"avatar_id": "reina",
"character_card": {
"spec": "chara_card_v3", "spec_version": "3.0",
"data": {
"name": "Customer Support Guide",
"description": "You are Sage, a calm customer support guide.",
"personality": "", "scenario": "", "first_mes": "", "mes_example": "",
"system_prompt": "Help customers understand their order status.",
"post_history_instructions": "", "alternate_greetings": [],
"creator_notes": "Order status and returns", "tags": [],
"creator": "", "character_version": "", "extensions": {},
"group_only_greetings": []
}
},
"voice_id": "0d9f1c3a5b7e4f0a9c1b3d5e7f902468",
"llm_provider": "anthropic",
"llm_model": "claude-sonnet-5",
"thinking_level": "low",
"web_search_enabled": true,
"memory_enabled": false,
"calendar_enabled": false,
"documents_enabled": false,
"draft_revision": { "id": "…", "version": 7 },
"active_publication": {
"id": "…",
"version": 2,
"revision": { "id": "…", "version": 6 },
"memory_enabled": false,
"calendar_enabled": false,
"documents_enabled": false,
"created_at": "2026-08-01T09:30:00.000Z"
},
"created_at": "2026-07-20T08:00:00.000Z",
"updated_at": "2026-08-01T09:30:00.000Z"
}
]
}An Agent without a public voice selection is omitted from the list, and fetching it directly returns 409 agent_not_api_ready. Open the Agent in the Dashboard, choose a TTS variant in its Voice section, save, and publish.
Managed realtime
Start an Agent session
Starting a conversation is two requests: your backend trades the workspace key for a short-lived token, and the browser SDK trades that token for a live session.
POST /v1/agents/22222222-2222-4222-8222-222222222222/session-tokens
Authorization: Bearer awp_your_key_here
Content-Type: application/json
{
"end_user_id": "55555555-5555-4555-8555-555555555555"
}HTTP/1.1 201 Created
Cache-Control: no-store
{
"token": "eyJvcmdhbml6YXRpb2…",
"expires_at": "2026-08-06T12:15:00.000Z",
"agent_id": "22222222-2222-4222-8222-222222222222",
"capabilities": {
"managed_voice_agent": true,
"transport": "webrtc"
}
}Usage credits
Agent session responses report usage.charge.credits. The legacy usage.charge.amount and currency: "USD" fields remain as deprecated v1 projections (amount = credits / 1000), not payment amounts. New clients should use credits. Update clients that reject unknown response fields before using the new response.