Send Invitation

POST

/v1/invitations

curl --request POST \
  --url https://example.com/v1/invitations \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "email": "example", "role": "viewer" }'

Invite someone by email to the organization, or to one workspace with project_id, at a role. Needs members:write, and the authority to give that role there (never above the creator’s own). Someone already in the organization is given a role with PUT /v1/members/{user_id} instead (400).

Authorizations

• ApiKey
• Bearer

Parameters

Query Parameters

project_id

A workspace of the organization; omit it for the organization itself. A workspace key names its own workspace.

string | null format: uuid

A workspace of the organization; omit it for the organization itself. A workspace key names its own workspace.

Request Body ^required

Media type application/json

InvitationRequest

POST /v1/invitations: invite someone by email at a role (to the workspace the query’s project_id names, as a guest, else to the organization).

object

email

required

string

<= 320 characters /^[^@\s]+@[^@\s]+$/

role

required

string

Allowed values: viewer contributor admin owner

Responses

201

The invitation, sent

Media type application/json

Invitation

A pending invitation.

object

invitation_id

required

string format: uuid

email

required

string

space_id

The space it grants a role on

string | null format: uuid

space_role

The role it grants there

string

nullable

Allowed values: viewer contributor admin owner

space_name

string | null

space_kind

string

nullable

Allowed values: organization workspace

invited_by

string | null format: uuid

created_at

string | null format: date-time

expires_at

string | null format: date-time

Example

{
  "space_role": "viewer",
  "space_kind": "organization"
}

400

Refused by the role rules

Media type application/json

ErrorResponse

Standard error response.

object

detail

required

Error message describing what went wrong

string

Example ^generated

{
  "detail": "example"
}

401

Invalid or missing API key

Media type application/json

ErrorResponse

Standard error response.

object

detail

required

Error message describing what went wrong

string

Example ^generated

{
  "detail": "example"
}

403

The key lacks members:write, or its creator may not give or take this role here (nobody grants above their own role)

Media type application/json

ErrorResponse

Standard error response.

object

detail

required

Error message describing what went wrong

string

Example ^generated

{
  "detail": "example"
}

404

Not found or not readable

Media type application/json

ErrorResponse

Standard error response.

object

detail

required

Error message describing what went wrong

string

Example ^generated

{
  "detail": "example"
}

409

The organization’s last owner stays

Media type application/json

ErrorResponse

Standard error response.

object

detail

required

Error message describing what went wrong

string

Example ^generated

{
  "detail": "example"
}

422

Validation Error

Media type application/json

HTTPValidationError

object

detail

Array<object>

ValidationError

object

loc

required

Location

Array<string | integer>

msg

required

Message

string

type

required

Error Type

string

input

ctx

Context

object

Example ^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}