Calendars
7 operations.
-
POST
/v1/hosts/{host_id}/calendar-connections/google/start -
GET
/v1/oauth/google/callback -
GET
/v1/hosts/{host_id}/calendar-connections -
PUT
/v1/calendar-connections/{connection_id}/calendars -
POST
/v1/calendar-connections/{connection_id}/refresh-calendars -
DELETE
/v1/calendar-connections/{connection_id} -
POST
/hooks/calendar/google/{account_id}
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
|