Queues

Routing a call to whichever member is free, and why it chose whom it did.

List queues, by slug

GET /v1/queues

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute

Parameters

Name	In	Type	Description
limit?	query	integer	1–100. Default 20.
cursor?	query	string	The nextCursor of the previous page. 1–512 characters.

Response 200 — A page of queues.

Field	Type	Description
data	Queue[]
nextCursor	string | null	The cursor for the next page; null on the last.

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
429	rate_limited
500	internal

---

Create a queue

POST /v1/queues

A slug unique within the application, a strategy (default fair_share) and its settings. voicemail overflow is refused until the platform records calls. Audited.

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute

Request body application/json

Field	Type	Description
strategy?	string	One of fair_share, round_robin, longest_idle, least_busy, skill_priority, pinned.
ringTimeoutSec?	integer	5–120. Default 30.
redirectDelayMs?	integer	0–60000. Default 2000.
maxAttempts?	integer	1–100. Default 20.
maxWaitSec?	integer	10–3600. Default 300.
overflowAction?	string	voicemail is in the schema and refused until the platform records calls. One of fail, webhook, push_offline_agents.
settings?	QueueSettings
slug	string	Matches ^[a-z0-9][a-z0-9_-]{0,62}$.

Response 201 — The queue.

Field	Type	Description
id	string (uuid)
slug	string
strategy	string	One of fair_share, round_robin, longest_idle, least_busy, skill_priority, pinned.
ringTimeoutSec	integer
redirectDelayMs	integer
maxAttempts	integer
maxWaitSec	integer
overflowAction	string	voicemail is in the schema and refused until the platform records calls. One of fail, webhook, push_offline_agents.
settings	QueueSettings
createdAt	string (date-time)
updatedAt	string (date-time)

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
409	conflict, room_full, room_closed, duplicate_identity, already_answered
413	payload_too_large
429	rate_limited
500	internal

---

Read a queue

GET /v1/queues/{id}

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute

Parameters

Name	In	Type	Description
id	path	string (uuid)

Response 200 — The queue.

Field	Type	Description
id	string (uuid)
slug	string
strategy	string	One of fair_share, round_robin, longest_idle, least_busy, skill_priority, pinned.
ringTimeoutSec	integer
redirectDelayMs	integer
maxAttempts	integer
maxWaitSec	integer
overflowAction	string	voicemail is in the schema and refused until the platform records calls. One of fail, webhook, push_offline_agents.
settings	QueueSettings
createdAt	string (date-time)
updatedAt	string (date-time)

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
429	rate_limited
500	internal

---

Change a queue's strategy, timings or overflow

PATCH /v1/queues/{id}

Applies from each entry's next attempt, waiting entries included. settings, when given, replaces the settings whole. Audited: before and after.

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute

Parameters

Name	In	Type	Description
id	path	string (uuid)

Request body application/json

Field	Type	Description
strategy?	string	One of fair_share, round_robin, longest_idle, least_busy, skill_priority, pinned.
ringTimeoutSec?	integer	5–120. Default 30.
redirectDelayMs?	integer	0–60000. Default 2000.
maxAttempts?	integer	1–100. Default 20.
maxWaitSec?	integer	10–3600. Default 300.
overflowAction?	string	voicemail is in the schema and refused until the platform records calls. One of fail, webhook, push_offline_agents.
settings?	QueueSettings

Response 200 — The queue, as it now stands.

Field	Type	Description
id	string (uuid)
slug	string
strategy	string	One of fair_share, round_robin, longest_idle, least_busy, skill_priority, pinned.
ringTimeoutSec	integer
redirectDelayMs	integer
maxAttempts	integer
maxWaitSec	integer
overflowAction	string	voicemail is in the schema and refused until the platform records calls. One of fail, webhook, push_offline_agents.
settings	QueueSettings
createdAt	string (date-time)
updatedAt	string (date-time)

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
413	payload_too_large
429	rate_limited
500	internal

---

Remove a queue, its members and its line

DELETE /v1/queues/{id}

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute

Parameters

Name	In	Type	Description
id	path	string (uuid)

Response 204 — Removed.

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
429	rate_limited
500	internal

---

List members, by identity

GET /v1/queues/{id}/members

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute

Parameters

Name	In	Type	Description
id	path	string (uuid)
limit?	query	integer	1–100. Default 20.
cursor?	query	string	The nextCursor of the previous page. 1–512 characters.

Response 200 — A page of members.

Field	Type	Description
data	QueueMember[]
nextCursor	string | null	The cursor for the next page; null on the last.

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
429	rate_limited
500	internal

---

Add a member

POST /v1/queues/{id}/members

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute

Parameters

Name	In	Type	Description
id	path	string (uuid)

Request body application/json

Field	Type	Description
skills?	string[]	At most 32 items.
priority?	integer	0–100. Default 0.
pausedUntil?	string (date-time) | null
identity	string	1–200 characters.

Response 201 — The member.

Field	Type	Description
identity	string
skills	string[]
priority	integer	Lower is preferred.
pausedUntil	string (date-time) | null
createdAt	string (date-time)
updatedAt	string (date-time)

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
409	conflict, room_full, room_closed, duplicate_identity, already_answered
413	payload_too_large
429	rate_limited
500	internal

---

Pause, resume, re-skill or re-tier a member

PATCH /v1/queues/{id}/members/{identity}

pausedUntil pauses until then; null resumes. A paused member is never offered a call.

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute

Parameters

Name	In	Type	Description
id	path	string (uuid)
identity	path	string	The tenant's opaque identity string, URL-encoded. 1–200 characters.

Request body application/json

Field	Type	Description
skills?	string[]	At most 32 items.
priority?	integer	0–100. Default 0.
pausedUntil?	string (date-time) | null

Response 200 — The member, as it now stands.

Field	Type	Description
identity	string
skills	string[]
priority	integer	Lower is preferred.
pausedUntil	string (date-time) | null
createdAt	string (date-time)
updatedAt	string (date-time)

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
413	payload_too_large
429	rate_limited
500	internal

---

Remove a member

DELETE /v1/queues/{id}/members/{identity}

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute

Parameters

Name	In	Type	Description
id	path	string (uuid)
identity	path	string	The tenant's opaque identity string, URL-encoded. 1–200 characters.

Response 204 — Removed.

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
429	rate_limited
500	internal

---

The line, oldest first, and what became of each entry

GET /v1/queues/{id}/entries

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute

Parameters

Name	In	Type	Description
id	path	string (uuid)
limit?	query	integer	1–100. Default 20.
cursor?	query	string	The nextCursor of the previous page. 1–512 characters.
state?	query	string	One of waiting, assigned, abandoned, overflowed, no_agents.

Response 200 — A page of entries.

Field	Type	Description
data	QueueEntry[]
nextCursor	string | null	The cursor for the next page; null on the last.

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
429	rate_limited
500	internal

---

The line now, and how today’s entries ended (UTC)

GET /v1/queues/{id}/stats

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute

Parameters

Name	In	Type	Description
id	path	string (uuid)

Response 200 — The statistics.

Field	Type	Description
waiting	integer
oldestWaitingSince	string (date-time) | null
members	integer
online	integer
eligibleNow	integer	Members a call could be offered to now.
today	object
today.assigned	integer
today.abandoned	integer
today.unanswered	integer	Ended with nobody eligible, or the loop spent.
today.averageWaitSec	number | null

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
429	rate_limited
500	internal

---

Rank the members for a caller, offering nothing

GET /v1/queues/{id}/simulate

Runs the live selection on live inputs: every eligible member with its score broken down by factor, every excluded one with the rule that excluded it.

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute

Parameters

Name	In	Type	Description
id	path	string (uuid)
caller	query	string	The identity placing the call. 1–200 characters.
skills?	query	string	Comma-separated skills the call requires. At most 2048 characters.

Response 200 — The ranking a call would get now.

Field	Type	Description
queueId	string (uuid)
strategy	string	One of fair_share, round_robin, longest_idle, least_busy, skill_priority, pinned.
caller	string
requiredSkills	string[]
at	string (date-time)
decision	object
decision.kind	string	One of offer, overflow, exhausted.
decision.agent?	string
decision.action?	string
decision.reason?	string
ranked	object[]
ranked[].position	integer
ranked[].identity	string
ranked[].score	number	Lowest wins.
ranked[].factors	object
excluded	object[]
excluded[].identity	string
excluded[].reason	string	One of self, paused, offline, unavailable, busy, tried, skill_mismatch, not_pinned.

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
429	rate_limited
500	internal

---

Why one member scored what it did for a caller

GET /v1/queues/{id}/explain

Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute

Parameters

Name	In	Type	Description
id	path	string (uuid)
caller	query	string	The identity placing the call. 1–200 characters.
skills?	query	string	Comma-separated skills the call requires. At most 2048 characters.
agent	query	string	1–200 characters.

Response 200 — The member’s place and the inputs behind it.

Field	Type	Description
queueId	string (uuid)
strategy	string	One of fair_share, round_robin, longest_idle, least_busy, skill_priority, pinned.
caller	string
agent	string
at	string (date-time)
eligible	boolean
excludedBy	string | null	One of self, paused, offline, unavailable, busy, tried, skill_mismatch, not_pinned.
position	integer | null
of	integer	How many members are eligible.
score	number | null
factors	object | null
inputs	object
inputs.online	boolean
inputs.availability	string	What the person chose. Presence is what the platform sees. One of available, away, dnd.
inputs.activeCalls	integer
inputs.pausedUntil	string (date-time) | null
inputs.skills	string[]
inputs.priority	integer
inputs.lastAssignedAt	string (date-time) | null
inputs.completedToday	integer
inputs.rejectedCallerToday	boolean

Errors

Status	Code
400	validation_failed, token_ttl_too_long
401	unauthenticated, token_expired, token_replayed, token_not_yet_valid
403	permission_denied, app_suspended, quota_exhausted
404	not_found, room_not_found, identity_not_found
429	rate_limited
500	internal