API reference

Calendars

7 operations.

POST /v1/hosts/{host_id}/calendar-connections/google/start

Starts connecting a host's Google calendar. Answers the address the browser opens. A member linked to the host may do this.

Operation id
startGoogleConnection
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
calendars.manage_own
Assistant tool
No. It sends a request to a customer's address or starts a provider connection (decision 0043, point 8).

Parameters

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

Request body application/json, required

Field Type Required Notes
return_path string no Limits: at most 2048 characters.

Answers

200 The address that asks the person to connect Google Calendar. application/json

Field Type Always sent Notes
authorization_url string 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
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited
503 This environment is not fully set up. not_configured

GET /v1/oauth/google/callback

Google sends the browser here after consent. The same member must still be signed in. The browser is then sent back to the app.

Operation id
finishGoogleConnection
Who can call it
Anyone. No sign-in.
Credentials
None needed.

Parameters

Name In Type Required Notes
code query string no
state query string no
error query string no

Answers

303 A browser redirect to the app, with calendar=connected or calendar_error set to a fixed code.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request

GET /v1/hosts/{host_id}/calendar-connections

A host's calendar connections, and the calendars on each one.

Operation id
listCalendarConnections
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
calendars.read
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}$.

Answers

200 The host's calendar connections. application/json

Field Type Always sent Notes
calendar_connections array of object yes
calendar_connections[] object yes
calendar_connections[].id string yes
calendar_connections[].host_id string yes
calendar_connections[].provider string yes Values: google , microsoft , fake .
calendar_connections[].status string yes Values: active , needs_reauth , error , revoked .
calendar_connections[].connected_address string yes
calendar_connections[].version integer yes
calendar_connections[].calendars array of object yes
calendar_connections[].calendars[] object yes
calendar_connections[].calendars[].id string yes
calendar_connections[].calendars[].provider_calendar_id string yes
calendar_connections[].calendars[].name string yes
calendar_connections[].calendars[].access_role string yes
calendar_connections[].calendars[].is_primary boolean yes
calendar_connections[].calendars[].is_conflict_source boolean yes
calendar_connections[].calendars[].is_write_target boolean 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

PUT /v1/calendar-connections/{connection_id}/calendars

Chooses which calendars block time and which one receives bookings. A member linked to the host may do this.

Operation id
setCalendarSelection
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
calendars.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
connection_id path string yes Limits: pattern ^ccn_[0-9a-z]{26}$.

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
conflict_sources array of string yes
write_target string or null yes Limits: 1 to 1024 characters.

Answers

200 The calendars after the choice. application/json

Field Type Always sent Notes
version integer yes
calendars array of object yes
calendars[] object yes
calendars[].id string yes
calendars[].provider_calendar_id string yes
calendars[].name string yes
calendars[].access_role string yes
calendars[].is_primary boolean yes
calendars[].is_conflict_source boolean yes
calendars[].is_write_target boolean 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

POST /v1/calendar-connections/{connection_id}/refresh-calendars

Reads the calendar list from the provider again. New calendars are not selected. A member linked to the host may do this.

Operation id
refreshCalendarList
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
calendars.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
connection_id path string yes Limits: pattern ^ccn_[0-9a-z]{26}$.

Answers

200 The calendars after the list was read again. application/json

Field Type Always sent Notes
version integer yes
calendars array of object yes
calendars[] object yes
calendars[].id string yes
calendars[].provider_calendar_id string yes
calendars[].name string yes
calendars[].access_role string yes
calendars[].is_primary boolean yes
calendars[].is_conflict_source boolean yes
calendars[].is_write_target boolean 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 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
503 This environment is not fully set up. A calendar could not be reached. not_configured , provider_unavailable

DELETE /v1/calendar-connections/{connection_id}

Removes a calendar connection and asks the provider to revoke the grant. A member linked to the host may do this.

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

Parameters

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

Answers

204 The connection 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

POST /hooks/calendar/google/{account_id}

Google's notice that a watched calendar changed. Answers 204 whatever it carries; a valid one only schedules a sync.

Operation id
receiveGoogleCalendarPush
Who can call it
Anyone. No sign-in.
Credentials
None needed.

Parameters

Name In Type Required Notes
account_id path string yes
x-goog-channel-id header string no
x-goog-channel-token header string no
x-goog-resource-state header string no

Answers

204 Received. Nothing is said about what was found.

Refusals

Status Meaning Codes
400 The request is not valid. invalid_request