List schedules

# Copy for LLM

Returns a paginated list of the calling PBX's schedules. Requires the schedules scope on an Integrations API key (a user bearer token also passes). Multi-tenant scoping is enforced: only the caller's own schedules are ever returned, and no query parameter can widen that.

Results are sorted by name ascending unless sort says otherwise. Page size is per_page, capped at 100, which is also the default. Schedule steps (the time rules) are not embedded.

Authorization Parameters Headers

HTTP: bearerAuth

User bearer token. Default authentication for customer-facing endpoints. Obtain a token by calling POST /login with your credentials, then send it on every subsequent request as Authorization: Bearer <token>. The token inherits the permissions and PBX scope of the authenticated user.

HTTP Authorization Scheme

bearer

Bearer format

Bearer <token>

HTTP: IntegrationApiKey

API key created on the Cockpit Integrations page (an "API key" integration). It is a bearer token owned by the customer's PBX and limited to the scopes selected when the key was created (e.g. phone-numbers, push-configuration).

Send it in the Authorization header:

Authorization: Bearer <api_key>

Manage keys (create / reveal / revoke) from Integrations → New integration → API key.

HTTP Authorization Scheme

bearer

page query · integer

Page number to fetch. Defaults to `1`.

per_page query · integer

Items per page. Values above the maximum, or below 1, fall back to the maximum.

sort query · string

Field to sort by, `-` prefixed for descending. Allowed: `name`, `created_at`. Anything else responds 400.

enum: name -name created_at -created_at

filter[name] query · string

Partial, case-insensitive match on the schedule name.

filter[description] query · string

Partial, case-insensitive match on the schedule description.

accept header · string

example: application/json

Responses

200 400 401 403 422 429 5XX

Response schema

Expand allCollapse all

dataarray<object>

Each item — Named schedule belonging to a single tenant (Pbx). A schedule groups a set of time-of-day rules that downstream call flows reference to decide routing based on the current date and time (for example, open versus closed hours). The actual rules live on the related `ScheduleStep` records (one schedule may contain many steps covering days-of-the-week, fixed dates, recurring dates, or specific periods); those steps are not embedded in this response and are retrieved through their own endpoints.

id*string · uuid

Unique identifier of the schedule.

read-only

example: 550e8400-e29b-41d4-a716-446655440000

pbx_id*string · uuid

Identifier of the owning tenant (Pbx). Every schedule is scoped to exactly one tenant.

example: 550e8400-e29b-41d4-a716-446655440001

name*string

Human-readable label for the schedule, shown in the cockpit and used when selecting the schedule in call flows.

length: 0–255

example: Business hours

descriptionstring | null

Optional free-text note describing the purpose or coverage of the schedule. Null when no description was provided.

length: 0–255

example: Monday to Friday, 09:00 to 18:00

created_atstring | null · date-time

Timestamp (ISO 8601, UTC) when the schedule was created.

read-only

example: 2024-03-01T08:29:07Z

updated_atstring | null · date-time

Timestamp (ISO 8601, UTC) when the schedule was last modified.

read-only

example: 2024-03-01T08:29:07Z

linksobject

firststring

The first page of the resource

example: http://localhost/api/v1/resources?page=1

laststring

The last page of the resource

example: http://localhost/api/v1/resources?page=1

prevnull | string

The previous page of the resource

nextnull | string

The next page of the resource

metaobject

current_pageinteger

The current page of the resource

≥ 1

example: 1

fromnull | integer

The first item of the resource

≥ 1

example: 1

last_pageinteger

The last page of the resource

≥ 1

example: 1

linksarray<object>

urlstring | null

The url of the resource (null for the boundary prev/next links)

example: http://localhost/api/v1/resources?page=1

labelstring

The label of the resource

example: first

activeboolean

The status of the resource

example: 1

pathstring

The path of the resource

example: http://localhost/api/v1/resources

per_pageinteger

The number of items per page of the resource

≥ 1

example: 15

tonull | integer

The last item of the resource

≥ 1

example: 1

totalinteger

The total number of items of the resource

≥ 0

example: 1

Bad Request. A `filter[...]` key or a `sort` field that the endpoint does not allow was requested. The message names the allowed values. Nothing is returned and no partial result is produced: correct the query string and retry.

Response schema

messagestring

Unauthenticated. The `Authorization: Bearer <token>` header was missing, malformed, or names a token that has been revoked or deleted.

Response schema

messagestring

Forbidden. The bearer token authenticated successfully but does not carry the scope this endpoint requires. Re-create the Integrations API key with the missing scope selected (Integrations > New integration > API key).

Response schema

messagestring

Unprocessable Parameters. This error is returned when a parameter is not valid.

Response schema

Expand allCollapse all

messagestring

example: The given data was invalid.

errorsobject

filterarray<string>

[]string

sortarray<string>

[]string

pagearray<string>

[]string

per_pagearray<string>

[]string

Too Many Requests. The rate limit for this action has been exceeded. Retry after the window indicated by the Retry-After header.

Response schema

messagestring

Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue.

Response schema

messagestring

exceptionstring

Only present in non-production environments.

filestring

Only present in non-production environments.

lineinteger

Only present in non-production environments.

get https://cockpit.voxbi.com/api/v1/schedules

Base URL The production API server The staging API server The development API server

Request sample cURL JavaScript Python PHP

Copy

curl -X GET 'https://cockpit.voxbi.com/api/v1/schedules' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Copy

const response = await fetch('https://cockpit.voxbi.com/api/v1/schedules', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
});

const data = await response.json();
console.log(data);

Copy

import requests

response = requests.get('https://cockpit.voxbi.com/api/v1/schedules',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'}
)
response.raise_for_status()
data = response.json()
print(data)

Copy

<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'GET',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/schedules', false, $context);
$data = json_decode($response, true);
print_r($data);

Sample response Response headers

Expand all Collapse all Copy

{ … }

"data": [ … ],

{ … },

"id": "550e8400-e29b-41d4-a716-446655440000",

"pbx_id": "550e8400-e29b-41d4-a716-446655440001",

"name": "Business hours",

"description": "Monday to Friday, 09:00 to 18:00",

"created_at": "2024-03-01T08:29:07.000000Z",

"updated_at": "2024-03-01T08:29:07.000000Z"

},

{ … }

"id": "550e8400-e29b-41d4-a716-446655440002",

"pbx_id": "550e8400-e29b-41d4-a716-446655440001",

"name": "Holiday schedule",

"description": null,

"created_at": "2024-03-04T11:02:55.000000Z",

"updated_at": "2024-05-19T09:41:12.000000Z"

}

],

"links": { … },

"first": "https://cockpit.voxbi.com/api/v1/schedules?page=1",

"last": "https://cockpit.voxbi.com/api/v1/schedules?page=1",

"prev": null,

"next": null

},

"meta": { … }

"current_page": 1,

"from": 1,

"last_page": 1,

"path": "https://cockpit.voxbi.com/api/v1/schedules",

"per_page": 100,

"to": 2,

"total": 2

}

}

Host string

example: cockpit.voxbi.com

Date string

example: Mon, 16 Oct 2023 14:08:48 GMT

Connection string

example: close

Cache-Control string

example: no-cache, private

Content-Type string

example: application/json

X-RateLimit-Limit integer

example: 60

X-RateLimit-Remaining integer

example: 59

Vary string

example: Origin

Sample response Response headers

Expand all Collapse all Copy

{ … }

"message": "Requested filter(s) `owner` are not allowed. Allowed filter(s) are `name, description`."

}

Content-Type string

example: application/json

Sample response Response headers

Expand all Collapse all Copy

{ … }

"message": "Unauthenticated."

}

Content-Type string

example: application/json

Sample response Response headers

Expand all Collapse all Copy

{ … }

"message": "Invalid ability provided."

}

Content-Type string

example: application/json

Sample response Response headers

Expand all Collapse all Copy

{ … }

"errors": { … }

"filter": [ … ],

"The filter field must be an array."

],

"sort": [ … ],

"The sort field must be a string."

],

"page": [ … ],

"The page field must be an integer."

],

"per_page": [ … ]

"The per page field must be an integer."

]

}

}

Cache-Control string

example: private, must-revalidate

Connection string

example: keep-alive

Content-Type string

example: application/json

Vary string

example: Origin

X-RateLimit-Limit integer

Max requests allowed in the current rate-limit window.

example: 60

X-RateLimit-Remaining integer

Requests remaining in the current rate-limit window.

example: 57

Sample response Response headers

Expand all Collapse all Copy

{ … }

"message": "Too Many Attempts."

}

Retry-After integer

Seconds to wait before retrying.

example: 60

Content-Type string

example: application/json

Sample response

Expand all Collapse all Copy

{ … }

"message": "Server Error"

}