Create a call-centre queue
Creates a queue and pushes the workspace's configuration to the phone system as part of the request.
API-key scope: queues.manage. Viewer members are refused
(accounts.write_denied).
Create-only: a name this workspace already uses is a 409, never a
silent overwrite. The queue is created EMPTY, the roster is set
separately, with PUT /v1/queues/{name}/agents, so a settings save can
never empty a team by omission.
Every setting is optional and every omitted setting takes its default;
see CallQueueSettings.
Authorization
bearerAuth 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
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 POST "https://example.com/v1/queues" \ -H "Content-Type: application/json" \ -d '{ "name": "support", "sharing_mode": "longest_free", "max_wait_seconds": 600, "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": "+254720000003" }}{ "error": { "code": "validation.bad_request", "message": "string", "request_id": "string", "details": [ "string" ], "resolution": "string", "reason": "invalid_characters", "suggested_e164": "+254720000003" }}{ "error": { "code": "validation.bad_request", "message": "string", "request_id": "string", "details": [ "string" ], "resolution": "string", "reason": "invalid_characters", "suggested_e164": "+254720000003" }}{ "error": { "code": "validation.bad_request", "message": "string", "request_id": "string", "details": [ "string" ], "resolution": "string", "reason": "invalid_characters", "suggested_e164": "+254720000003" }}{ "error": { "code": "validation.bad_request", "message": "string", "request_id": "string", "details": [ "string" ], "resolution": "string", "reason": "invalid_characters", "suggested_e164": "+254720000003" }}{ "error": { "code": "validation.bad_request", "message": "string", "request_id": "string", "details": [ "string" ], "resolution": "string", "reason": "invalid_characters", "suggested_e164": "+254720000003" }}List the workspace's call-centre queues GET
Every queue in the active workspace, each with the roster that serves it in the order the switch will try it. **API-key scope:** `queues.read`. The workspace is the authenticated one and nothing else: there is no workspace id in any path or body in this group, so another tenant's queue cannot be named. A queue name is BARE, the switch staples the workspace on itself. ## One console queue, several API queues The dashboard manages EXACTLY ONE queue per workspace, named after the workspace id. This API supports as many as you like, but the two surfaces meet at `PUT /v1/numbers/{id}/routing`: a `queue` block with `name` omitted defaults to the workspace-id queue, and saving it re-points that number and re-provisions the queue from the routing body (sharing mode, agent pool, announcements). So a colleague saving a number in the console can move that number off a queue you created here, and can overwrite the workspace-id queue's settings. If you manage queues through this API, set `queue.name` explicitly on every routing save.
Get one queue and its roster GET
**API-key scope:** `queues.read`.