Skip to navigation
Agents

Update an agent

Send only the fields you want to change. web_channel is merged key by key into the stored web channel (see WebChannel); send "web_channel": null to remove the web channel altogether.

Authentication

AuthorizationBearer

API key from RubricHQ Settings → API Keys. Send it as: Authorization: Bearer <YOUR_API_KEY>.

Path parameters

idintegerRequired

Query parameters

client_idintegerOptional

Optional. RubricHQ client (workspace) ID. Defaults to the workspace your API key belongs to; pass it only to target another workspace you can access.

Request

This endpoint expects an object.
namestringRequired

Human-readable agent name (shown in dashboard).

phone_numberstringRequired

Required. E.164 phone number the agent answers on / is called on. Its country code also selects the telephony carrier RubricHQ dials over (returned as telephony_carrier).

client_idintegerOptional

Optional. Client (workspace) to create the agent under. Defaults to the workspace your API key belongs to.

agent_sourceenumOptionalDefaults to internal

Where the agent under test comes from. Replaces the old integration_type / agent_kind fields.

  • internal — an agent you configure here in RubricHQ (you provide the prompt, language, opening message, and a phone number and/or web transport). This is the default.
  • external_vapi — an existing agent hosted on Vapi. Provide its assistant_id; instructions / language_id are pulled from Vapi.
  • external_retell — an existing agent hosted on Retell. Provide its assistant_id.
Allowed values:
assistant_idstringOptional

The external provider’s assistant/agent ID. Required when agent_source is external_vapi or external_retell; ignored for internal agents.

conversation_typeenumOptionalDefaults to inbound

Call direction(s) this agent supports.

Allowed values:
language_idintegerOptional

Language pack ID for the agent (required for internal agents). Call GET /languages to list the available languages and their IDs. For English (US) the language_id is 15.

instructionsstringOptional

System prompt / behavioral instructions for the agent LLM. Required for internal agents.

opening_messageobjectOptional

How the conversation starts (this is the “Opening Prompt” in the dashboard). Renamed from first_message.

web_channelobject or nullOptional

How RubricHQ reaches an internal agent over the web — the same settings as the “Web” channel card in the dashboard. Omit it for phone-only agents. On update it is merged into the stored channel; send null to remove the web channel.

max_call_durationintegerOptional10-3600

Hard cap on call length, in seconds. Runtime force-hangs up after this.

interruption_threshold_msintegerOptional
Milliseconds of caller speech that should trigger an interruption event.
disabled_metric_idslist of integersOptional

Metric IDs to skip when scoring this agent’s calls and runs — one unified list covering both built-in and custom metrics. Call GET /metrics to look up metric IDs.

transport_layer_web_callingenumOptionalDeprecated

Shorthand for web_channel.transport, kept for backwards compatibility. Prefer web_channel, which also carries the settings each transport needs — websocket in particular is rejected without a web_channel.websocket_url.

Allowed values:

Response

Updated agent
idintegerOptional
client_idintegerOptional
namestringOptional
agent_sourceenumOptional

Where the agent comes from (see CreateAgentRequest.agent_source).

Allowed values:
phone_numberstring or nullOptional
conversation_typeenumOptional
Allowed values:
language_idinteger or nullOptional
instructionsstring or nullOptional
opening_messageobject or nullOptional

The agent’s opening-message configuration (see CreateAgentRequest.opening_message).

max_call_durationinteger or nullOptional
interruption_threshold_msinteger or nullOptional
transport_layer_web_callingenum or nullOptional

Web-calling transport, or null for phone-only agents. Same value as web_channel.transport.

Allowed values:
web_channelobjectOptional

The agent’s web channel as stored, or null for a phone-only agent. Only the fields for the active transport are present. Credentials are never echoed: each key/secret is reported as a <name>_set boolean.

telephony_carrierstring or nullOptional

Read-only. The carrier RubricHQ dials this agent over, derived from the country code of phone_number.

disabled_metric_idslist of integersOptional

Metric IDs currently disabled for this agent (built-in + custom, unified).

created_atdatetimeOptional
updated_atdatetimeOptional

Errors

422
Unprocessable Entity Error