COcoval
Agents

Update agent

Update specific fields of an existing agent configuration.

patch/agents/{agent_id}

Request

  • Base URL
    https://api.coval.dev/v1
  • Auth
    API key in header x-api-key

Path parameters

agent_idstring required

Agent resource ID

Request body

display_namestring

Human-readable agent name

model_type'MODEL_TYPE_VOICE' | 'MODEL_TYPE_OUTBOUND_VOICE' | 'MODEL_TYPE_CHAT' | 'MODEL_TYPE_CHAT_A2A' | 'MODEL_TYPE_CHAT_WEBSOCKET' | 'MODEL_TYPE_EMAIL' | 'MODEL_TYPE_SMS' | 'MODEL_TYPE_WEBSOCKET' | 'MODEL_TYPE_SDK_WEBSOCKET' | 'MODEL_TYPE_LIVEKIT' | 'MODEL_TYPE_DAILY' | 'MODEL_TYPE_OPENAI_REALTIME' | 'MODEL_TYPE_GEMINI_REALTIME' | 'MODEL_TYPE_GROK_REALTIME' | 'MODEL_TYPE_DEEPGRAM_REALTIME'

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_EMAIL: Email-based text agents
  • 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_SDK_WEBSOCKET: Voice agents that connect outbound to the Cloudflare Durable Object relay using Coval Agent SDK.
  • MODEL_TYPE_LIVEKIT: LiveKit agents (requires metadata.generate_token_endpoint and metadata.livekit_url)
  • MODEL_TYPE_DAILY: Pipecat Cloud agents (requires metadata.pipecat_api_key and metadata.agent_name)
  • MODEL_TYPE_OPENAI_REALTIME: OpenAI Realtime voice-to-voice agents
  • MODEL_TYPE_GEMINI_REALTIME: Gemini Live voice-to-voice agents
  • MODEL_TYPE_GROK_REALTIME: Grok (xAI) Voice Agent voice-to-voice agents
  • MODEL_TYPE_DEEPGRAM_REALTIME: Deepgram Voice Agent voice-to-voice agents
phone_numberstring nullable

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

endpointstring nullable

Custom API endpoint URL

promptstring nullable

Agent instructions/system prompt

customer_agent_idstring

External identifier for the agent

languagestring nullable

Primary language for the agent

attributesobject nullable

Free-form agent attributes

metadataobject nullable

Simulator-specific configuration

workflowsobject nullable

Workflow configuration

metric_idsstring[] nullable

Associated metric IDs

test_set_idsstring[] nullable

Associated test set IDs

tagsstring[] nullable

Tags associated with the agent

Example request

{
  "display_name": "Updated Agent Name",
  "model_type": "MODEL_TYPE_VOICE",
  "phone_number": "+9876543210",
  "endpoint": "https://api.newexample.com/agent",
  "prompt": "Updated instructions...",
  "customer_agent_id": "my-support-agent",
  "language": "en",
  "attributes": {
    "company_name": "Acme Corp"
  },
  "metadata": {
    "key": "value"
  },
  "workflows": {
    "workflow": "config"
  },
  "metric_ids": [
    "abc123def456ghi789jklm"
  ],
  "test_set_ids": [
    "gT5wq2Hn"
  ],
  "tags": [
    "production"
  ]
}

Response

Agent updated successfully

Example response

{
  "agent": {
    "id": "abc123def456ghi789jklm",
    "customer_agent_id": "my-support-agent",
    "display_name": "Customer Support Agent",
    "model_type": "MODEL_TYPE_VOICE",
    "phone_number": "+1234567890",
    "endpoint": "https://api.example.com/agent",
    "prompt": "You are a helpful customer support agent...",
    "language": "en",
    "attributes": {
      "company_name": "Acme Corp",
      "tier": "enterprise"
    },
    "metadata": {
      "voice": "alloy",
      "model": "gpt-realtime-2"
    },
    "workflows": {},
    "metric_ids": [
      "abc123def456ghi789jklm",
      "def456ghi789jklmabc123"
    ],
    "test_set_ids": [
      "gT5wq2Hn"
    ],
    "knowledge_base_ids": [],
    "tags": [
      "production",
      "voice"
    ],
    "create_time": "2025-10-14T12:00:00Z",
    "update_time": "2025-10-15T14:30:00Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.