Agents

Update an agent

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).

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.
assistant_idstringOptional

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

phone_numberstringOptional

E.164 phone number the agent answers on / is called on. Required for internal agents that are tested over the phone.

conversation_typeenumOptionalDefaults to inbound

Call direction(s) this agent supports.

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.

transport_layer_web_callingenumOptional

Web-calling transport used to reach an internal agent over the web (mirrors the options in the dashboard). Omit it for phone-only agents.

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.

Response

Updated agent
idintegerOptional
client_idintegerOptional
namestringOptional
agent_sourceenumOptional

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

phone_numberstring or nullOptional
conversation_typeenumOptional
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
transport_layer_web_callingenum or nullOptional

Web-calling transport, or null for phone-only agents.

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