Assistants
7 operations.
-
GET
/v1/assistant-consent -
POST
/v1/assistant-consent -
GET
/v1/assistant-grants -
DELETE
/v1/assistant-grants/{assistant_grant_id} -
GET
/v1/assistant-approvals -
GET
/v1/assistant-approvals/{approval_id} -
POST
/v1/assistant-approvals/{approval_id}/decision
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
|