Create an agent

POST

Connect it to an address with POST /v2/agents/{agentId}/channels.

Authorization

Authorizationheaderrequired
Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json

namestringrequired
Limitsmax length 100
providerstringrequired
LLM provider for the AI agent.
One ofopenaianthropicgooglemistralzavu
apiKeystring
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.
modelstringrequired
systemPromptstringrequired
Limitsmax length 10000
contextWindowMessagesinteger
Default10
Limitsmin 1 · max 50
includeContactMetadataboolean
Defaulttrue
triggerOnChannelsstring[]
Default["*"]
triggerOnMessageTypesstring[]
Default["text"]
maxTokensinteger
Limitsmin 1 · max 4096
temperaturenumber
Limitsmin 0 · max 2
voiceobject
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.
17 properties
- enabledbooleanrequired
  Whether the agent handles voice calls. When false, the voice agent does not answer calls and outbound calls are rejected.
- greetingstring
  Opening line the agent speaks when the call connects. If omitted, the agent waits for the caller to speak first.
  Limitsmax length 1000
- greetingsobject
  Greeting per language, keyed by language code. Used when the caller's language differs from the one greeting is written in.
  1 properties
  - {key}string
- languagestring
  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.
- modelstring
  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.
- sttProviderstring
  Speech-recognition provider. Uses the default when omitted.
- sttModelstring
  Speech-recognition model. Uses the default when omitted.
- ttsProviderstring
  Speech-synthesis provider. Uses the default when omitted.
- ttsVoiceIdstring
  Identifier of the synthesized voice that speaks. Choose from the voices available in the dashboard. Uses a neutral default when omitted.
- voiceSpeednumber
  Speech rate. 1.0 is natural. Only honoured by voices that support rate control; ignored by the others.
  Default1
  Limitsmin 0.5 · max 1.5
- interruptibleboolean
  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.
  Defaulttrue
- maxCallDurationMinutesinteger
  Hard limit on call length in minutes. The call ends automatically when reached.
  Default15
  Limitsmin 1 · max 120
- maxIdleSecondsinteger
  How long the agent waits during silence before ending the call.
  Default30
  Limitsmin 5 · max 300
- recordCallsboolean
  Whether the call audio is recorded.
- voicemailActionstring
  What the agent does when an answering machine or voicemail is detected on an outbound call.
  One ofhangupleave_message
  Defaulthangup
- voicemailMessagestring
  Message spoken when voicemailAction is leave_message. Falls back to greeting when omitted.
  Limitsmax length 1000
- transferPhoneNumberstring
  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.

Responses

201Created, disabled and connected to no channel.

agentobjectrequired
An AI agent. It answers on the addresses in channels.
17 properties
- idstringrequired
- namestringrequired
- enabledbooleanrequired
  Whether the agent is active.
- providerstringrequired
  LLM provider for the AI agent.
  One ofopenaianthropicgooglemistralzavu
- modelstringrequired
  Model ID (e.g., gpt-4o-mini, claude-3-5-sonnet).
- systemPromptstringrequired
  System prompt for the agent.
- contextWindowMessagesinteger
  Number of previous messages to include as context.
  Default10
- includeContactMetadataboolean
  Whether to include contact metadata in context.
  Defaulttrue
- maxTokensintegernullable
  Maximum tokens for LLM response.
- temperaturenumbernullable
  LLM temperature (0-2).
- triggerOnChannelsstring[]
  Channels that trigger the agent.
- triggerOnMessageTypesstring[]
  Message types that trigger the agent.
- statsobject
  3 properties
  - totalInvocationsinteger
  - totalTokensUsedinteger
  - totalCostnumber
    Total cost in USD.
- createdAtstring<date-time>required
- updatedAtstring<date-time>required
- voiceobject
  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.
  17 properties
  - enabledbooleanrequired
    Whether the agent handles voice calls. When false, the voice agent does not answer calls and outbound calls are rejected.
  - greetingstring
    Opening line the agent speaks when the call connects. If omitted, the agent waits for the caller to speak first.
    Limitsmax length 1000
  - greetingsobject
    Greeting per language, keyed by language code. Used when the caller's language differs from the one greeting is written in.
    1 properties
    {key}string
  - languagestring
    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.
  - modelstring
    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.
  - sttProviderstring
    Speech-recognition provider. Uses the default when omitted.
  - sttModelstring
    Speech-recognition model. Uses the default when omitted.
  - ttsProviderstring
    Speech-synthesis provider. Uses the default when omitted.
  - ttsVoiceIdstring
    Identifier of the synthesized voice that speaks. Choose from the voices available in the dashboard. Uses a neutral default when omitted.
  - voiceSpeednumber
    Speech rate. 1.0 is natural. Only honoured by voices that support rate control; ignored by the others.
    Default1
    Limitsmin 0.5 · max 1.5
  - interruptibleboolean
    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.
    Defaulttrue
  - maxCallDurationMinutesinteger
    Hard limit on call length in minutes. The call ends automatically when reached.
    Default15
    Limitsmin 1 · max 120
  - maxIdleSecondsinteger
    How long the agent waits during silence before ending the call.
    Default30
    Limitsmin 5 · max 300
  - recordCallsboolean
    Whether the call audio is recorded.
  - voicemailActionstring
    What the agent does when an answering machine or voicemail is detected on an outbound call.
    One ofhangupleave_message
    Defaulthangup
  - voicemailMessagestring
    Message spoken when voicemailAction is leave_message. Falls back to greeting when omitted.
    Limitsmax length 1000
  - transferPhoneNumberstring
    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.
- channelsobject[]required
  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.
  3 properties
  - addressstringrequired
  - typestringrequired
    A transport a message travels on.
    One ofsmssms_onewaywhatsapptelegramemailinstagrammessengervoice
  - activebooleanrequired

400A 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"}]`).

codestringrequired
messagestringrequired
detailsobject
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.
1 properties
- errorsobject[]
  3 properties
  - pathobject[]required
  - messagestringrequired
  - codestring

401Unauthorized.

codestringrequired
messagestringrequired
detailsobject
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.
1 properties
- errorsobject[]
  3 properties
  - pathobject[]required
  - messagestringrequired
  - codestring


curl -X POST "https://api.zavu.dev/v2/agents" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "provider": "openai",
  "model": "string",
  "systemPrompt": "string"
}'


{
  "agent": {
    "id": "agent_abc123",
    "name": "Customer Support Agent",
    "enabled": true,
    "provider": "openai",
    "model": "gpt-4o-mini",
    "systemPrompt": "string",
    "contextWindowMessages": 10,
    "includeContactMetadata": true,
    "maxTokens": 1,
    "temperature": 1,
    "triggerOnChannels": [
      "sms",
      "whatsapp"
    ],
    "triggerOnMessageTypes": [
      "text"
    ],
    "stats": {
      "totalInvocations": 1,
      "totalTokensUsed": 1,
      "totalCost": 1
    },
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-01T00:00:00Z",
    "voice": {
      "enabled": true,
      "greeting": "Hi, thanks for calling Acme. How can I help you today?",
      "greetings": {
        "es": "Hola, soy Atlas. Preguntame lo que quieras."
      },
      "language": "en",
      "model": "openai/gpt-4o",
      "sttProvider": "string",
      "sttModel": "string",
      "ttsProvider": "string",
      "ttsVoiceId": "aria",
      "voiceSpeed": 1,
      "interruptible": true,
      "maxCallDurationMinutes": 15,
      "maxIdleSeconds": 30,
      "recordCalls": true,
      "voicemailAction": "hangup",
      "voicemailMessage": "string",
      "transferPhoneNumber": "+14155551234"
    },
    "channels": [
      {
        "address": "string",
        "type": "sms",
        "active": true
      }
    ]
  }
}