Replace a queue's agent roster
Replaces the queue's roster with the supplied extensions, IN ORDER, and pushes the workspace to the phone system.
API-key scope: queues.manage. Viewer members are refused
(accounts.write_denied).
A LIST, not a set: the order is what chosen_order means. It is
always stored, whatever the sharing mode, so switching modes later
keeps the order you set. Positions come back 1-based; every agent is
at level 1 (preference bands are not offered yet).
WHOLESALE REPLACE: an extension left out is unbound from this queue
and stops receiving its calls. The person is not deleted — they belong
to the workspace and may serve other queues. Sending {"agents": []}
empties the queue.
All-or-nothing: every extension is resolved BEFORE anything is written, so a typo in the fourth name leaves the roster exactly as it was rather than half-applied.
Each extension must be one with a LIVE LINE in this workspace — the devices that ring for it are resolved from your current records at save time, never taken from the request, so a re-enrolled app keeps ringing without a roster edit. A PSTN number is not an extension and cannot be a roster entry.
Setting somebody's roster does not change their ACD status: a person the switch has on a break stays on it.
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
Path Parameters
^[A-Za-z0-9._-]{1,64}$Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
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/agents" \ -H "Content-Type: application/json" \ -d '{ "agents": [ "1001", "1002", "1003" ] }'{ "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" }}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.
Mint a short-lived SIP JWT for the browser dialer POST
Workspace-scoped JWT consumed by the in-browser softphone to authenticate the WebSocket SIP registration. The response also carries the `endpoint`, `protocol` and ICE/TURN configuration the browser SDK needs — pass those through to the client rather than hard-coding them, so calling-infrastructure changes do not require a front-end release. Renew before `expiresIn` seconds elapse.