Narya API reference
The Narya API manages Agents and catalogs, mints short-lived browser credentials, and generates speech. This page shows exactly where credentials come from and how the core requests look on the wire.
Start here
One API, two credential types
All public endpoints live under /v1 on the environment host. Product capabilities still determine which resources a workspace can use.
| Environment | Base URL |
|---|---|
| Production | https://animated-waffle.narya.ai |
| Development | https://animated-waffle-dev.narya.ai |
Workspace API key
A permanent awp_ credential created in the Dashboard. Lives only on your backend; manages resources and mints the short-lived tokens below.
Short-lived tokens
Agent session tokens (15 minutes) let a browser start one managed conversation. TTS stream tokens (2 minutes) open one streaming synthesis connection. Both are minted by your backend with the workspace key.
Credentials
Get an API key
Every request below authenticates with a workspace API key in the Authorization header. Here is exactly where that key comes from.
- 1
Open Integrations in the Dashboard
Sign in at /login, then select Integrations in the sidebar (under the Config group), or go directly to /operator/keys. The page is titled API keys. Only workspace Owners and Admins see it — other roles get “API key management requires an organization Owner or Admin.” - 2
Name and create the key
Enter a descriptive Label such ascheckout-voice-prodand select Create key. - 3
Copy the key immediately
A banner shows the full key exactly once: “Key created. Copy it now, it won’t be shown again.” The key starts withawp_. Only a hash is stored, so a lost key must be replaced, not recovered. - 4
Store it server-side
Put the key in your backend’s secret manager. Never ship it in browser or mobile code — browsers use short-lived tokens instead. The Issued keys table shows each key’s prefix, status, and last-used time, and a Revoke button that disables it immediately.
curl https://animated-waffle.narya.ai/v1/voices \
--header 'Authorization: Bearer awp_your_key_here' animated-waffle-dev.narya.ai, and a production key only against animated-waffle.narya.ai. Change the base URL and key together.Reliability
Authentication and account errors
Authentication and account failures share one JSON shape: { event: 'error', request_id, code, retryable, detail }. Match on code, not on detail text.
| Status · code | When it happens | Fix |
|---|---|---|
| 401 · unauthorized | The Authorization header is missing, the credential is not an awp_ key where one is required, or the key is unknown or revoked. | Send Authorization: Bearer awp_… with an active key from the Integrations page. Revocation takes effect immediately. |
| 403 · capability_disabled | The workspace does not have the required product enabled — e.g. “The agents capability is disabled for this organization.” | Contact Narya to enable the capability for your workspace. |
| 402 · insufficient_credit | The workspace has no remaining credit for billable usage. | Top up credit in the Dashboard (Usage & credits), then retry. |
| 403 · organization_suspended | The workspace is suspended. | Contact a platform administrator. |
| 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. |
Core products
Endpoint index
These are the primary public routes. The detailed TTS lifecycle lives in its own reference because it includes both HTTP and WebSocket contracts.
# Agents (workspace API key)
GET /v1/agents
POST /v1/agents
GET /v1/agents/{agentId}
PATCH /v1/agents/{agentId}
DELETE /v1/agents/{agentId}
POST /v1/agents/{agentId}/publish
# 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
# Voice and Avatar catalogs
GET /v1/voices
GET /v1/avatars
# Text to Speech
POST /v1/tts
POST /v1/tts/stream-tokens # key → 2-minute streaming token
WS /v1/tts/streamAgents
Look up Agents
Your backend resolves the human-chosen slug to the stable agent id once, then uses the id everywhere.
curl https://animated-waffle.narya.ai/v1/agents \
--header 'Authorization: Bearer awp_your_key_here'{
"agents": [
{
"id": "22222222-2222-4222-8222-222222222222",
"slug": "support-guide",
"display_name": "Customer Support Guide",
"description": "Order status and returns",
"avatar_id": "reina",
"voice_id": "0d9f1c3a5b7e4f0a9c1b3d5e7f902468",
"llm_provider": "anthropic",
"llm_model": "claude-sonnet-5",
"web_search_enabled": true,
"memory_enabled": false,
"calendar_enabled": false,
"draft_revision": { "id": "…", "version": 7 },
"active_publication": {
"id": "…",
"version": 2,
"revision": { "id": "…", "version": 6 },
"memory_enabled": false,
"calendar_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"
}
]
}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"
}
}Speech generation
Use the dedicated TTS reference for synthesis
The TTS reference covers voices, one-shot requests, streaming events, audio output, errors, limits, runnable examples, and the production checklist.
Open the TTS API reference