API Reference
Queues

Replace a queue's settings

PUT
/v1/queues/{name}

API-key scope: queues.manage. Viewer members are refused (accounts.write_denied).

This is a FULL REPLACE, not a patch

An omitted setting RETURNS TO ITS DEFAULT — it does not keep the value the previous save left. The body you send is the queue you get. To change one setting, send every setting you want to keep along with it; GET /v1/queues/{name} first if you do not have them to hand.

Concretely: a queue saved with max_wait_seconds: 600 and then updated with a body of {"sharing_mode": "take_turns"} comes back with max_wait_seconds: 0 (hold indefinitely) and announce_position: false.

The ROSTER is the exception, because it is not part of this body at all: agents are untouched by an update and are replaced only through PUT /v1/queues/{name}/agents.

Queues cannot be renamed. name may be omitted from the body; if it is present it must equal the name in the path, and a mismatch is a 400 rather than a silently ignored rename.

Update-only: an unknown name is a 404, not an implicit create.

Authorization

bearerAuth
AuthorizationBearer <token>

Long-lived ES256 JWT minted from the dashboard (https://app.sautikit.com/developers/api-keys). Signed by the platform keyring. Carries workspace_id and scopes claims; revoked via the platform deny-list.

In: header

Path Parameters

name*string
Match^[A-Za-z0-9._-]{1,64}$

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The settings half of a queue — the body of POST /v1/queues and PUT /v1/queues/{name}. The roster is NOT here: it has its own endpoint, so a settings save cannot empty a team by omission.

On PUT this is a FULL REPLACE: an omitted field returns to the default listed below, it does not keep its previous value.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/v1/queues/string" \  -H "Content-Type: application/json" \  -d '{    "sharing_mode": "chosen_order",    "max_wait_seconds": 600,    "max_depth": 25,    "discard_abandoned_after_seconds": 60,    "announce_position": true,    "announce_frequency_seconds": 30  }'
{  "queue": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "sharing_mode": "longest_free",    "max_wait_seconds": 0,    "max_depth": 0,    "discard_abandoned_after_seconds": 0,    "announce_position": true,    "announce_frequency_seconds": 0,    "moh_url": "string",    "agents": [      {        "extension": "string",        "level": 0,        "position": 0      }    ],    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

Get one queue and its roster GET

**API-key scope:** `queues.read`.

Delete a queue DELETE

Deletes the queue and the bindings between it and its agents, then pushes the workspace to the phone system. **API-key scope:** `queues.manage`. Viewer members are refused (`accounts.write_denied`). The AGENTS SURVIVE: a person belongs to the workspace, not to one queue, and may still serve others. NOT idempotent: deleting a queue that is already gone is a `404`. Any number whose routing still points at this queue keeps pointing at a name that no longer exists — repoint it with `PUT /v1/numbers/{id}/routing` before deleting, or the next save will recreate the queue from that number's `queue` block.