Page folders

Folders group top-level pages in the wiki or in one project. Create folders first when importing a tree, then file pages into them.

List page folders

List the page folders of the wiki (omit projectId) or one project.

GET /v1/workspaces/{workspaceId}/page-folders

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/page-folders"

Response: a list envelope { data, has_more, next_cursor }. While has_more is true, pass next_cursor back as cursor to get the next page.

Create page folder

Create a page folder (an imported wiki tree needs folders first — D18).

POST /v1/workspaces/{workspaceId}/page-folders

curl -X POST "https://api.dotby.app/v1/workspaces/acme/page-folders" \
  -H "Authorization: Bearer $DOTBY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"Platform work"}'

Response: the resulting object as JSON.

Update page folder

Rename a page folder or change its icon. Only pass the fields to change.

PATCH /v1/workspaces/{workspaceId}/page-folders/{folderId}

curl -X PATCH "https://api.dotby.app/v1/workspaces/acme/page-folders/FOLDER_ID" \
  -H "Authorization: Bearer $DOTBY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Platform work"}'

Response: the resulting object as JSON.

Archive page folder

Archive a page folder (its pages fall back to the top level).

POST /v1/workspaces/{workspaceId}/page-folders/{folderId}/archive

curl -X POST "https://api.dotby.app/v1/workspaces/acme/page-folders/FOLDER_ID/archive" \
  -H "Authorization: Bearer $DOTBY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Response: the resulting object as JSON.

Errors

Every error is an RFC 9457 application/problem+json body with a machine-stable code. Branch on the code, not the message:

• 401 — unauthenticated / invalid_token: the bearer token is missing, expired, or revoked. Re-authenticate; do not retry as-is.
• 403 — insufficient_scope / forbidden / upgrade_required: the token works but may not do this. upgrade_required means the workspace is not on Pro.
• 404 — not_found_or_forbidden: the resource does not exist for this token. Never probe for existence.
• 409 — idempotency_conflict: same Idempotency-Key, different body. Mint a new key.
• 429 — rate_limited: back off for the number of seconds in Retry-After, then retry.
• 400 — validation_failed: the request shape is wrong. Fix the request; retrying unchanged will fail again.