Queues

8 endpoints. Every path below is relative to the API base URL and already includes the /api/v1 prefix — see conventions for authentication, pagination, errors and idempotency.

	Endpoint
GET	`/contact-center/queues`	List the tenant's call queues with live member and waiting counts, filterable by active flag and name search
POST	`/contact-center/queues`	Create a call queue, auto-generating a slug from the name when none is supplied
GET	`/contact-center/queues/{id}`	Fetch one queue's full configuration — routing, overflow, fallbacks, announcements and required skills
PATCH	`/contact-center/queues/{id}`	Update a queue's configuration and return its refreshed detailed representation
DELETE	`/contact-center/queues/{id}`	Delete a queue, refusing while callers are still waiting in it so no live call is stranded
GET	`/contact-center/queues/{id}/history`	Historical rollup for a date range (§16). Never scans raw events
GET	`/contact-center/queues/{id}/statistics`	Live counters for one queue (§16 realtime)
GET	`/contact-center/queues/overview`	Every queue's live tile — what the wallboard polls when websockets are down

Endpoints

List the tenant's call queues with live member and waiting counts, filterable by active flag and name search

GET/contact-center/queues

No scope is enforced in the handler — any valid key may call it.
Paging uses limit (default 50, capped at 200) and page query params, not per_page or cursor.

Query parameters

Name	Type	Required	Notes
`active`	boolean	—	default `false`
`search`	string	—

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/contact-center/queues?active=false&search=string" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/queues?active=false&search=string`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/queues?active=false&search=string');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/queues?active=false&search=string",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	`data`-wrapped array

Example response, generated from the schema:

json

{
  "data": {},
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "pages": 1
  }
}

Create a call queue, auto-generating a slug from the name when none is supplied

POST/contact-center/queues

Requires queue.write.
Returns 201, not 200. Permission is only enforced for session users; an API-key request has no user and skips the check.

cURLJavaScriptPHPPython

bash

curl -X POST "$CALLAGENT_API_URL/contact-center/queues" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/queues`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/queues');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.post(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/queues",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	JSON object

Errors

Status	When it happens
`403`	Session user lacks the queue.write permission
`422`	Validation failed on the queue payload

Fetch one queue's full configuration — routing, overflow, fallbacks, announcements and required skills

GET/contact-center/queues/{id}

No scope is enforced in the handler — any valid key may call it.

Path parameters

Name	Type	Required	Notes
`id`	string	yes

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/contact-center/queues/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/queues/01JQ0000000000000000000000`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/queues/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/queues/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	`data`-wrapped object

Errors

Status	When it happens
`404`	No queue with this id in the caller's tenant

Example response, generated from the schema:

json

{
  "data": {}
}

Update a queue's configuration and return its refreshed detailed representation

PATCH/contact-center/queues/{id}

Requires queue.write.

Path parameters

Name	Type	Required	Notes
`id`	string	yes

cURLJavaScriptPHPPython

bash

curl -X PATCH "$CALLAGENT_API_URL/contact-center/queues/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/queues/01JQ0000000000000000000000`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/queues/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.patch(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/queues/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	JSON object

Errors

Status	When it happens
`403`	Session user lacks the queue.write permission
`404`	No queue with this id in the caller's tenant
`422`	Validation failed on the queue payload

Delete a queue, refusing while callers are still waiting in it so no live call is stranded

DELETE/contact-center/queues/{id}

Requires queue.write.
This response is not data-wrapped.

Path parameters

Name	Type	Required	Notes
`id`	string	yes

cURLJavaScriptPHPPython

bash

curl -X DELETE "$CALLAGENT_API_URL/contact-center/queues/01JQ0000000000000000000000" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/queues/01JQ0000000000000000000000`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/queues/01JQ0000000000000000000000');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.delete(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/queues/01JQ0000000000000000000000",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	Bare JSON object, not `data`-wrapped

Errors

Status	When it happens
`403`	Session user lacks the queue.write permission
`404`	No queue with this id in the caller's tenant
`409`	The queue still has callers waiting

Historical rollup for a date range (§16). Never scans raw events

GET/contact-center/queues/{id}/history

No scope is enforced in the handler — any valid key may call it.
from and to are required query params; interval defaults to 15 and only accepts 15, 30, 60 or 1440.

Path parameters

Name	Type	Required	Notes
`id`	string	yes

Query parameters

Name	Type	Required	Notes
`from`	string	yes	date-time
`to`	string	yes	date-time
`interval`	`15` · `30` · `60` · `1440` · `null`	—

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/contact-center/queues/01JQ0000000000000000000000/history?from=%2B40712345678&to=%2B40712345678" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/queues/01JQ0000000000000000000000/history?from=%2B40712345678&to=%2B40712345678`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/queues/01JQ0000000000000000000000/history?from=%2B40712345678&to=%2B40712345678');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/queues/01JQ0000000000000000000000/history?from=%2B40712345678&to=%2B40712345678",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	`data`-wrapped object

Errors

Status	When it happens
`404`	No queue with this id in the caller's tenant
`422`	from/to missing or invalid, or interval is not 15, 30, 60 or 1440

Example response, generated from the schema:

json

{
  "data": {
    "offered": 1,
    "answered": 1,
    "abandoned": 1,
    "timed_out": 1,
    "overflowed": 1,
    "voicemail": 1,
    "callbacks_requested": 1,
    "transferred_out": 1,
    "abandonment_rate_percent": 1,
    "service_level_percent": 1,
    "average_wait_seconds": 30,
    "max_wait_seconds": 30,
    "average_handle_seconds": 30,
    "occupancy_percent": 1,
    "transfer_rate_percent": 1
  }
}

Live counters for one queue (§16 realtime)

GET/contact-center/queues/{id}/statistics

No scope is enforced in the handler — any valid key may call it.

Path parameters

Name	Type	Required	Notes
`id`	string	yes

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/contact-center/queues/01JQ0000000000000000000000/statistics" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/queues/01JQ0000000000000000000000/statistics`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/queues/01JQ0000000000000000000000/statistics');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/queues/01JQ0000000000000000000000/statistics",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	`data`-wrapped object

Errors

Status	When it happens
`404`	No queue with this id in the caller's tenant

Example response, generated from the schema:

json

{
  "data": {
    "queue_id": null,
    "queue_name": "Support Line",
    "waiting": 1,
    "longest_wait_seconds": {},
    "active": 1,
    "agents_logged_in": 1,
    "agents_available": 1,
    "agents_busy": 1,
    "offered_today": 1,
    "answered_today": 1,
    "abandoned_today": 1,
    "missed_today": 1,
    "overflowed_today": 1,
    "callbacks_pending": 1,
    "service_level_percent": 1,
    "service_level_target": 1,
    "abandonment_rate_percent": 1,
    "average_wait_seconds": 30,
    "max_wait_seconds": 30
  }
}

Every queue's live tile — what the wallboard polls when websockets are down

GET/contact-center/queues/overview

No scope is enforced in the handler — any valid key may call it.

cURLJavaScriptPHPPython

bash

curl -X GET "$CALLAGENT_API_URL/contact-center/queues/overview" \
  -H "Authorization: Bearer $CALLAGENT_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(`${process.env.CALLAGENT_API_URL}/contact-center/queues/overview`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CALLAGENT_API_KEY}`,
    Accept: 'application/json',
  },
});

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

php

<?php

$handle = curl_init(getenv('CALLAGENT_API_URL') . '/contact-center/queues/overview');

curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('CALLAGENT_API_KEY'),
        'Accept: application/json',
    ],
]);

$body = json_decode(curl_exec($handle), true);
$status = curl_getinfo($handle, CURLINFO_HTTP_CODE);
curl_close($handle);

if ($status >= 400) {
    throw new RuntimeException("{$body['error']['type']}: {$body['error']['message']}");
}

$data = $body['data'];

python

import os, requests

response = requests.get(
    f"{os.environ['CALLAGENT_API_URL']}/contact-center/queues/overview",
    headers={"Authorization": f"Bearer {os.environ['CALLAGENT_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
data = response.json()["data"]

Responses

Status	Body
`200`	`data`-wrapped object

Errors

Status	When it happens
`400`	No tenant is bound to the request context

Example response, generated from the schema:

json

{
  "data": {
    "waiting": 1,
    "longest_wait_seconds": 30,
    "active": 1,
    "agents_logged_in": 1,
    "agents_available": 1,
    "agents_busy": 1,
    "agents_paused": 1,
    "offered_today": 1,
    "answered_today": 1,
    "abandoned_today": 1,
    "callbacks_pending": 1,
    "service_level_percent": 1,
    "abandonment_rate_percent": 1,
    "queues": [
      {}
    ]
  }
}

Queues ​

Endpoints ​

List the tenant's call queues with live member and waiting counts, filterable by active flag and name search ​

Create a call queue, auto-generating a slug from the name when none is supplied ​

Fetch one queue's full configuration — routing, overflow, fallbacks, announcements and required skills ​

Update a queue's configuration and return its refreshed detailed representation ​

Delete a queue, refusing while callers are still waiting in it so no live call is stranded ​

Historical rollup for a date range (§16). Never scans raw events ​

Live counters for one queue (§16 realtime) ​

Every queue's live tile — what the wallboard polls when websockets are down ​

Queues

Endpoints

List the tenant's call queues with live member and waiting counts, filterable by active flag and name search

Create a call queue, auto-generating a slug from the name when none is supplied

Fetch one queue's full configuration — routing, overflow, fallbacks, announcements and required skills

Update a queue's configuration and return its refreshed detailed representation

Delete a queue, refusing while callers are still waiting in it so no live call is stranded

Historical rollup for a date range (§16). Never scans raw events

Live counters for one queue (§16 realtime)

Every queue's live tile — what the wallboard polls when websockets are down