Schedules
10 operations.
-
GET
/v1/hosts/{host_id}/schedules -
POST
/v1/hosts/{host_id}/schedules -
GET
/v1/schedules/{schedule_id} -
PATCH
/v1/schedules/{schedule_id} -
DELETE
/v1/schedules/{schedule_id} -
PUT
/v1/schedules/{schedule_id}/hours -
PUT
/v1/schedules/{schedule_id}/overrides/{date} -
DELETE
/v1/schedules/{schedule_id}/overrides/{date} -
POST
/v1/event-types/{event_type_id}/schedule -
DELETE
/v1/event-types/{event_type_id}/schedule
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
|