Pages

Pages form the workspace wiki (omit projectId) or a project’s docs (pass projectId). Page bodies accept PLAIN TEXT — each line becomes a paragraph — so you never have to build TipTap JSON.

Get page tree

Compatibility page-tree read for installed clients. Returns the historical nested-array shape, but very large trees use a byte-safe prefix; use get_page_tree_v2 when completeness matters.

GET /v1/workspaces/{workspaceId}/pages

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

Response: the resulting object as JSON.

Create page

Create a page in the workspace wiki (omit projectId) or in a project. Optional parent page nests it; body starts empty — write it with update_page_body.

POST /v1/workspaces/{workspaceId}/pages

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

Response: the resulting object as JSON.

Get page tree with completeness

List a byte-safe page-tree prefix with an explicit { rows, complete } envelope. projectId omitted means the workspace wiki; when complete is false, narrow the project/scope or continue in the interactive Pages surface.

GET /v1/workspaces/{workspaceId}/pages/tree-v2

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/pages/tree-v2"

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.

Get page

Get one page: title, TipTap-JSON body, plain-text bodyText, folder, parent, and metadata.

GET /v1/workspaces/{workspaceId}/pages/{pageId}

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

Response: the resulting object as JSON.

Rename page

Rename a page.

PATCH /v1/workspaces/{workspaceId}/pages/{pageId}

curl -X PATCH "https://api.dotby.app/v1/workspaces/acme/pages/PAGE_ID" \
  -H "Authorization: Bearer $DOTBY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Ship the onboarding flow"}'

Response: the resulting object as JSON.

Search pages

Full-text search pages by title/content across the wiki or one project. Returns the matching page rows.

GET /v1/workspaces/{workspaceId}/pages/search

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/pages/search?query=onboarding"

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.

Search pages with completeness

Search pages by title/content with an explicit complete flag. When false, narrow the term or scope because byte-safe candidate limits may have omitted matches.

GET /v1/workspaces/{workspaceId}/pages/search-v2

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/pages/search-v2?query=onboarding"

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.

Update page body

Replace a page’s body. body is always Markdown, converted and validated as rich text by the server; no format flag or TipTap JSON is needed. An empty body clears the page.

PATCH /v1/workspaces/{workspaceId}/pages/{pageId}/body

curl -X PATCH "https://api.dotby.app/v1/workspaces/acme/pages/PAGE_ID/body" \
  -H "Authorization: Bearer $DOTBY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"Plain text content."}'

Response: the resulting object as JSON.

Move page

Move a page in the tree: under a new parent (or top level when omitted), after a sibling.

POST /v1/workspaces/{workspaceId}/pages/{pageId}/move

curl -X POST "https://api.dotby.app/v1/workspaces/acme/pages/PAGE_ID/move" \
  -H "Authorization: Bearer $DOTBY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"parentPageId":"PAGE_ID"}'

Response: the resulting object as JSON.

Set page folder

File a top-level page into a folder, or omit folderId to move it out of any folder.

PATCH /v1/workspaces/{workspaceId}/pages/{pageId}/folder

curl -X PATCH "https://api.dotby.app/v1/workspaces/acme/pages/PAGE_ID/folder" \
  -H "Authorization: Bearer $DOTBY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folderId":"FOLDER_ID"}'

Response: the resulting object as JSON.

Archive page

Archive a page (and its subtree). Reversible in the app; never a hard delete.

POST /v1/workspaces/{workspaceId}/pages/{pageId}/archive

curl -X POST "https://api.dotby.app/v1/workspaces/acme/pages/PAGE_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.