Workflow states

Direct-id workflow-state operations. List and create states under a Project; these endpoints update, move, hide, default, or remove an existing state.

Update project status

Rename, recolor, or re-bucket one project workflow status (project admin). Only pass fields to change. Re-bucketing cannot remove the final unstarted, started, or completed status and reports required_type when unsafe.

PATCH /v1/workspaces/{workspaceId}/states/{stateId}

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

Response: the resulting object as JSON.

Delete project status

Delete one project workflow status (project admin). The consequence is mandatory: move re-files every Task into the sibling targetStateId; archive archives the Tasks and parks them on the surviving default. Tasks are never orphaned. Unsafe requests report stable last_state, required_type, move_target_required, or move_target_invalid codes.

DELETE /v1/workspaces/{workspaceId}/states/{stateId}

curl -X DELETE -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/states/STATE_ID?disposition=move"

Response: the resulting object as JSON.

Move project status

Move a project workflow status to a zero-based index within its existing type bucket (project admin). A status never crosses workflow buckets through this operation.

POST /v1/workspaces/{workspaceId}/states/{stateId}/move

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

Response: the resulting object as JSON.

Set default project status

Make one workflow status the default for new Tasks in its project (project admin). The previous default is cleared.

POST /v1/workspaces/{workspaceId}/states/{stateId}/default

curl -X POST "https://api.dotby.app/v1/workspaces/acme/states/STATE_ID/default" \
  -H "Authorization: Bearer $DOTBY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Response: the resulting object as JSON.

Set project status visibility

Set or clear the project-wide collapsed-by-default hint for one workflow status (project admin). This is display metadata only: the status remains usable.

PATCH /v1/workspaces/{workspaceId}/states/{stateId}/visibility

curl -X PATCH "https://api.dotby.app/v1/workspaces/acme/states/STATE_ID/visibility" \
  -H "Authorization: Bearer $DOTBY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hidden":true}'

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.