List schedules

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, which defaults to 100 and is capped at 5000. Each schedule embeds its steps (the time rules), in the same shape the write endpoints accept.

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

Response schema

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 rules themselves are the schedule's `steps` (days of the week, fixed dates, recurring dates, specific periods), embedded in every response.

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

steps*array<object>

The schedule's time rules, the list on the cockpit edit page. Ordered by type (`days_of_the_week`, `fixed_dates`, `recurring_dates`, `specific_period`) and then by creation. Empty when the schedule has no steps, in which case it matches nothing.

Each item — One time rule of a schedule, as listed on the schedule's cockpit edit page. A call flow's schedule step matches when ANY enabled step of the schedule matches the current date and time. Every rule key is always present. Only the one that matches `type` is filled and the others are null: | `type` | Filled keys | |---|---| | `days_of_the_week` | `start_time`, `end_time`, `days_of_the_week` | | `fixed_dates` | `start_time`, `end_time`, `fixed_dates` | | `recurring_dates` | `start_time`, `end_time`, `recurring_dates` | | `specific_period` | `specific_period` (`start_time` and `end_time` are null) | This is the same shape the write endpoints accept in `steps`, so a client can read a schedule, edit its `steps` and send them back unchanged.

id*string · uuid

Unique identifier of the step. Send it back in `steps` to update this step instead of replacing it.

read-only

example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

type*string

Kind of rule. `days_of_the_week`: a weekly time window. `fixed_dates`: a time window on specific calendar dates. `recurring_dates`: a time window on the same day and month every year. `specific_period`: one continuous range between two date-times.

enum: days_of_the_week fixed_dates recurring_dates specific_period

example: days_of_the_week

status*string

A disabled step is kept but never matches.

enum: enabled disabled

example: enabled

start_time*string | null

Start of the daily window, 24-hour `HH:MM`, in the PBX's local time. Null for `specific_period`.

pattern: ^\d{2}:\d{2}$

example: 09:00

end_time*string | null

End of the daily window, 24-hour `HH:MM`, in the PBX's local time. Null for `specific_period`.

pattern: ^\d{2}:\d{2}$

example: 18:00

days_of_the_week*object | null

For `days_of_the_week` steps, one flag per weekday; `true` means the window applies on that day. Null for other types.

monday*boolean

tuesday*boolean

wednesday*boolean

thursday*boolean

friday*boolean

saturday*boolean

sunday*boolean

fixed_dates*array<string>

For `fixed_dates` steps, the calendar dates (`YYYY-MM-DD`) the window applies on, in the order they were saved. Null for other types.

[]string · date

recurring_dates*array<string>

For `recurring_dates` steps, the days (`MM-DD`) the window applies on every year, in the order they were saved, each once. Null for other types.

[]string

pattern: ^\d{2}-\d{2}$

specific_period*object | null

For `specific_period` steps, the inclusive range (`YYYY-MM-DD HH:MM`, PBX local time). Null for other types.

start*string

example: 2026-08-03 08:00

end*string

example: 2026-08-17 18:00

created_atstring | null · date-time

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

read-only

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

updated_atstring | null · date-time

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

read-only

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

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

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

Request sample

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

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);

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)

<?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);

{ … }

"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",

"steps": [ … ],

{ … },

"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",

"type": "days_of_the_week",

"status": "enabled",

"start_time": "09:00",

"end_time": "18:00",

"days_of_the_week": { … },

"monday": true,

"tuesday": true,

"wednesday": true,

"thursday": true,

"friday": true,

"saturday": false,

"sunday": false

"fixed_dates": null,

"recurring_dates": null,

"specific_period": null,

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

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

{ … }

"id": "9b2f4c1e-3d5a-4e8b-9c7d-1a2b3c4d5e6f",

"type": "fixed_dates",

"status": "enabled",

"start_time": "00:00",

"end_time": "23:59",

"days_of_the_week": null,

"fixed_dates": [ … ],

"2026-12-24",

"2026-12-31"

"recurring_dates": null,

"specific_period": null,

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

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

}

"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,

"steps": [],

"created_at": "2024-03-01T08:29:07.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

{ … }

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

}

Content-Type string

example: application/json

{ … }

"message": "Unauthenticated."

}

Content-Type string

example: application/json

{ … }

"message": "Invalid ability provided."

}

Content-Type string

example: application/json

{ … }

"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

{ … }

"message": "Too Many Attempts."

}

Retry-After integer

Seconds to wait before retrying.

example: 60

Content-Type string

example: application/json

{ … }

"message": "Server Error"

}

No matching endpoints

List schedules

Responses