Collections

The top level of the page tree, and who may see each one.

4 operations. Every path is relative to the instance origin; every response body is JSON unless stated. See API for authentication, errors and pagination.

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

List the collections of a workspace, filtered by visibility (ADR-0016 D2): open and closed collections are listed for every member, private ones only for their explicit members. Each entry carries the caller's effective accessLevel — null means "listed by name only" (a closed collection a member may see but not open).

listCollections · token scope: content: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
  • icon · string | null — required
  • description · string | null — required
  • visibility · "open" | "closed" | "private" — required
  • accessLevel · "read" | "comment" | "edit" | "full" | 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

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

Create a collection in a workspace.

createCollection · token scope: content:write

Path parameters

• workspaceId · string (uuid) — required

Request body — application/json, required

• name · string — required, length 1–200
• icon · string — length 0–2048
• description · string — length 0–280
• visibility · "open" | "closed" | "private" — required

Response 200 — application/json

• id · string (uuid) — required
• workspaceId · string (uuid) — required
• name · string — required
• icon · string | null — required
• description · string | null — required
• visibility · "open" | "closed" | "private" — required
• accessLevel · "read" | "comment" | "edit" | "full" | 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

PATCH /api/v1/workspaces/{workspaceId}/collections/{collectionId}

Update a collection name, icon, description and/or visibility. Changing visibility requires full on the collection and bumps the workspace access generation; explicit collection_member rows survive it.

updateCollection · token scope: content:write

Path parameters

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

Request body — application/json, required

• name · string — length 1–200
• icon · string | null
• description · string | null
• visibility · "open" | "closed" | "private"

Response 200 — application/json

• id · string (uuid) — required
• workspaceId · string (uuid) — required
• name · string — required
• icon · string | null — required
• description · string | null — required
• visibility · "open" | "closed" | "private" — required
• accessLevel · "read" | "comment" | "edit" | "full" | 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

DELETE /api/v1/workspaces/{workspaceId}/collections/{collectionId}

Delete a collection and everything in it — irreversible, and it does NOT go through the trash. Requires the collections.delete capability (admin/owner) AND full on the collection (ADR-0016 D1: no role grants implicit access). Refuses (409) while the collection still holds live pages or databases — empty it first. Its collection_member rows go with it. Returns the deleted collection.

deleteCollection · token scope: content:write

Path parameters

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

Response 200 — application/json

• id · string (uuid) — required
• workspaceId · string (uuid) — required
• name · string — required
• icon · string | null — required
• description · string | null — required
• visibility · "open" | "closed" | "private" — required
• accessLevel · "read" | "comment" | "edit" | "full" | 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