Skip to main content
PATCH
/
v1
/
agents
/
{agent_id}
curl --request PATCH \
  --url https://api.coval.dev/v1/agents/{agent_id} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "display_name": "Updated Agent Name",
  "prompt": "Updated instructions...",
  "metadata": {
    "updated": true
  }
}
'
{
  "agent": {
    "id": "abc123def456ghi789jklm",
    "display_name": "Updated Agent Name",
    "model_type": "MODEL_TYPE_VOICE",
    "phone_number": "+1234567890",
    "endpoint": "https://api.example.com/agent",
    "prompt": "Updated instructions...",
    "metadata": {
      "updated": true
    },
    "workflows": {},
    "metric_ids": [],
    "test_set_ids": [],
    "knowledge_base_ids": [],
    "create_time": "2025-10-14T12:00:00Z",
    "update_time": "2025-10-23T16:45:00Z"
  }
}

Authorizations

​
x-api-key
string
header
required

API key for authentication

Path Parameters

​
agent_id
string
required

Agent resource ID

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

Body

application/json

Partial update request (PATCH semantics - only provided fields are updated)

​
display_name
string

Human-readable agent name

Required string length: 1 - 200
Example:

"Updated Agent Name"

​
model_type
enum<string>

Agent type. Active types that can be created via the v1 API:

  • 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_CHAT_A2A: A2A JSON-RPC chat agents (requires metadata.chat_endpoint)
  • MODEL_TYPE_CHAT_WEBSOCKET: Text chat over WebSocket (requires metadata.endpoint in direct mode)
  • MODEL_TYPE_SMS: SMS messaging agents (requires phone_number in E.164 format)
  • MODEL_TYPE_WEBSOCKET: WebSocket voice agents (requires metadata.endpoint wss:// URL in direct mode; metadata.initialization_json is optional)
  • MODEL_TYPE_OPENAI_REALTIME: OpenAI Realtime voice-to-voice agents
  • MODEL_TYPE_GEMINI_REALTIME: Gemini Live voice-to-voice agents
Available options:
MODEL_TYPE_VOICE,
MODEL_TYPE_OUTBOUND_VOICE,
MODEL_TYPE_CHAT,
MODEL_TYPE_CHAT_A2A,
MODEL_TYPE_CHAT_WEBSOCKET,
MODEL_TYPE_SMS,
MODEL_TYPE_WEBSOCKET,
MODEL_TYPE_OPENAI_REALTIME,
MODEL_TYPE_GEMINI_REALTIME
Example:

"MODEL_TYPE_VOICE"

​
phone_number
string | null

Phone number in E.164 format or SIP address for voice/SMS agents

Maximum string length: 200
Example:

"+9876543210"

​
endpoint
string | null

Custom API endpoint URL

Maximum string length: 200
Example:

"https://api.newexample.com/agent"

​
prompt
string | null

Agent instructions/system prompt

Example:

"Updated instructions..."

​
metadata
object

Simulator-specific configuration (null = no change, {} = clear)

Example:
{ "key": "value" }
​
workflows
object

Workflow configuration (null = no change, {} = clear)

Example:
{ "workflow": "config" }
​
metric_ids
string[] | null

Associated metric IDs (null = no change, [] = clear)

Example:
["abc123def456ghi789jklm"]
​
test_set_ids
string[] | null

Associated test set IDs (null = no change, [] = clear)

Example:
["gT5wq2Hn"]
​
tags
string[] | null

Tags to associate with this agent. Null or omitted leaves tags unchanged. Pass [] to clear all tags.

Example:
["production"]

Response

Agent updated successfully

​
agent
object
required

Agent configuration resource.

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