AI Voice Agents API

Use AI agent endpoints to create, list, read, update, pause, activate, and delete customer-scoped voice agents. Every request requires a MiniVoice API key. The API key determines the customer, so requests must not include customer_id.

Endpoints

Endpoint	Method	Purpose
/v1/ai/agents	GET	List AI agents for the authenticated customer.
/v1/ai/agents	POST	Create an AI agent.
/v1/ai/agents/:id	GET	Read one AI agent.
/v1/ai/agents/:id	PATCH	Update one AI agent.
/v1/ai/agents/:id	DELETE	Soft-delete one AI agent.
/v1/ai/agents/:id/activate	POST	Set an agent active.
/v1/ai/agents/:id/pause	POST	Set an agent paused.

Create Request

curl -sS https://api.minivoice.eu/v1/ai/agents \
  -X POST \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Sales Receptionist",
    "description": "Answers new inbound sales calls for a software company.",
    "greeting": "Thanks for calling Acme Software. Are you calling about sales or support?",
    "instructions": "Ask one question at a time. If the caller wants sales, collect company name and team size. If the caller wants support, transfer to the support destination.",
    "model": "gpt-4.1-mini",
    "voice": "nova",
    "language": "en",
    "runtime_limits": {
      "max_turns": 10,
      "max_call_seconds": 420,
      "silence_timeout_ms": 3000,
      "turn_recording_max_seconds": 10
    },
    "fallback_message": "I am having trouble continuing. I will connect you with the team."
  }'

Create Response

{
  "data": {
    "id": "agent_20260707T120000.000000000",
    "name": "Sales Receptionist",
    "status": "active",
    "is_active": true,
    "model": "gpt-4.1-mini",
    "voice": "nova",
    "language": "en",
    "greeting": "Thanks for calling Acme Software. Are you calling about sales or support?",
    "instructions": "Ask one question at a time. If the caller wants sales, collect company name and team size. If the caller wants support, transfer to the support destination.",
    "business_profile": "Answers new inbound sales calls for a software company.",
    "behavior_config": {
      "campaign_mode": false,
      "max_turn_latency_ms": 8000,
      "runtime_limits": {
        "max_turns": 10,
        "max_call_seconds": 420,
        "silence_timeout_ms": 3000,
        "turn_recording_max_seconds": 10
      },
      "fallback_message": "I am having trouble continuing. I will connect you with the team."
    },
    "tool_config": {
      "type": "",
      "target": "",
      "message": "I am having trouble continuing. I will connect you with the team.",
      "hangup_tool_description": "",
      "transfer_tool_description": "",
      "transfer_destinations": []
    },
    "description": "Answers new inbound sales calls for a software company.",
    "campaign_mode": false,
    "runtime_limits": {
      "max_turns": 10,
      "max_call_seconds": 420,
      "silence_timeout_ms": 3000,
      "turn_recording_max_seconds": 10
    },
    "created_at": "2026-07-07T12:00:00Z",
    "updated_at": "2026-07-07T12:00:00Z"
  }
}

Parameters

Field	Type	Required	Description
name	string	yes on create	Agent name. Must be at most 120 characters.
description	string	no	Public response field also returned as business_profile. Must be at most 1000 characters.
greeting	string	no	First message spoken to the caller. Alias for greeting_message. Must be at most 500 characters.
instructions	string	no	Agent prompt. Alias for system_prompt in requests, but public responses use instructions. Must be at most 8000 characters.
model	string	no	Defaults to gpt-4.1-mini. Must be one of the public model allowlist.
voice	string	no	Defaults to alloy. Must be one of the public voice allowlist.
language	string	no	Defaults to en. Must match a short language code such as en or en-US.
runtime_limits.max_turns	integer	no	Defaults to 5. Valid range is 1 to 20.
runtime_limits.max_call_seconds	integer	no	Defaults to 180. Valid range is 30 to 1800.
runtime_limits.silence_timeout_ms	integer	no	Defaults to 3000. Valid range is 1000 to 15000.
runtime_limits.turn_recording_max_seconds	integer	no	Defaults to 10. Valid range is 2 to 30.
max_turn_latency_ms	integer	no	Defaults to 8000. Valid range is 1000 to 60000.
is_active	boolean	no	Defaults to true on create. Paused agents cannot be used for DID routing or outbound AI calls.

Do not include customer_id or secret/provider configuration in public agent requests. The API key supplies customer scope, and unsupported configuration fields return unsupported_field.

Update Example

curl -sS https://api.minivoice.eu/v1/ai/agents/agent_20260707T120000.000000000 \
  -X PATCH \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "greeting": "Thanks for calling Acme Software. How can I route your call?",
    "runtime_limits": {
      "max_turns": 8,
      "max_call_seconds": 300
    }
  }'

PATCH preserves existing values for fields you omit. To pause without changing the rest of the agent, use the dedicated pause endpoint.

Pause and Activate

curl -sS https://api.minivoice.eu/v1/ai/agents/agent_20260707T120000.000000000/pause \
  -X POST \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

curl -sS https://api.minivoice.eu/v1/ai/agents/agent_20260707T120000.000000000/activate \
  -X POST \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

List Example

curl -sS 'https://api.minivoice.eu/v1/ai/agents?limit=25' \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

{
  "count": 1,
  "data": [
    {
      "id": "agent_20260707T120000.000000000",
      "name": "Sales Receptionist",
      "status": "active",
      "is_active": true,
      "model": "gpt-4.1-mini",
      "voice": "nova",
      "language": "en"
    }
  ]
}

Common Error

{
  "error": {
    "code": "invalid_model",
    "message": "model is not supported",
    "allowed_values": [
      "gpt-realtime-2",
      "gpt-4.1-mini",
      "gpt-4.1",
      "gpt-4o-mini",
      "gpt-4o"
    ]
  }
}

Testing

Create an agent with a short receptionist prompt. Fetch it by ID and verify that the response includes instructions but not an internal system_prompt field. Pause the agent and confirm that using it for a DID route or outbound AI call fails as unavailable. Activate it again before testing live calls.