API reference

Members

8 operations.

GET /v1/members

The members of the account.

Operation id
listMembers
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
members.read
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Answers

200 The active members, oldest membership first. application/json

Field Type Always sent Notes
members array of Member 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

PATCH /v1/members/{id}

Changes a member's role.

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

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.
role string yes Values: owner , admin , member .

Answers

200 The member after the change. application/json

Field Type Always sent Notes
(whole body) Member 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 An account keeps at least one owner. This was changed by someone else since it was read. last_owner , version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

DELETE /v1/members/{id}

Removes a member from the account. The person and their other accounts stay. Invites the member sent stay valid until they are revoked.

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

Parameters

Name In Type Required Notes
id path string yes Limits: pattern ^mem_[0-9a-z]{26}$.
version query integer yes Limits: at least 1.

Answers

204 The membership has ended.

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 An account keeps at least one owner. This was changed by someone else since it was read. last_owner , version_conflict
429 Too many attempts. rate_limited

GET /v1/invites

The account's invites, newest first: pending ones and those that ended in the last 30 days, each with its state.

Operation id
listInvites
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
members.read
Assistant tool
No. Not in the first set of tools (decision 0043, point 9).

Answers

200 The invites. application/json

Field Type Always sent Notes
invites array of object yes
invites[] object yes
invites[].host_id string or null yes
invites[].id string yes
invites[].email string yes
invites[].role string yes Values: admin , member .
invites[].state string yes Where the invite stands now. A pending invite past its expiry is expired. Values: pending , accepted , revoked , expired .
invites[].invited_by_member_id string yes
invites[].expires_at string yes Limits: format date-time.
invites[].accepted_member_id string or null yes
invites[].version integer yes
invites[].created_at string yes Limits: format date-time.
invites[].updated_at string yes Limits: format date-time.

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

POST /v1/invites

Invites a person by email address, as an admin or a member, and sends the invite email. The link works for 7 days. An invite stays valid if the member who sent it is removed; revoke it to stop it.

Operation id
createInvite
Who can call it
Acts in one account, the one the credential belongs to.
Credentials
session or API key
Permission
members.invite
Retry key
Required: send an Idempotency-Key header.
Assistant tool
No. It mints a capability, credential or secret that outlives the grant and is later checked against the member's full role (decision 0043, point 8).

Parameters

Name In Type Required Notes
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
host_id string no Limits: pattern ^host_[0-9a-z]{26}$.
email string yes Limits: at most 320 characters.
role string yes Nobody is invited as an owner. Values: admin , member .

Answers

201 The invite. application/json

  • Header Idempotency-Replayed: true when this answer was built from the receipt of an earlier attempt.
Field Type Always sent Notes
host_id string or null yes
id string yes
email string yes
role string yes Values: admin , member .
state string yes Where the invite stands now. A pending invite past its expiry is expired. Values: pending , accepted , revoked , expired .
invited_by_member_id string yes
expires_at string yes Limits: format date-time.
accepted_member_id string or null yes
version integer yes
created_at string yes Limits: format date-time.
updated_at string yes Limits: format date-time.

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
409 This cannot be done while something else depends on it. The same identifier was already used for a different request. This request is already running. conflict , id_conflict , request_in_progress
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

POST /v1/invites/{invite_id}/resend

Sends a pending invite again with a new link. The old link stops working, and the 7 days start again. Counts against the hourly limit of invite emails.

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

Request body application/json, required

Field Type Required Notes
version integer yes Limits: at least 1.

Answers

200 The invite after the resend. application/json

Field Type Always sent Notes
host_id string or null yes
id string yes
email string yes
role string yes Values: admin , member .
state string yes Where the invite stands now. A pending invite past its expiry is expired. Values: pending , accepted , revoked , expired .
invited_by_member_id string yes
expires_at string yes Limits: format date-time.
accepted_member_id string or null yes
version integer yes
created_at string yes Limits: format date-time.
updated_at string yes Limits: format date-time.

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. This was changed by someone else since it was read. conflict , version_conflict
415 Send the body as JSON. unsupported_media_type
429 Too many attempts. rate_limited

POST /v1/invites/{invite_id}/revoke

Revokes a pending invite. Its link stops working at once.

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

Answers

200 The invite after the revoke. application/json

Field Type Always sent Notes
host_id string or null yes
id string yes
email string yes
role string yes Values: admin , member .
state string yes Where the invite stands now. A pending invite past its expiry is expired. Values: pending , accepted , revoked , expired .
invited_by_member_id string yes
expires_at string yes Limits: format date-time.
accepted_member_id string or null yes
version integer yes
created_at string yes Limits: format date-time.
updated_at string yes Limits: format date-time.

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

POST /v1/invites/accept

Accepts an invite for the signed-in person, whose address must be the invited one. Makes them a member with the invited role. It does not change which account the session acts in.

Operation id
acceptInvite
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
account_id string yes The account the invite link names. Limits: 1 to 64 characters.
token string yes The token from the invite link. Limits: 1 to 200 characters.

Answers

200 The account and the new membership. application/json

Field Type Always sent Notes
account_id string yes The account the person is now a member of.
member Member 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
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