> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telzino.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update Agent Status
> Activate or deactivate an agent without resending its configuration
Use this endpoint to take an agent in or out of service. It is the lightweight alternative to [Update Agent](/api-reference/agents/update) 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](/api-reference/agents/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
The unique identifier of the agent (UUID format)
## Request Body
Agent activation status.
**Supported values:**
* `active` - Agent is available to receive calls
* `inactive` - 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](/api-reference/agents/update) instead.
```bash cURL theme={null}
curl -X PATCH https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000/status \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"status": "inactive"
}'
```
```javascript JavaScript theme={null}
const agentId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(
`https://api.telzino.com/v1/agents/${agentId}/status`,
{
method: 'PATCH',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({ status: 'inactive' })
}
);
const result = await response.json();
```
```python Python theme={null}
import requests
agent_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.patch(
f'https://api.telzino.com/v1/agents/{agent_id}/status',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'},
json={'status': 'inactive'}
)
result = response.json()
```
```json 200 theme={null}
{
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Front Desk",
"status": "inactive",
"provider": "livekit",
"organization_id": "987fcdeb-51a2-43f1-9876-543210987654",
"sip_registration_data": {
"sipDomain": "sip.example.com",
"username": "1001",
"port": 5060,
"transport": "udp",
"registrationEnabled": false,
"extension": "1001"
},
"updated_at": "2026-08-05T10:31:07.412Z"
}
}
```
```json 400 theme={null}
{
"error": "Invalid request data",
"details": [
{
"received": "cancelled",
"code": "invalid_enum_value",
"options": ["active", "inactive"],
"path": ["status"],
"message": "status must be 'active' or 'inactive' (use PUT /v1/agents/{agentId} to set 'cancelled' or 'pending')"
}
]
}
```
```json 404 theme={null}
{
"error": "not_found",
"error_description": "Agent not found or access denied"
}
```
```json 409 theme={null}
{
"error": "conflict",
"error_description": "Agent is cancelled and cannot be reactivated through this endpoint"
}
```
## Behavior
**The response is the full agent object**, the same shape [Get Agent](/api-reference/agents/get) returns. Secret fields (integration passwords and tokens, SIP password) are never included.
**SIP registration follows the status.** If the agent has SIP registration configured, its `registrationEnabled` flag is written in the same operation:
| Request | `status` | SIP registration |
| ------------------------ | ---------- | ---------------------------------------------- |
| `{"status": "inactive"}` | `inactive` | Deregistered — the agent stops receiving calls |
| `{"status": "active"}` | `active` | Registered again |
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](/api-reference/agents/toggle-sip-registration). Use [Get SIP Registration Status](/api-reference/agents/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](/api-reference/agents/update) if you genuinely need to reactivate one.
**LiveKit agents only.** Agents on other providers return `403`, matching [Update Agent](/api-reference/agents/update).
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:
```bash theme={null}
# Pause
curl -X PATCH https://api.telzino.com/v1/agents/{agentId}/status \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status": "inactive"}'
# Resume
curl -X PATCH https://api.telzino.com/v1/agents/{agentId}/status \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"status": "active"}'
```
### Activate after provisioning
An agent created through [Create Agent](/api-reference/agents/create) or the Portal can be configured while `pending` or `inactive` and switched on once its phone number, prompts, and integrations are ready.
## Troubleshooting
| Error | Cause | Solution |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` "status must be 'active' or 'inactive'" | Sent `cancelled`, `pending`, or an unrecognized value | Use [Update Agent](/api-reference/agents/update) for the other states |
| `400` "Invalid request data" with an `unrecognized_keys` detail | Extra fields in the body | This endpoint accepts `status` only — send other changes to [Update Agent](/api-reference/agents/update) |
| `403` "Cannot update vida agents via this API" | Agent is not a LiveKit agent | Only LiveKit agents can be updated through the API |
| `404` "Agent not found or access denied" | Wrong agent ID, or the agent belongs to another account | Verify the ID with [List Agents](/api-reference/agents/list) and check your access token |
| `409` "Agent is cancelled" | The agent was permanently disabled | Reactivate through [Update Agent](/api-reference/agents/update) |
| Agent set to `active` but still not taking calls | The agent has no SIP registration configured, so there was nothing to re-register | Configure it with [Set SIP Registration](/api-reference/agents/sip-registration), then check [Get SIP Registration Status](/api-reference/agents/sip-registration-status) |