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

List the page tree: the workspace wiki when projectId is omitted, or one project’s pages. Returns nested nodes with ids, titles, and folder grouping.

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

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.

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.

Update page body

Replace a page’s body. Accepts PLAIN TEXT (each line becomes a paragraph) or a full TipTap JSON document string — plain text is ramped server-side (Spec 81 D18), so agents never have to build TipTap JSON.

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.