Get a schedule

Returns the schedule identified by the path parameter, unwrapped (no data envelope). Requires the schedules scope on an Integrations API key (a user bearer token also passes).

Multi-tenant scoping is enforced: a schedule belonging to another PBX returns the same 404 as an id that does not exist anywhere, so the endpoint never confirms a foreign schedule. The schedule's steps (its time rules) are embedded, in the same shape PUT and PATCH 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

id path · string · uuid *

Schedule identifier

accept header · string

example: application/json

Responses

Response schema

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

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

Not Found. No schedule with that id exists inside the caller's PBX. A schedule that belongs to another tenant returns exactly this response, so the endpoint never reveals whether a foreign id exists.

Response schema

messagestring

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/{id}

Base URL

Request sample

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

const response = await fetch('https://cockpit.voxbi.com/api/v1/schedules/{id}', {
  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/{id}',
    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/{id}', false, $context);
$data = json_decode($response, true);
print_r($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"

{ … },

"id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",

"type": "recurring_dates",

"status": "disabled",

"start_time": "00:00",

"end_time": "23:59",

"days_of_the_week": null,

"fixed_dates": null,

"recurring_dates": [ … ],

"01-01",

"05-01",

"12-25"

"specific_period": null,

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

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

{ … }

"id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",

"type": "specific_period",

"status": "enabled",

"start_time": null,

"end_time": null,

"days_of_the_week": null,

"fixed_dates": null,

"recurring_dates": null,

"specific_period": { … },

"start": "2026-08-03 08:00",

"end": "2026-08-17 18:00"

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

}

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": "Unauthenticated."

}

Content-Type string

example: application/json

{ … }

"message": "Invalid ability provided."

}

Content-Type string

example: application/json

{ … }

"message": "Schedule not found."

}

Content-Type string

example: application/json

{ … }

"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

Get a schedule

Responses