Members
8 operations.
-
GET
/v1/members -
PATCH
/v1/members/{id} -
DELETE
/v1/members/{id} -
GET
/v1/invites -
POST
/v1/invites -
POST
/v1/invites/{invite_id}/resend -
POST
/v1/invites/{invite_id}/revoke -
POST
/v1/invites/accept
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
|