> ## Documentation Index > Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create an agent > Connect it to an address with `POST /v2/agents/{agentId}/channels`. ## OpenAPI ````yaml /api-reference/v2/openapi.json post /v2/agents openapi: 3.0.3 info: title: Zavu API v2 version: 2.0.0 description: >- The second version of the Zavu API. It runs on the same engine as /v1: the same API keys, the same per-project rate limit, the same sending limits, prices and reviews. /v1 keeps working unchanged, and you can mix calls to both. **Addresses, not senders.** /v2 has no sender object. Where a message leaves from is named the way the recipient sees it: an E.164 number, an email address, `@botname` for Telegram, `@username` for Instagram, the Facebook Page id for Messenger, and the literal `sms_oneway` for one-way SMS (sent from shared numbers, never a number of your own). `GET /v2/channels` lists one entry per (address, type); a number that carries WhatsApp and SMS is two entries with the same address. **What else changes.** No `Zavu-Sender` header (`from` or `conversationId` instead); every send reports how it was routed; one project webhook carries every event; every error is `{code, message, details}` at the root. **Wrong method.** A path under `/v2/messages`, `/v2/conversations`, `/v2/contacts`, `/v2/channels`, `/v2/templates`, `/v2/campaigns`, `/v2/agents`, `/v2/webhook` or `/v2/email-domains` called with a method it does not take answers `405 method_not_allowed`, with `details.allowed` and an `Allow` header. **Money.** Every amount is USD, rounded to 6 decimals. servers: - url: https://api.zavu.dev security: - bearerAuth: [] tags: - name: Messages description: Send, list and read messages. - name: Conversations description: Inbox threads, one per contact across channels. - name: Contacts description: Contacts and the identifiers they are reached at. - name: Channels description: 'Where the project can send from: one entry per (address, type).' - name: Templates description: WhatsApp message templates. - name: Campaigns description: One message to many recipients. - name: Webhook description: The one project webhook for every event. - name: Agents description: AI agents and the addresses they answer on. - name: Numbers description: Search and buy phone numbers. - name: Email Domains description: Domains to send email from. - name: Functions description: Configure Zavu Functions. paths: /v2/agents: post: tags: - Agents summary: Create an agent description: Connect it to an address with `POST /v2/agents/{agentId}/channels`. operationId: createAgentV2 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentCreateStandaloneRequest' responses: '201': description: Created, disabled and connected to no channel. content: application/json: schema: type: object required: - agent properties: agent: $ref: '#/components/schemas/Agent' '400': description: >- A required field is missing or invalid. Every missing required field is listed, not the first (`details.errors`, e.g. `[{"path":["provider"],"message":"provider is required"},{"path":["model"],"message":"model is required"}]`). content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: AgentCreateStandaloneRequest: type: object description: >- Create an agent that exists on its own, disabled and connected to no channel. required: - name - provider - model - systemPrompt properties: name: type: string maxLength: 100 provider: $ref: '#/components/schemas/AgentProvider' apiKey: type: string description: >- Your key for the model provider. Required for `openai`, `anthropic`, `google` and `mistral`, where a request without it is refused with `400`; not used with `zavu`. Stored encrypted and never returned. model: type: string systemPrompt: type: string maxLength: 10000 contextWindowMessages: type: integer minimum: 1 maximum: 50 default: 10 includeContactMetadata: type: boolean default: true triggerOnChannels: type: array items: type: string default: - '*' triggerOnMessageTypes: type: array items: type: string default: - text maxTokens: type: integer minimum: 1 maximum: 4096 temperature: type: number minimum: 0 maximum: 2 voice: $ref: '#/components/schemas/AgentVoiceConfig' Agent: type: object description: An AI agent. It answers on the addresses in `channels`. required: - id - name - enabled - provider - model - systemPrompt - createdAt - updatedAt - channels properties: id: type: string example: agent_abc123 name: type: string example: Customer Support Agent enabled: type: boolean description: Whether the agent is active. provider: $ref: '#/components/schemas/AgentProvider' model: type: string description: Model ID (e.g., gpt-4o-mini, claude-3-5-sonnet). example: gpt-4o-mini systemPrompt: type: string description: System prompt for the agent. contextWindowMessages: type: integer description: Number of previous messages to include as context. default: 10 includeContactMetadata: type: boolean description: Whether to include contact metadata in context. default: true maxTokens: type: integer description: Maximum tokens for LLM response. nullable: true temperature: type: number description: LLM temperature (0-2). nullable: true triggerOnChannels: type: array items: type: string description: Channels that trigger the agent. example: - sms - whatsapp triggerOnMessageTypes: type: array items: type: string description: Message types that trigger the agent. example: - text stats: type: object properties: totalInvocations: type: integer totalTokensUsed: type: integer totalCost: type: number description: Total cost in USD. createdAt: type: string format: date-time updatedAt: type: string format: date-time voice: $ref: '#/components/schemas/AgentVoiceConfig' description: >- Voice Agent configuration. When present and enabled, the agent can answer inbound phone calls and place outbound calls with Zavu's managed voice pipeline. Requires the Voice Agents feature to be enabled for your team. channels: type: array description: >- The (address, type) entries this agent answers on: every transport of the addresses it is connected to that its `triggerOnChannels` allows. Connect one with `POST /v2/agents/{agentId}/channels`. items: type: object required: - address - type - active properties: address: type: string type: $ref: '#/components/schemas/ChannelType' active: type: boolean Error: type: object required: - code - message description: >- Every v2 error has this shape at the root. There is no `{error: {...}}` wrapper anywhere in v2. A missing resource is `404 not_found` with the message ` not found`; an address the project does not have is `404 not_found`, `None of this project's channels has the address
.`, with the address in `details` under the name the request used (`from` or `address`). A `message` is written for the caller and never carries a stack trace or a source path. A body that is not JSON is `400 invalid_json`, with `details.errors` (`path: []`, the parse error in `message`). properties: code: type: string example: invalid_request message: type: string details: type: object additionalProperties: true description: >- Machine-readable context. Keys that mean the same thing everywhere: - `errors`: present on every `400 invalid_request` for an invalid body or query parameter, `[{path, message, ...}]`, `path` naming the field (`["to"]`, `["contacts", 2, "recipient"]`, `["limit"]`). - `recommendation`: one sentence saying what to do next. - `dashboardUrl`: the dashboard screen that fixes it. - `connect`: on `409 no_channel`, the channels this project can connect to reach the recipient, each `{type, request, note, available, dashboardUrl?}`; `request` is the exact call (`POST /v2/channels` with its body, or `POST /v2/numbers`), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). `available: false` says why in `note` (one-way SMS closed until business verification is approved). - `address` / `from`: the address the error is about, under the name the request used for it. properties: errors: type: array items: type: object required: - path - message properties: path: type: array items: oneOf: - type: string - type: integer message: type: string code: type: string additionalProperties: true AgentProvider: type: string description: LLM provider for the AI agent. enum: - openai - anthropic - google - mistral - zavu AgentVoiceConfig: type: object description: >- Voice Agent configuration on an AI agent. Controls how the agent behaves on inbound and outbound phone calls through Zavu's managed voice pipeline (speech recognition, the agent's LLM, and speech synthesis, with real-time interruption handling). Requires the Voice Agents feature to be enabled for your team. required: - enabled properties: enabled: type: boolean description: >- Whether the agent handles voice calls. When false, the voice agent does not answer calls and outbound calls are rejected. greeting: type: string description: >- Opening line the agent speaks when the call connects. If omitted, the agent waits for the caller to speak first. maxLength: 1000 example: Hi, thanks for calling Acme. How can I help you today? greetings: type: object additionalProperties: type: string description: >- Greeting per language, keyed by language code. Used when the caller's language differs from the one `greeting` is written in. example: es: Hola, soy Atlas. Preguntame lo que quieras. language: type: string description: >- BCP-47 language code used for both speech recognition and speech synthesis (e.g. `en`, `es`, `pt-BR`). Auto-detected from the recipient when omitted. example: en model: type: string description: >- Model that runs the conversation, co-located in the voice network for lowest latency. Independent of the model used for text messaging. Derived from the agent's text model when omitted. example: openai/gpt-4o sttProvider: type: string description: Speech-recognition provider. Uses the default when omitted. sttModel: type: string description: Speech-recognition model. Uses the default when omitted. ttsProvider: type: string description: Speech-synthesis provider. Uses the default when omitted. ttsVoiceId: type: string description: >- Identifier of the synthesized voice that speaks. Choose from the voices available in the dashboard. Uses a neutral default when omitted. example: aria voiceSpeed: type: number description: >- Speech rate. 1.0 is natural. Only honoured by voices that support rate control; ignored by the others. minimum: 0.5 maximum: 1.5 default: 1 interruptible: type: boolean description: >- Whether the caller can interrupt the agent while it is speaking (barge-in). When true, the agent stops talking as soon as the caller starts. default: true maxCallDurationMinutes: type: integer description: >- Hard limit on call length in minutes. The call ends automatically when reached. minimum: 1 maximum: 120 default: 15 maxIdleSeconds: type: integer description: How long the agent waits during silence before ending the call. minimum: 5 maximum: 300 default: 30 recordCalls: type: boolean description: Whether the call audio is recorded. voicemailAction: type: string description: >- What the agent does when an answering machine or voicemail is detected on an outbound call. enum: - hangup - leave_message default: hangup voicemailMessage: type: string description: >- Message spoken when `voicemailAction` is `leave_message`. Falls back to `greeting` when omitted. maxLength: 1000 transferPhoneNumber: type: string description: >- E.164 phone number the agent can transfer the call to. When set, the agent is given a transfer tool it can use to hand the call to a human. example: '+14155551234' ChannelType: type: string description: A transport a message travels on. enum: - sms - sms_oneway - whatsapp - telegram - email - instagram - messenger - voice securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.