Lithic docs
lithicapp.io

Workspaces und Personen

Workspaces mit ihren Mitgliedern, Gruppen und Einladungen, die Rechte des aufrufenden Kontos und der bisher verbrauchte Anteil am gebuchten Tarif.

31 Operationen. Jeder Pfad ist relativ zum Ursprung der Instanz; jeder Antwortkörper ist JSON, sofern nicht anders vermerkt. Die Endpunktbeschreibungen unten stammen unverändert aus der Routentabelle des Servers und bleiben englisch. Authentifizierung, Fehler und seitenweise Abfrage stehen unter API.

GET /api/v1/workspaces

List workspaces the caller is a member of.

listWorkspaces · token scope: session only

Query parameters

  • cursor · string · length 1–∞
  • limit · integer · 1–100

Response 200 · application/json

  • items · object[] · required
    • id · string (uuid) · required
    • slug · string · required, length 1–100
    • name · string · required
    • icon · string | null · required
    • role · "owner" | "admin" | "member" | "guest" · required
    • createdAt · string (date-time) · required
  • nextCursor · string | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

POST /api/v1/workspaces

Create a workspace; the caller becomes its owner, and it starts with one open collection.

createWorkspace · token scope: session only

Request body · application/json, required

  • name · string · required, length 1–200
  • slug · string · length 1–100

Response 200 · application/json

  • id · string (uuid) · required
  • slug · string · required, length 1–100
  • name · string · required
  • icon · string | null · required
  • role · "owner" | "admin" | "member" | "guest" · required
  • createdAt · string (date-time) · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

GET /api/v1/workspaces/activatable

List workspaces the caller is a member of that this product is not activated on.

listActivatableWorkspaces · token scope: session only

Query parameters

  • cursor · string · length 1–∞
  • limit · integer · 1–100

Response 200 · application/json

  • items · object[] · required
    • id · string (uuid) · required
    • slug · string · required, length 1–100
    • name · string · required
    • icon · string | null · required
    • role · "owner" | "admin" | "member" | "guest" · required
    • createdAt · string (date-time) · required
  • nextCursor · string | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

GET /api/v1/workspaces/{workspaceId}

Get a single workspace.

getWorkspace · token scope: content:read

Path parameters

  • workspaceId · string (uuid) · required

Response 200 · application/json

  • id · string (uuid) · required
  • slug · string · required, length 1–100
  • name · string · required
  • icon · string | null · required
  • role · "owner" | "admin" | "member" | "guest" · required
  • createdAt · string (date-time) · required
  • activated · boolean · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

PATCH /api/v1/workspaces/{workspaceId}

Update a workspace name and/or icon.

updateWorkspace · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required

Request body · application/json, required

  • name · string · length 1–200
  • icon · string | null

Response 200 · application/json

  • id · string (uuid) · required
  • slug · string · required, length 1–100
  • name · string · required
  • icon · string | null · required
  • role · "owner" | "admin" | "member" | "guest" · required
  • createdAt · string (date-time) · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

DELETE /api/v1/workspaces/{workspaceId}

Delete a workspace and everything in it (irreversible). Requires the workspace.delete capability, i.e. owner (ADR-0016 D1); an admin gets 403. Removes memberships, groups, invitations, collections, the field registry, every block with its doc and projections, and every attachment.

deleteWorkspace · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required

Response 200 · application/json

  • id · string (uuid) · required
  • slug · string · required, length 1–100
  • name · string · required
  • icon · string | null · required
  • role · "owner" | "admin" | "member" | "guest" · required
  • createdAt · string (date-time) · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

POST /api/v1/workspaces/{workspaceId}/activation

Activate the asking product on this workspace (ADR-0033). The product comes from the request origin, never from a body. Idempotent.

activateWorkspaceProduct · token scope: session only

Path parameters

  • workspaceId · string (uuid) · required

Response 200 · application/json

  • id · string (uuid) · required
  • slug · string · required, length 1–100
  • name · string · required
  • icon · string | null · required
  • role · "owner" | "admin" | "member" | "guest" · required
  • createdAt · string (date-time) · required
  • activated · boolean · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

GET /api/v1/workspaces/{workspaceId}/members

List the members of a workspace. Email addresses are disclosed only to callers holding members.manage (admin/owner); user.email is null for everyone else (ADR-0016 D9d). A guest sees only the members co-present on a page they can read, names only.

listWorkspaceMembers · token scope: admin:read

Path parameters

  • workspaceId · string (uuid) · required

Query parameters

  • cursor · string · length 1–∞
  • limit · integer · 1–100

Response 200 · application/json

  • items · object[] · required
    • workspaceId · string (uuid) · required
    • userId · string (uuid) · required
    • role · "owner" | "admin" | "member" | "guest" · required
    • user · object · required
      • id · string (uuid) · required
      • email · string (email) | null · required
      • name · string | null · required
      • image · string | null · required
      • bot · object | null
        • ownerId · string (uuid) · required
        • ownerName · string | null · required
    • joinedAt · string (date-time) · required
  • nextCursor · string | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

GET /api/v1/workspaces/{workspaceId}/collections/{collectionId}/members

List a collection's explicit grants (collection_member, ADR-0016 D3) with each subject resolved for display. These are step 2 of resolution: the implicit levels a visibility gives a workspace role (D2) are NOT rows and do not appear here. Requires full on the collection.

listCollectionMembers · token scope: admin:read

Path parameters

  • workspaceId · string (uuid) · required
  • collectionId · string (uuid) · required

Query parameters

  • cursor · string · length 1–∞
  • limit · integer · 1–100

Response 200 · application/json

  • items · object[] · required
    • collectionId · string (uuid) · required
    • subjectType · "user" | "group" · required
    • subjectId · string (uuid) · required
    • role · "read" | "comment" | "edit" | "full" · required
    • subject · object · required
      • subjectType · "user" | "group" · required
      • subjectId · string (uuid) · required
      • name · string · required
      • image · string | null · required
      • bot · boolean
      • agentUrl · string | null
  • nextCursor · string | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

PUT /api/v1/workspaces/{workspaceId}/collections/{collectionId}/members

Grant a user or group a level in a collection (upsert on (collection, subjectType, subjectId), so re-sending changes the level). Requires full on the collection; an owner may always write themselves in (D1: owners can take access, never quietly have it). Bumps the access generation.

setCollectionMember · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required
  • collectionId · string (uuid) · required

Request body · application/json, required

  • subjectType · "user" | "group" · required
  • subjectId · string (uuid) · required
  • role · "read" | "comment" | "edit" | "full" · required

Response 200 · application/json

  • collectionId · string (uuid) · required
  • subjectType · "user" | "group" · required
  • subjectId · string (uuid) · required
  • role · "read" | "comment" | "edit" | "full" · required
  • subject · object · required
    • subjectType · "user" | "group" · required
    • subjectId · string (uuid) · required
    • name · string · required
    • image · string | null · required
    • bot · boolean
    • agentUrl · string | null

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

DELETE /api/v1/workspaces/{workspaceId}/collections/{collectionId}/members/{subjectType}/{subjectId}

Revoke a subject's explicit grant in a collection. Requires full on the collection. Refused (409) when it would remove the LAST full member (ADR-0016 D6, the same last-subject invariant as ACLs). Bumps the access generation. Returns the membership that was removed.

removeCollectionMember · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required
  • collectionId · string (uuid) · required
  • subjectType · "user" | "group" · required
  • subjectId · string (uuid) · required

Response 200 · application/json

  • collectionId · string (uuid) · required
  • subjectType · "user" | "group" · required
  • subjectId · string (uuid) · required
  • role · "read" | "comment" | "edit" | "full" · required
  • subject · object · required
    • subjectType · "user" | "group" · required
    • subjectId · string (uuid) · required
    • name · string · required
    • image · string | null · required
    • bot · boolean
    • agentUrl · string | null

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

POST /api/v1/me/avatar

Set the calling account's profile picture (multipart/form-data, one file field). PNG/JPEG/GIF/WebP by BYTES, not by declared type; max 1024 KiB. Account-wide, so no :workspaceId and no plan quota. Replaces any previous one.

uploadMyAvatar · token scope: session only

Response 200 · application/json

  • image · string | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

DELETE /api/v1/me/avatar

Remove the calling account's picture: row, bytes and image. Displays fall back to initials. Idempotent.

deleteMyAvatar · token scope: session only

Response 200 · application/json

  • image · string | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

GET /api/v1/users/{userId}/avatar

Stream a person's picture, as an <img src> rather than JSON. Readable by that person and by anyone sharing a workspace with them; everything else (unknown id, no picture, no shared workspace) is the same 404. v is a cache-buster and is ignored.

getUserAvatar · token scope: session only

Path parameters

  • userId · string (uuid) · required

Response 200 · application/json

  • string

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

GET /api/v1/me/connected-apps

List the AI assistants (MCP hosts) the calling account connected through the OAuth sign-in, for the product asking plus clients that named none. Session-only.

listConnectedApps · token scope: session only

Response 200 · application/json

  • items · object[] · required
    • clientId · string · required
    • name · string · required
    • connectedAt · string (date-time) · required
    • lastActiveAt · string (date-time) | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

DELETE /api/v1/me/connected-apps/{clientId}

Disconnect one: deletes its tokens and the consent, so it stops working at once and has to ask again. Session-only.

disconnectConnectedApp · token scope: session only

Path parameters

  • clientId · string · required, length 1–200

Response 200 · application/json

  • clientId · string · required
  • name · string · required
  • connectedAt · string (date-time) · required
  • lastActiveAt · string (date-time) | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

GET /api/v1/workspaces/{workspaceId}/usage

This workspace's storage and seat usage against its plan's limits. Readable by every member (guests included): it is the answer to “why was my upload refused”. Being over a limit stops new writes of that kind and never removes, hides or locks anything that already exists.

getWorkspaceUsage · token scope: content:read

Path parameters

  • workspaceId · string (uuid) · required

Response 200 · application/json

  • workspaceId · string (uuid) · required
  • plan · "free" | "pro" | "business" | "enterprise" · required
  • planSource · "operator" | "subscription" | null · required Who decided this plan: operator (assigned by a human in the back office), subscription (a payment), or null (this deployment’s default). An operator-assigned plan cannot be bought over: a payment would be taken and the plan left unchanged, so a client offering a purchase has to read this.
  • limits · object · required
    • storageBytes · integer | null · required
    • fileSizeBytes · integer | null · required
    • members · integer | null · required
    • guests · integer | null · required
    • versionHistoryDays · integer | null · required
  • storageBytes · integer · required, 0–9007199254740991
  • attachmentCount · integer · required, 0–9007199254740991
  • members · integer · required, 0–9007199254740991
  • guests · integer · required, 0–9007199254740991
  • over · "storageBytes" | "fileSizeBytes" | "members" | "guests" | "versionHistoryDays"[] · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

GET /api/v1/workspaces/{workspaceId}/me/capabilities

The caller's own workspace role and the administrative capabilities it carries (ADR-0016 D1), derived server-side from workspaceCapabilities(). The single source for enabling admin UI. Content permissions are NOT here (no role grants implicit read); those come from getPageAccess.

getMyCapabilities · token scope: admin:read

Path parameters

  • workspaceId · string (uuid) · required

Response 200 · application/json

  • workspaceId · string (uuid) · required
  • userId · string (uuid) · required
  • role · "owner" | "admin" | "member" | "guest" · required
  • capabilities · "workspace.delete" | "workspace.transferOwnership" | "workspace.manageOwnerRole" | "workspace.manage" | "members.manage" | "groups.manage" | "invitations.manage" | "fields.manage" | "collections.create" | "collections.delete" | "purge" | "agents.manage"[] · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

PATCH /api/v1/workspaces/{workspaceId}/members/{userId}

Change a member's workspace role (ADR-0016 D11a). Granting or revoking owner requires workspace.manageOwnerRole (owner only); every other change requires members.manage. Nobody may raise their OWN role, and the last owner cannot be demoted (409). Bumps the workspace access generation.

updateMemberRole · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required
  • userId · string (uuid) · required

Request body · application/json, required

  • role · "owner" | "admin" | "member" | "guest" · required

Response 200 · application/json

  • workspaceId · string (uuid) · required
  • userId · string (uuid) · required
  • role · "owner" | "admin" | "member" | "guest" · required
  • user · object · required
    • id · string (uuid) · required
    • email · string (email) | null · required
    • name · string | null · required
    • image · string | null · required
    • bot · object | null
      • ownerId · string (uuid) · required
      • ownerName · string | null · required
  • joinedAt · string (date-time) · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

DELETE /api/v1/workspaces/{workspaceId}/members/{userId}

Remove a member from the workspace. Requires members.manage; removing an owner additionally requires workspace.manageOwnerRole, and the last owner cannot be removed (409). Drops their group memberships; their explicit ACL and collection-member rows are removed with them, so a restricted page may be left without a full subject: the D6 invariant is re-checked and the removal is refused (409) when it would strand one. Returns the membership that was removed.

removeMember · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required
  • userId · string (uuid) · required

Response 200 · application/json

  • workspaceId · string (uuid) · required
  • userId · string (uuid) · required
  • role · "owner" | "admin" | "member" | "guest" · required
  • user · object · required
    • id · string (uuid) · required
    • email · string (email) | null · required
    • name · string | null · required
    • image · string | null · required
    • bot · object | null
      • ownerId · string (uuid) · required
      • ownerName · string | null · required
  • joinedAt · string (date-time) · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

GET /api/v1/workspaces/{workspaceId}/groups

List the workspace groups with their member counts. Readable by any member except a guest (403, reason guest_no_directory): a group name has to be legible in a share dialog for the permission model to be understandable. Writes require groups.manage.

listGroups · token scope: admin:read

Path parameters

  • workspaceId · string (uuid) · required

Query parameters

  • cursor · string · length 1–∞
  • limit · integer · 1–100

Response 200 · application/json

  • items · object[] · required
    • id · string (uuid) · required
    • workspaceId · string (uuid) · required
    • name · string · required
    • memberCount · integer · required, 0–9007199254740991
    • createdAt · string (date-time) · required
  • nextCursor · string | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

POST /api/v1/workspaces/{workspaceId}/groups

Create a group. Requires groups.manage. Groups are flat, with no nesting (D7).

createGroup · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required

Request body · application/json, required

  • name · string · required, length 1–200

Response 200 · application/json

  • id · string (uuid) · required
  • workspaceId · string (uuid) · required
  • name · string · required
  • memberCount · integer · required, 0–9007199254740991
  • createdAt · string (date-time) · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

PATCH /api/v1/workspaces/{workspaceId}/groups/{groupId}

Rename a group. Requires groups.manage.

updateGroup · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required
  • groupId · string (uuid) · required

Request body · application/json, required

  • name · string · required, length 1–200

Response 200 · application/json

  • id · string (uuid) · required
  • workspaceId · string (uuid) · required
  • name · string · required
  • memberCount · integer · required, 0–9007199254740991
  • createdAt · string (date-time) · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

DELETE /api/v1/workspaces/{workspaceId}/groups/{groupId}

Delete a group. Requires groups.manage. Its permission and collection_member rows go with it, so access granted only through this group is revoked; refused (409) when that would leave a restricted block or a collection without a full subject (D6). Bumps the access generation. Returns the deleted group.

deleteGroup · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required
  • groupId · string (uuid) · required

Response 200 · application/json

  • id · string (uuid) · required
  • workspaceId · string (uuid) · required
  • name · string · required
  • memberCount · integer · required, 0–9007199254740991
  • createdAt · string (date-time) · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

GET /api/v1/workspaces/{workspaceId}/groups/{groupId}/members

List a group's users. Readable by any member except a guest (see listGroups); changing the membership requires groups.manage. Because the read half is open to every other member, user.email follows the same D9d rule as listWorkspaceMembers: an address for a caller holding members.manage, null for everybody else.

listGroupMembers · token scope: admin:read

Path parameters

  • workspaceId · string (uuid) · required
  • groupId · string (uuid) · required

Query parameters

  • cursor · string · length 1–∞
  • limit · integer · 1–100

Response 200 · application/json

  • items · object[] · required
    • groupId · string (uuid) · required
    • userId · string (uuid) · required
    • user · object · required
      • id · string (uuid) · required
      • email · string (email) | null · required
      • name · string | null · required
      • image · string | null · required
      • bot · object | null
        • ownerId · string (uuid) · required
        • ownerName · string | null · required
  • nextCursor · string | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

PUT /api/v1/workspaces/{workspaceId}/groups/{groupId}/members/{userId}

Add a workspace member to a group (idempotent: re-adding is a no-op that returns the existing membership). Requires groups.manage; the user must already be a member of the workspace. Bumps the access generation (D10).

addGroupMember · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required
  • groupId · string (uuid) · required
  • userId · string (uuid) · required

Response 200 · application/json

  • groupId · string (uuid) · required
  • userId · string (uuid) · required
  • user · object · required
    • id · string (uuid) · required
    • email · string (email) | null · required
    • name · string | null · required
    • image · string | null · required
    • bot · object | null
      • ownerId · string (uuid) · required
      • ownerName · string | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

DELETE /api/v1/workspaces/{workspaceId}/groups/{groupId}/members/{userId}

Remove a user from a group. Requires groups.manage. Refused (409) when the group is the only remaining full subject of a restricted block or a collection and this user is its last member (D6). Bumps the access generation. Returns the membership that was removed.

removeGroupMember · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required
  • groupId · string (uuid) · required
  • userId · string (uuid) · required

Response 200 · application/json

  • groupId · string (uuid) · required
  • userId · string (uuid) · required
  • user · object · required
    • id · string (uuid) · required
    • email · string (email) | null · required
    • name · string | null · required
    • image · string | null · required
    • bot · object | null
      • ownerId · string (uuid) · required
      • ownerName · string | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

GET /api/v1/workspaces/{workspaceId}/invitations

List the workspace's invitations (pending first, newest first). Requires invitations.manage. Tokens are never returned again; only createInvitation ever shows one.

listInvitations · token scope: admin:read

Path parameters

  • workspaceId · string (uuid) · required

Query parameters

  • cursor · string · length 1–∞
  • limit · integer · 1–100

Response 200 · application/json

  • items · object[] · required
    • id · string (uuid) · required
    • workspaceId · string (uuid) · required
    • email · string (email) · required
    • role · "admin" | "member" | "guest" · required
    • invitedBy · string (uuid) · required
    • expiresAt · string (date-time) · required
    • acceptedAt · string (date-time) | null · required
    • createdAt · string (date-time) · required
  • nextCursor · string | null · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

POST /api/v1/workspaces/{workspaceId}/invitations

Invite an email address. Requires invitations.manage; the invited role may not exceed the inviter's own, and owner is not invitable (ownership is transferred). At most one un-accepted invitation exists per (workspace, lower(email)); a repeat invite replaces the pending one. The token is 32 CSPRNG bytes stored HASHED, single-use, 14-day expiry, and appears exactly once: in this response's url. The response never reveals whether the address already has an account.

createInvitation · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required

Request body · application/json, required

  • email · string (email) · required, length 0–320
  • role · "admin" | "member" | "guest" · required

Response 200 · application/json

  • id · string (uuid) · required
  • workspaceId · string (uuid) · required
  • email · string (email) · required
  • role · "admin" | "member" | "guest" · required
  • invitedBy · string (uuid) · required
  • expiresAt · string (date-time) · required
  • acceptedAt · string (date-time) | null · required
  • createdAt · string (date-time) · required
  • url · string · required
  • mailed · boolean · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

DELETE /api/v1/workspaces/{workspaceId}/invitations/{invitationId}

Revoke an invitation by deleting its row. The token stops working immediately. Requires invitations.manage. Returns the revoked invitation.

revokeInvitation · token scope: admin:write

Path parameters

  • workspaceId · string (uuid) · required
  • invitationId · string (uuid) · required

Response 200 · application/json

  • id · string (uuid) · required
  • workspaceId · string (uuid) · required
  • email · string (email) · required
  • role · "admin" | "member" | "guest" · required
  • invitedBy · string (uuid) · required
  • expiresAt · string (date-time) · required
  • acceptedAt · string (date-time) | null · required
  • createdAt · string (date-time) · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object

POST /api/v1/invitations/accept

Redeem an invitation token and join its workspace. Deliberately OUTSIDE the /workspaces/:workspaceId scope (ADR-0016 D11): the membership guard would 404 the very person being invited. Requires a session and matches on its email (lower(email) on both sides; plus-addressing NOT stripped). The invited role is re-validated against the INVITER's current role at accept time. insert … on conflict do nothing on workspace_member, so an existing membership wins and a second acceptance cannot change a role. Returns the resulting membership (existing or new).

acceptInvitation · token scope: session only

Request body · application/json, required

  • token · string · required, length 1–200

Response 200 · application/json

  • workspaceId · string (uuid) · required
  • userId · string (uuid) · required
  • role · "owner" | "admin" | "member" | "guest" · required
  • user · object · required
    • id · string (uuid) · required
    • email · string (email) | null · required
    • name · string | null · required
    • image · string | null · required
    • bot · object | null
      • ownerId · string (uuid) · required
      • ownerName · string | null · required
  • joinedAt · string (date-time) · required

Response default · application/json

  • error · object · required
    • code · "bad_request" | "validation_failed" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal" · required
    • message · string · required
    • reason · string · length 1–64
    • params · object