API reference

Assistants

7 operations.

GET /v1/assistant-consent

What an assistant asks for: its claimed name, its address host, the redirect address, the permissions, and your accounts with what you may give in each. Read from the signed request the authorization server sent the consent page.

Operation id
getAssistantConsent
Who can call it
A signed-in person, for themselves. Not tied to an account.
Credentials
session

Parameters

Name In Type Required Notes
oauth_query query string yes The query string the authorization server sent the consent page, exactly as received. Limits: 1 to 8000 characters.

Answers

200 The request, for the consent page. application/json

Field Type Always sent Notes
client_name string yes The name the assistant claims for itself. Show it as text, marked as claimed.
client_host string yes The host of the assistant's address, which the owner's list vouches for.
redirect_uri string yes Where the browser goes when this request is answered.
redirect_host string yes
local_redirect boolean yes True when the redirect address is on this computer. Show a warning.
requested array of string yes The permissions the assistant asked for.
accounts array of object yes Your accounts. You choose one; a grant is for one account.
accounts[] object yes
accounts[].id string yes
accounts[].name string yes
accounts[].handle string yes
accounts[].role string yes
accounts[].permissions array of string yes What you may give the assistant in this account: asked for, and held by you now.

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. forbidden
429 Too many attempts. rate_limited

POST /v1/assistant-consent

Answers an assistant's request. Accepting connects it to one of your accounts with the permissions you chose (from what it asked for and you hold), and replaces any earlier connection of the same assistant there. Declining tells it no. Either way, send the browser to redirect_to.

Operation id
decideAssistantConsent
Who can call it
A signed-in person, for themselves. Not tied to an account.
Credentials
session

Request body application/json, required

Field Type Required Notes
oauth_query string yes The query string the authorization server sent the consent page, exactly as received. Limits: 1 to 8000 characters.
accept boolean yes False declines; the assistant is told no.
account_id string no The account the assistant acts in. Limits: 1 to 64 characters.
permissions array of string no What the assistant may do, from what it asked for. Untick any you do not want. Limits: at most 50 items.

Answers

200 Where the browser goes next. application/json

Field Type Always sent Notes
redirect_to string yes Send the browser here: the assistant's own address.
assistant_grant_id string or null 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. forbidden
404 Nothing was found there. not_found
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

GET /v1/assistant-grants

Connected assistants, newest first: yours, or every member's with assistant_grants.read. Each with the assistant's claimed name and host, the redirect host, the permissions, when it was connected and last used, and when it expires.

Operation id
listAssistantGrants
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
assistant_grants.read_own
Assistant tool
No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).

Answers

200 The grants. application/json

Field Type Always sent Notes
assistant_grants array of object yes
assistant_grants[] object yes
assistant_grants[].id string yes
assistant_grants[].member_id string yes
assistant_grants[].client_name string yes The name the assistant claimed when it was connected. Text only.
assistant_grants[].client_host string yes
assistant_grants[].redirect_host string yes
assistant_grants[].permissions array of string yes What the member consented to.
assistant_grants[].state string yes Values: active , expired , revoked .
assistant_grants[].connected_at string yes Limits: format date-time.
assistant_grants[].last_used_at string or null yes Noted at most once an hour. Limits: format date-time.
assistant_grants[].expires_at string yes Limits: format date-time.
assistant_grants[].revoked_at string or null yes Limits: format date-time.
assistant_grants[].revoked_reason string or null yes Values: member , admin , member_removed , replaced , refresh_reuse , client_removed , expired , binding_mismatch , not_completed .

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

DELETE /v1/assistant-grants/{assistant_grant_id}

Disconnects an assistant: yours, or any member's with assistant_grants.manage. It stops on its next request and its next refresh. The grant stays in the list as revoked. Revoking a revoked grant changes nothing.

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

Parameters

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

Answers

200 The grant after the revoke. application/json

Field Type Always sent Notes
id string yes
member_id string yes
client_name string yes The name the assistant claimed when it was connected. Text only.
client_host string yes
redirect_host string yes
permissions array of string yes What the member consented to.
state string yes Values: active , expired , revoked .
connected_at string yes Limits: format date-time.
last_used_at string or null yes Noted at most once an hour. Limits: format date-time.
expires_at string yes Limits: format date-time.
revoked_at string or null yes Limits: format date-time.
revoked_reason string or null yes Values: member , admin , member_removed , replaced , refresh_reuse , client_removed , expired , binding_mismatch , not_completed .

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

GET /v1/assistant-approvals

Your pending assistant approvals, newest first. API keys and assistant calls receive an empty page; only your own member session sees approvals. Support access is refused.

Operation id
listAssistantApprovals
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
assistant_grants.read_own
Assistant tool
No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).

Parameters

Name In Type Required Notes
state query string no Values: pending .
limit query integer no Limits: at least 1, at most 100.
cursor query string no

Answers

200 One page of pending approvals. application/json

Field Type Always sent Notes
approvals array of object yes
approvals[] object yes
approvals[].id string yes
approvals[].created_at string yes Limits: format date-time.
approvals[].expires_at string yes Limits: format date-time.
approvals[].action string yes Values: createBookingForVisitor , rescheduleBooking , cancelBooking , reassignBooking , setBookingOutcome .
approvals[].assistant object yes
approvals[].assistant.assistant_grant_id string yes
approvals[].assistant.client_name string yes The name the assistant claimed when it was connected. Show it as text.
approvals[].assistant.client_host string yes
next_cursor string or null 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
429 Too many attempts. rate_limited

GET /v1/assistant-approvals/{approval_id}

One call an assistant asked to make for you, waiting for your approval: what it will do, read by the server now, and the arguments it sent. Only the member the assistant acts for can read it.

Operation id
getAssistantApproval
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
assistant_grants.read_own
Assistant tool
No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).

Parameters

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

Answers

200 The approval. application/json

Field Type Always sent Notes
id string yes
state string yes Values: pending , approved , used , declined , expired .
action string yes The operation the assistant asked to run. Values: createBookingForVisitor , rescheduleBooking , cancelBooking , reassignBooking , setBookingOutcome .
created_at string yes Limits: format date-time.
expires_at string yes Limits: format date-time.
decided_at string or null yes Limits: format date-time.
assistant object yes
assistant.assistant_grant_id string yes
assistant.client_name string yes The name the assistant claimed when it was connected. Show it as text.
assistant.client_host string yes
plan object yes What will happen, from the server's own reads.
plan.emails_visitor boolean yes Whether this change sends the visitor an email.
plan.booking object or null yes The booking the call changes, as the server reads it now. Null for a new booking, or when the member may not see it.
plan.booking.id string yes
plan.booking.status string yes
plan.booking.version integer yes
plan.booking.start string yes Limits: format date-time.
plan.booking.end string yes Limits: format date-time.
plan.booking.event_type_name string or null yes
plan.booking.host_names array of string yes
plan.booking.visitor_name string or null yes
plan.booking.visitor_email string or null yes
plan.event_type object or null yes
plan.event_type.id string yes
plan.event_type.name string yes
plan.host object or null yes The host a new booking or a reassignment names.
plan.host.id string yes
plan.host.display_name string yes
plan.start string or null yes The new start a booking or a move names. Limits: format date-time.
arguments array of object yes The arguments as the assistant sent them, as plain text.
arguments[] object yes
arguments[].name string yes
arguments[].value string 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/assistant-approvals/{approval_id}/decision

Approve or decline one call an assistant asked to make for you. Approving lets the assistant run exactly that call, once, before the approval expires. Only the member the assistant acts for can decide, once.

Operation id
decideAssistantApproval
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
assistant_grants.manage_own
Assistant tool
No. It manages keys, assistant grants, webhooks, lookups or members, which are never tools (decision 0043, point 8).

Parameters

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

Request body application/json, required

Field Type Required Notes
decision string yes Values: approve , decline .

Answers

200 The approval after the decision. application/json

Field Type Always sent Notes
id string yes
state string yes Values: pending , approved , used , declined , expired .
action string yes The operation the assistant asked to run. Values: createBookingForVisitor , rescheduleBooking , cancelBooking , reassignBooking , setBookingOutcome .
created_at string yes Limits: format date-time.
expires_at string yes Limits: format date-time.
decided_at string or null yes Limits: format date-time.
assistant object yes
assistant.assistant_grant_id string yes
assistant.client_name string yes The name the assistant claimed when it was connected. Show it as text.
assistant.client_host string yes
plan object yes What will happen, from the server's own reads.
plan.emails_visitor boolean yes Whether this change sends the visitor an email.
plan.booking object or null yes The booking the call changes, as the server reads it now. Null for a new booking, or when the member may not see it.
plan.booking.id string yes
plan.booking.status string yes
plan.booking.version integer yes
plan.booking.start string yes Limits: format date-time.
plan.booking.end string yes Limits: format date-time.
plan.booking.event_type_name string or null yes
plan.booking.host_names array of string yes
plan.booking.visitor_name string or null yes
plan.booking.visitor_email string or null yes
plan.event_type object or null yes
plan.event_type.id string yes
plan.event_type.name string yes
plan.host object or null yes The host a new booking or a reassignment names.
plan.host.id string yes
plan.host.display_name string yes
plan.start string or null yes The new start a booking or a move names. Limits: format date-time.
arguments array of object yes The arguments as the assistant sent them, as plain text.
arguments[] object yes
arguments[].name string yes
arguments[].value 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
409 This cannot be done while something else depends on it. conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited