Create agent

Persists a reusable voice persona — `systemPrompt`, optional `voice`, routing `intent`, and optional `llmOptions` — keyed by `name` within the authenticated organization. Pass the returned `id` as `agentId` on `POST /v1/sessions` to seed a session from this agent.

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Human-readable name. Must be unique within the organization — duplicates return 409.

Length1 <= length <= 120

systemPrompt*string

Initial agent instructions used as the session-level systemPrompt default.

Length1 <= length

voice?string

Default TTS voice id. Omit to let the router pick per provider.

intent*

Routing defaults stored on an agent row. Hydrated into a session's RoutingIntent when the session is created with agentId and no inline intent. Note: agents accept a smaller optimizeFor enum than the per-session RoutingIntent.

llmOptions?

Optional LLM tuning defaults stored on an agent. Strict object — only these three keys are accepted.

stackPreferences?

Per-agent stack preferences. Empty / missing layers leave the router unconstrained for that layer; failover stays active within the allowed set.

Response Body

`application/json`

{
  "id": "agent_01HW...",
  "organizationId": "string",
  "name": "string",
  "systemPrompt": "string",
  "voice": "string",
  "intent": {
    "language": "en-US",
    "optimizeFor": "latency"
  },
  "llmOptions": {
    "temperature": 0,
    "maxTokens": 1,
    "model": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "stackPreferences": {
    "allowedProviders": {
      "stt": [
        "deepgram"
      ],
      "llm": [
        "openai"
      ],
      "tts": [
        "elevenlabs"
      ]
    }
  }
}

{
  "error": "Invalid request body",
  "code": "VALIDATION_ERROR"
}

{
  "error": "Unauthorized",
  "code": "UNAUTHORIZED"
}

{
  "error": "Agent with this name already exists",
  "code": "AGENT_NAME_CONFLICT"
}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

409application/json

`application/json`

`application/json`

`application/json`

`application/json`