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. 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 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:
["new_metric_1"]
​
test_set_ids
string[] | null

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

Example:
["new_testset_1"]

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.