Skip to main content
POST
/
v1
/
agents
curl --request POST \ --url https://api.coval.dev/v1/agents \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <api-key>' \ --data ' { "display_name": "Customer Support Voice Agent", "model_type": "MODEL_TYPE_VOICE", "phone_number": "+12345678901", "prompt": "You are a helpful customer support agent...", "metadata": { "voice": "alloy", "model": "gpt-4o-realtime-preview" }, "workflows": { "edges": [ { "id": "edge-1", "source": "start", "target": "process-1" }, { "id": "edge-2", "source": "process-1", "target": "end" } ], "nodes": [ { "id": "start", "data": { "label": "Start", "description": "Agent is ready to handle a new call" }, "type": "start", "position": { "x": 250, "y": 0 } }, { "id": "process-1", "data": { "label": "Handle Call", "description": "Answer, greet, and assist the customer." }, "type": "process", "position": { "x": 250, "y": 150 } }, { "id": "end", "data": { "label": "End", "description": "Conclude the call politely." }, "type": "end", "position": { "x": 250, "y": 300 } } ] }, "metric_ids": [ "abc123def456ghi789jklm" ], "test_set_ids": [] } '
{ "agent": { "id": "abc123def456ghi789jklm", "display_name": "Customer Support Agent", "model_type": "MODEL_TYPE_VOICE", "phone_number": "+1234567890", "endpoint": null, "prompt": "You are a helpful customer support agent...", "metadata": { "voice": "alloy", "model": "gpt-4o-realtime-preview" }, "workflows": {}, "metric_ids": [ "abc123def456ghi789jklm" ], "test_set_ids": [], "knowledge_base_ids": [], "create_time": "2025-10-14T12:00:00Z", "update_time": null } }

Authorizations

​
X-API-Key
string
header
required

API key for authentication

Body

application/json
​
display_name
string
required

Human-readable agent name

Required string length: 1 - 200
Example:

"Customer Support Agent"

​
model_type
enum<string>
required

Agent type. 5 types are supported:

  • MODEL_TYPE_VOICE: Inbound voice calls (requires phone_number in E.164 format or SIP address)
  • MODEL_TYPE_OUTBOUND_VOICE: Outbound voice calls (requires endpoint webhook URL)
  • MODEL_TYPE_CHAT: Text-based chat agents (requires metadata.chat_endpoint)
  • MODEL_TYPE_SMS: SMS messaging agents (requires phone_number in E.164 format)
  • MODEL_TYPE_WEBSOCKET: WebSocket voice agents (requires metadata.endpoint wss:// URL and metadata.initialization_json)
Available options:
MODEL_TYPE_VOICE,
MODEL_TYPE_OUTBOUND_VOICE,
MODEL_TYPE_CHAT,
MODEL_TYPE_SMS,
MODEL_TYPE_WEBSOCKET
Example:

"MODEL_TYPE_VOICE"

​
phone_number
string | null

Phone number in E.164 format (e.g., +12345678901) or SIP address (e.g., sip:user@domain.com).

Required for:

  • MODEL_TYPE_VOICE agents (E.164 or SIP)
  • MODEL_TYPE_SMS agents (E.164 only)

Optional for other agent types.

Maximum string length: 200
Example:

"+12345678901"

​
endpoint
string | null

Webhook endpoint URL that Coval will POST to.

Required for MODEL_TYPE_OUTBOUND_VOICE agents. Must be a valid HTTP/HTTPS URL.

Maximum string length: 200
Example:

"https://api.yourcompany.com/triggers/voice-simulation"

​
prompt
string | null

Agent instructions/system prompt

Maximum string length: 50000
Example:

"You are a helpful customer support agent..."

​
metadata
object

Simulator-specific configuration (JSONB, max 10MB).

For CHAT agents:

Required:

  • chat_endpoint - Chat endpoint URL (validated, no private IPs/localhost)

Authentication:

  • authorization_header - Auth header (Bearer, X-API-Key, etc.)

Initialization:

  • initialization_endpoint - Init endpoint called before chat (validated URL)
  • initialization_payload - JSON payload for init request (max 16KB)

Custom Data:

  • custom_data - Organization/agent-level data (max 32KB JSON string)
  • custom_persona_data - Persona-specific data (max 16KB JSON string)

Headers & Format:

  • custom_headers - Additional headers with template variables (max 16KB JSON string)
  • response_format - "chat_completions" (default) or "responses"

Request/Response Processing:

  • input_template - Custom JSON template for requests (validated JSON)
  • payload_wrapper - Wrapper field name (e.g., "data", "request")
  • response_message_path - Dot notation path to extract message
  • strip_message_timestamps - Remove timestamp fields (boolean, default: false)

Tool Calls:

  • tool_call_extraction_config - Configuration for extracting tool calls from custom responses

Dynamic Configuration:

  • persona_id - Reference persona for parameter substitution (22-char ShortUUID)

Template Variables: {{sessionId}}, {{simulation_output_id}}, {{init_response.path}}, {{persona.field}}, {{messages}}, {{latest_message}}, {{custom_data.field}}

For OUTBOUND_VOICE agents:

  • trigger_call_headers - JSON string with HTTP headers
  • trigger_call_payload - JSON string with base payload
  • phone_number_key - Field name for phone number (default: "phone_number")

For WEBSOCKET agents:

Required:

  • endpoint - WebSocket endpoint URL (must be wss://, validated)
  • initialization_json - JSON string payload sent on connection

Authentication (optional):

  • authorization_header - Auth header sent during WebSocket handshake. Supports:
    • "Bearer <token>" → sent as Authorization: Bearer <token>
    • "X-API-Key <key>" → sent as X-API-Key: <key>
  • custom_headers - JSON string of additional HTTP headers for WebSocket handshake
Example:
{
  "chat_endpoint": "https://api.example.com/v1/chat",
  "authorization_header": "Bearer sk-xxx"
}
​
workflows
object

Workflow configuration (JSONB, max 10MB)

Example:
{}
​
metric_ids
string[]

Associated metric IDs (22-char IDs)

Pattern: ^[A-Za-z0-9]{22}$
Example:
["abc123def456ghi789jklm"]
​
test_set_ids
string[]

Associated test set IDs (22-char IDs)

Pattern: ^[A-Za-z0-9]{22}$
Example:
["xyz789uvw456rst123abcd"]

Response

Agent created successfully

​
agent
object
required

Agent configuration resource.

Note: The active field (soft delete status) is managed internally and not exposed in API responses.