Update a schedule

Updates the schedule identified by the path parameter. Requires the schedules scope on an Integrations API key (a user bearer token also passes).

This is a full replace and takes the same body as creation, so name stays required and an omitted description is CLEARED (set to null). Use PATCH on the same path when you want to change one field and leave the rest alone.

Multi-tenant scoping is enforced, so a schedule belonging to another PBX responds 404 and is left untouched. pbx_id is forced from the authenticated principal and is never read from the body, so a schedule cannot be moved between tenants.

Steps: omit steps and they are left exactly as they are, so a body with only name and description never touches the time rules. Send steps and they become exactly that list: keep a step by sending it back with its id (edited or not), add one by leaving id out, and drop one by leaving it out of the list. steps: [] removes them all. The schedule and its steps are written in one transaction, so a 422 on any step changes nothing at all.

The response is the updated schedule with its steps, unwrapped (no data envelope).

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

Request body · required · application/json

Request schema

name*string

Human-readable label for the schedule.

length: 1–255

example: Business hours (winter)

descriptionstring | null

Optional free-text note. Omit or send null to clear it.

length: 0–255

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

stepsarray<object>

The schedule's time rules (the list on the cockpit edit page). Optional on every write: omit it to leave the steps as they are. When sent, the steps become exactly this list: an item with an `id` updates that step, an item without one creates a step, and any existing step not listed is deleted (an administrator can restore it from the cockpit trash). Send `[]` to remove every step. At most 100 steps. Each item is one of the ScheduleStepInput variants.

items: 0–100

[]object

One step (time rule) in a schedule write. Pick the variant that matches `type`. Keys that belong to another type are ignored, not stored. - `id`: include it to UPDATE that existing step of this schedule (it may even change type). Leave it out to CREATE a new step. Not allowed on `POST /schedules`. An id that is not a live step of this schedule responds 422. Sending back exactly what GET returned changes nothing (no rewrite, no `updated_at` bump). - `status`: `enabled` (default when omitted or null) or `disabled`. `true`, `1`, `"1"`, `"true"` and `false`, `0`, `"0"`, `"false"` are accepted as aliases. - Times are 24-hour `HH:MM` in the PBX's local time. `HH:MM:SS` is accepted and the seconds are dropped. Equivalent inputs that are also accepted (and normalized to the documented shape): `days_of_the_week` as a list of enabled day names (`["monday", "friday"]`) or as the JSON string the cockpit stores; `fixed_dates` and `recurring_dates` as one comma-separated string; recurring dates as `M-D` or `YYYY-MM-DD` (the year is ignored); `specific_period` as flat `specific_period_start` and `specific_period_end` keys, and its date-times with a `T` separator or seconds.

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

Unprocessable Entity. The request body failed validation. `errors` maps each rejected field to its messages, and `message` repeats the first one. Nothing was written.

Response schema

messagestring

The first validation message, repeated for convenience.

errorsobject

Step errors are keyed by their path in the body, zero-based (`steps.1.days_of_the_week`, `steps.2.fixed_dates.0`), and every message names the step by its one-based position ("Step 2: ...").

namearray<string>

[]string

descriptionarray<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.

put https://cockpit.voxbi.com/api/v1/schedules/{id}

Base URL

Request sample

curl -X PUT 'https://cockpit.voxbi.com/api/v1/schedules/{id}' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"name":"Business hours (winter)","description":"Monday to Friday, 09:00 to 17:00"}'

const response = await fetch('https://cockpit.voxbi.com/api/v1/schedules/{id}', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
  body: JSON.stringify({
    "name": "Business hours (winter)",
    "description": "Monday to Friday, 09:00 to 17:00"
}),
});

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

import requests

response = requests.put('https://cockpit.voxbi.com/api/v1/schedules/{id}',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
    json={
    "name": "Business hours (winter)",
    "description": "Monday to Friday, 09:00 to 17:00"
}
)
response.raise_for_status()
data = response.json()
print(data)

<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'PUT',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
        'content' => '{
    \"name\": \"Business hours (winter)\",
    \"description\": \"Monday to Friday, 09:00 to 17:00\"
}',
    ],
]);

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

Sample request

{ … }

"name": "Business hours (winter)",

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

}

{ … }

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

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

"name": "Business hours (winter)",

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

"steps": [ … ],

{ … },

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

"type": "days_of_the_week",

"status": "enabled",

"start_time": "09:00",

"end_time": "17: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-11-04T10:15:44.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": "f7a8b9c0-d1e2-4f3a-8b4c-5d6e7f8a9b0c",

"type": "recurring_dates",

"status": "enabled",

"start_time": "00:00",

"end_time": "23:59",

"days_of_the_week": null,

"fixed_dates": null,

"recurring_dates": [ … ],

"12-25",

"12-26"

"specific_period": null,

"created_at": "2024-11-04T10:15:44.000000Z",

"updated_at": "2024-11-04T10:15:44.000000Z"

}

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

"updated_at": "2024-11-04T10:15:44.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": "The name field is required.",

"errors": { … }

"name": [ … ]

"The name field is required."

]

}

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

Update a schedule

Request body · required · application/json

Responses