Agents
Update Agent Status
Activate or deactivate an agent without resending its configuration
PATCH
Use this endpoint to take an agent in or out of service. It is the lightweight alternative to Update Agent when the only thing changing is whether the agent is live — you send one field instead of the whole agent object, so there is no risk of overwriting configuration you did not intend to touch.
For an agent with SIP registration configured, this also takes the agent off and back on the SIP registrar, so
inactive genuinely stops incoming calls rather than only labelling the agent.
Path Parameters
string
required
The unique identifier of the agent (UUID format)
Request Body
string
required
Agent activation status.Supported values:
active- Agent is available to receive callsinactive- Agent is temporarily disabled
Only the two reversible states are accepted here.
cancelled (permanently disabled) and pending (awaiting activation) are rejected with a 400 — set those through Update Agent instead.Behavior
The response is the full agent object, the same shape Get Agent returns. Secret fields (integration passwords and tokens, SIP password) are never included. SIP registration follows the status. If the agent has SIP registration configured, itsregistrationEnabled flag is written in the same operation:
Every other SIP field — domain, username, password, proxy, transport — is preserved untouched. Agents without SIP registration simply have their status updated.
To move the registration flag on its own, leaving
status where it is, use Enable/Disable SIP Registration. Use Get SIP Registration Status to confirm what the registrar currently holds.
Safe to retry. Sending a status the agent already has, with its registration already in the matching state, returns 200 without changing anything — so a retry after a timeout cannot cause a double write or a spurious entry in the agent’s change history. If the two have drifted apart, the request repairs them even when the status itself does not change.
Applied immediately. The agent’s cached configuration is refreshed as part of the request, and the SIP sync service picks up the registration change over Supabase realtime. Calls already in progress are not interrupted.
Cancelled agents cannot be revived here. cancelled is a permanent state, so an agent already in it returns 409 rather than flipping back to active. Use Update Agent if you genuinely need to reactivate one.
LiveKit agents only. Agents on other providers return 403, matching Update Agent.
Plans are billed per agent, counted from agents in the
active state. Deactivating an agent removes it from that count at the next subscription sync rather than instantly, so the change may not appear on your subscription the moment the request returns.Common Uses
Take an agent offline temporarily
Pause an agent during a maintenance window, outside business hours, or between seasonal campaigns, then bring it back without re-sending prompts, voice settings, or integrations:Activate after provisioning
An agent created through Create Agent or the Portal can be configured whilepending or inactive and switched on once its phone number, prompts, and integrations are ready.
