API reference

Schedules

10 operations.

GET /v1/hosts/{host_id}/schedules

The schedules of one host, oldest first, with weekly hours and date overrides.

Operation id
listSchedules
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
schedules.read
Assistant tool
Yes. It only reads.

Parameters

Name In Type Required Notes
host_id path string yes Limits: pattern ^host_[0-9a-z]{26}$.

Answers

200 The host's schedules. application/json

Field Type Always sent Notes
schedules array of Schedule yes

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
429 Too many attempts. rate_limited

POST /v1/hosts/{host_id}/schedules

Adds a schedule for a host. It is not the default. A member linked to the host may do this.

Operation id
createSchedule
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
schedules.manage_own
Retry key
Required: send an Idempotency-Key header.
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Parameters

Name In Type Required Notes
host_id path string yes Limits: pattern ^host_[0-9a-z]{26}$.
Idempotency-Key header string yes Caller-chosen key for a safe retry. 1 to 255 visible ASCII characters. Limits: pattern ^[\u0020-\u007E]{1,255}$.

Request body application/json, required

Field Type Required Notes
name string yes
time_zone string yes

Answers

201 The schedule. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
(whole body) Schedule yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 The same identifier was already used for a different request. This request is already running. id_conflict , request_in_progress
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

GET /v1/schedules/{schedule_id}

One schedule, with its weekly hours and date overrides. A schedule with no host is an event type's own hours.

Operation id
getSchedule
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
schedules.read
Assistant tool
Yes. It only reads.

Parameters

Name In Type Required Notes
schedule_id path string yes Limits: pattern ^sch_[0-9a-z]{26}$.

Answers

200 The schedule. application/json

Field Type Always sent Notes
(whole body) Schedule yes

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
429 Too many attempts. rate_limited

PATCH /v1/schedules/{schedule_id}

Changes a schedule's name, time zone or default flag. A member linked to the host may do this. An event type's own hours need the right to change event types.

Operation id
updateSchedule
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
schedules.manage_own
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
schedule_id path string yes Limits: pattern ^sch_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
name string no
time_zone string no
is_default boolean no

Answers

200 The schedule after the change. application/json

Field Type Always sent Notes
(whole body) Schedule yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 This was changed by someone else since it was read. version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

DELETE /v1/schedules/{schedule_id}

Removes a schedule that is not the default and is not used by an event type. A member linked to the host may do this. An event type's own hours need the right to change event types.

Operation id
deleteSchedule
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
schedules.manage_own
Assistant tool
No. It deletes. A delete is never a tool (decision 0043, point 8).

Parameters

Name In Type Required Notes
schedule_id path string yes Limits: pattern ^sch_[0-9a-z]{26}$.
version query integer yes Limits: at least 1.

Answers

204 The schedule has been removed.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 This cannot be done while something else depends on it. This was changed by someone else since it was read. conflict , version_conflict
429 Too many attempts. rate_limited

PUT /v1/schedules/{schedule_id}/hours

Replaces the whole week. Every weekday is required, and an empty day is closed. An event type's own hours keep at least one range. A member linked to the host may do this. An event type's own hours need the right to change event types.

Operation id
replaceScheduleHours
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
schedules.manage_own
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
schedule_id path string yes Limits: pattern ^sch_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
hours object yes
hours.sunday array of object yes
hours.sunday[] object yes
hours.sunday[].start string yes
hours.sunday[].end string yes
hours.monday array of object yes
hours.monday[] object yes
hours.monday[].start string yes
hours.monday[].end string yes
hours.tuesday array of object yes
hours.tuesday[] object yes
hours.tuesday[].start string yes
hours.tuesday[].end string yes
hours.wednesday array of object yes
hours.wednesday[] object yes
hours.wednesday[].start string yes
hours.wednesday[].end string yes
hours.thursday array of object yes
hours.thursday[] object yes
hours.thursday[].start string yes
hours.thursday[].end string yes
hours.friday array of object yes
hours.friday[] object yes
hours.friday[].start string yes
hours.friday[].end string yes
hours.saturday array of object yes
hours.saturday[] object yes
hours.saturday[].start string yes
hours.saturday[].end string yes

Answers

200 The schedule after the week was replaced. application/json

Field Type Always sent Notes
(whole body) Schedule yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 This was changed by someone else since it was read. version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

PUT /v1/schedules/{schedule_id}/overrides/{date}

Sets the hours of one date. An empty list closes that day. A member linked to the host may do this. An event type's own hours need the right to change event types.

Operation id
setScheduleOverride
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
schedules.manage_own
Assistant tool
No. A repeat could take effect twice: it takes no retry key, or its write does not store the key or check a version (decision 0043, point 7).

Parameters

Name In Type Required Notes
schedule_id path string yes Limits: pattern ^sch_[0-9a-z]{26}$.
date path string yes

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
intervals array of object yes
intervals[] object yes
intervals[].start string yes
intervals[].end string yes

Answers

200 The schedule after the date was set. application/json

Field Type Always sent Notes
(whole body) Schedule yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 This was changed by someone else since it was read. version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

DELETE /v1/schedules/{schedule_id}/overrides/{date}

Removes one date override, so that date follows the weekly hours again. A member linked to the host may do this. An event type's own hours need the right to change event types.

Operation id
removeScheduleOverride
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
schedules.manage_own
Assistant tool
No. It deletes. A delete is never a tool (decision 0043, point 8).

Parameters

Name In Type Required Notes
schedule_id path string yes Limits: pattern ^sch_[0-9a-z]{26}$.
date path string yes
version query integer yes Limits: at least 1.

Answers

200 The schedule after the override was removed. application/json

Field Type Always sent Notes
(whole body) Schedule yes

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 This was changed by someone else since it was read. version_conflict
429 Too many attempts. rate_limited

POST /v1/event-types/{event_type_id}/schedule

Gives an event type hours of its own. They replace every host's hours for this event type; each host's calendar and time off still block. Send the event type's version. Change them afterwards through the schedule routes.

Operation id
createEventTypeSchedule
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Retry key
Required: send an Idempotency-Key header.
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.
Idempotency-Key header string yes Caller-chosen key for a safe retry. 1 to 255 visible ASCII characters. Limits: pattern ^[\u0020-\u007E]{1,255}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
name string no
time_zone string yes
hours object yes
hours.sunday array of object yes
hours.sunday[] object yes
hours.sunday[].start string yes
hours.sunday[].end string yes
hours.monday array of object yes
hours.monday[] object yes
hours.monday[].start string yes
hours.monday[].end string yes
hours.tuesday array of object yes
hours.tuesday[] object yes
hours.tuesday[].start string yes
hours.tuesday[].end string yes
hours.wednesday array of object yes
hours.wednesday[] object yes
hours.wednesday[].start string yes
hours.wednesday[].end string yes
hours.thursday array of object yes
hours.thursday[] object yes
hours.thursday[].start string yes
hours.thursday[].end string yes
hours.friday array of object yes
hours.friday[] object yes
hours.friday[].start string yes
hours.friday[].end string yes
hours.saturday array of object yes
hours.saturday[] object yes
hours.saturday[].start string yes
hours.saturday[].end string yes
overrides array of object no
overrides[] object yes
overrides[].date string yes
overrides[].intervals array of object yes
overrides[].intervals[] object yes
overrides[].intervals[].start string yes
overrides[].intervals[].end string yes

Answers

201 The event type's hours. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
(whole body) Schedule yes

Refusals

Status Meaning Codes
400 The body is not valid JSON. The request is not valid. invalid_json , invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 This cannot be done while something else depends on it. The same identifier was already used for a different request. This request is already running. This was changed by someone else since it was read. conflict , id_conflict , request_in_progress , version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

DELETE /v1/event-types/{event_type_id}/schedule

Removes an event type's own hours, so each host's hours apply again. Send the event type's version. An event type without hours of its own answers the same, and nothing changes.

Operation id
deleteEventTypeSchedule
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
event_types.manage
Assistant tool
No. It deletes. A delete is never a tool (decision 0043, point 8).

Parameters

Name In Type Required Notes
event_type_id path string yes Limits: pattern ^evt_[0-9a-z]{26}$.
version query integer yes Limits: at least 1.

Answers

204 The event type uses its hosts' hours.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request
401 Sign in is required. unauthenticated
403 You are not allowed to do that. Choose an account to act in first. forbidden , no_active_account
404 Nothing was found there. not_found
409 This was changed by someone else since it was read. version_conflict
429 Too many attempts. rate_limited