Project folders

Folders group projects in the sidebar, one sublevel deep. A folder is a label, never a lock — filing a project changes navigation, not who can open it.

List project folders

List a workspace’s active project folders, position-sorted. parentGroupId is the parent folder for a subfolder, null for a top-level folder (folders nest one level). You only receive folders whose subtree holds a project you can open (managers also see empty ones). Folders are purely visual grouping — they never affect access.

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

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/project-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 project folder

Create a project folder (manager+). Pass parentGroupId to create it as a subfolder of a top-level folder (folders nest one level deep). A folder is a visual label — it never changes who can open the projects inside.

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

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

Rename or re-describe a project folder, or change its icon (manager+). Only pass the fields to change. To move it in the tree, use move_project_folder.

PATCH /v1/workspaces/{workspaceId}/project-folders/{groupId}

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

Response: the resulting object as JSON.

Move project folder

Re-file a project folder under a top-level folder, or omit parentGroupId to promote it to the top level (manager+). Folders nest one level deep, so a folder that has subfolders cannot itself be moved under another.

PATCH /v1/workspaces/{workspaceId}/project-folders/{groupId}/parent

curl -X PATCH "https://api.dotby.app/v1/workspaces/acme/project-folders/GROUP_ID/parent" \
  -H "Authorization: Bearer $DOTBY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"parentGroupId":"GROUP_ID"}'

Response: the resulting object as JSON.

Archive project folder

Archive a project folder (manager+). Its projects keep their filing and simply show as unfiled while it is archived; restoring the folder in the app brings the grouping back.

POST /v1/workspaces/{workspaceId}/project-folders/{groupId}/archive

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