API reference

Time off

3 operations.

GET /v1/hosts/{host_id}/time-off

Time off for one host that overlaps the asked range.

Operation id
listTimeOff
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}$.
from query string yes Limits: format date-time.
to query string yes Limits: format date-time.

Answers

200 The blocks that overlap the range, earliest start first. application/json

Field Type Always sent Notes
time_off array of TimeOff 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}/time-off

Records time off for a host. A member linked to the host may do this.

Operation id
createTimeOff
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. Its write and its retry receipt are not one batch, so a retry after a lost receipt could add the time off twice (decision 0043, points 7 and 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
start string yes Limits: format date-time.
end string yes Limits: format date-time.
origin string no Values: member , api , import .

Answers

201 The block of time off. 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) TimeOff 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

DELETE /v1/time-off/{time_off_id}

Removes one block of time off. A member linked to the host may do this.

Operation id
removeTimeOff
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
time_off_id path string yes Limits: pattern ^off_[0-9a-z]{26}$.

Answers

204 The block 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
429 Too many attempts. rate_limited