Projects
Este conteúdo não está disponível em sua língua ainda.
Projects own tasks, workflow states (board columns), labels, custom properties, and sprints. Everything nested under /projects/{projectId} lives on this page. Address a project by its short uppercase KEY (e.g. ENG) or by id.
List projects
Section titled “List projects”List the non-archived projects in a workspace the user can access.
GET /v1/workspaces/{workspaceId}/projects
curl -H "Authorization: Bearer $DOTBY_TOKEN" \ "https://api.dotby.app/v1/workspaces/acme/projects"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
Section titled “Create project”Create a project in a workspace (manager+). Seeds the default board columns.
POST /v1/workspaces/{workspaceId}/projects
curl -X POST "https://api.dotby.app/v1/workspaces/acme/projects" \ -H "Authorization: Bearer $DOTBY_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name":"Platform work"}'Response: the resulting object as JSON.
Get project
Section titled “Get project”Get one project by its short KEY (e.g. “ENG”), including the viewer’s role.
GET /v1/workspaces/{workspaceId}/projects/{key}
curl -H "Authorization: Bearer $DOTBY_TOKEN" \ "https://api.dotby.app/v1/workspaces/acme/projects/ENG"Response: the resulting object as JSON.
List states
Section titled “List states”List a project’s workflow states (board columns), left to right. Every state accepts writes. A state with hiddenAt renders collapsed by default in status-grouped views (its issues still count everywhere) — a display hint only, never a restriction. Any disabledAt timestamp is a retired flag from an older version and carries no meaning; ignore it.
GET /v1/workspaces/{workspaceId}/projects/{projectId}/states
curl -H "Authorization: Bearer $DOTBY_TOKEN" \ "https://api.dotby.app/v1/workspaces/acme/projects/ENG/states"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.
List labels
Section titled “List labels”List a project’s labels.
GET /v1/workspaces/{workspaceId}/projects/{projectId}/labels
curl -H "Authorization: Bearer $DOTBY_TOKEN" \ "https://api.dotby.app/v1/workspaces/acme/projects/ENG/labels"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.
List custom properties
Section titled “List custom properties”List a project’s custom property definitions (Spec 109): id, name, kind (text | number | date | checkbox | select | member | url), isMulti, required, select options (stable ids), and the issue-type scoping (typeIds; absent = applies to every task). Rejects when the project’s custom-properties feature is off. Defs with archivedAt set are DISABLED — read-only history; never write to them. Use the active def ids as keys for set_custom_field and create_issue.customFields.
GET /v1/workspaces/{workspaceId}/projects/{projectId}/fields
curl -H "Authorization: Bearer $DOTBY_TOKEN" \ "https://api.dotby.app/v1/workspaces/acme/projects/ENG/fields"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.
List issues
Section titled “List issues”List the non-archived issues in a project (board-ready: state, assignees, labels).
GET /v1/workspaces/{workspaceId}/projects/{projectId}/issues
curl -H "Authorization: Bearer $DOTBY_TOKEN" \ "https://api.dotby.app/v1/workspaces/acme/projects/ENG/issues"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 issue
Section titled “Create issue”Create an issue in a project. description is plain text. Returns the new issue. The creator is auto-subscribed and any assignees notified.
POST /v1/workspaces/{workspaceId}/projects/{projectId}/issues
curl -X POST "https://api.dotby.app/v1/workspaces/acme/projects/ENG/issues" \ -H "Authorization: Bearer $DOTBY_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"title":"Ship the onboarding flow"}'Response: the resulting object as JSON.
Update project
Section titled “Update project”Update a project’s fields (manager+). Only pass the fields to change.
PATCH /v1/workspaces/{workspaceId}/projects/{projectId}
curl -X PATCH "https://api.dotby.app/v1/workspaces/acme/projects/ENG" \ -H "Authorization: Bearer $DOTBY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"Platform work"}'Response: the resulting object as JSON.
Archive project
Section titled “Archive project”Archive a project (soft delete — reversible in the app).
POST /v1/workspaces/{workspaceId}/projects/{projectId}/archive
curl -X POST "https://api.dotby.app/v1/workspaces/acme/projects/ENG/archive" \ -H "Authorization: Bearer $DOTBY_TOKEN" \ -H "Idempotency-Key: $(uuidgen)"Response: the resulting object as JSON.
Set project folder
Section titled “Set project folder”File a project into a project folder, or omit groupId to move it out of any folder (manager+). Filing is purely visual — it never changes who can open the project.
PATCH /v1/workspaces/{workspaceId}/projects/{projectId}/folder
curl -X PATCH "https://api.dotby.app/v1/workspaces/acme/projects/ENG/folder" \ -H "Authorization: Bearer $DOTBY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"groupId":"GROUP_ID"}'Response: the resulting object as JSON.
List cycles
Section titled “List cycles”List a project’s cycles (sprints) with status (upcoming | active | completed) and date ranges.
GET /v1/workspaces/{workspaceId}/projects/{projectId}/cycles
curl -H "Authorization: Bearer $DOTBY_TOKEN" \ "https://api.dotby.app/v1/workspaces/acme/projects/ENG/cycles"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 cycle
Section titled “Create cycle”Create a cycle (sprint) in a project. Dates are ms epoch; ranges must not overlap an existing cycle.
POST /v1/workspaces/{workspaceId}/projects/{projectId}/cycles
curl -X POST "https://api.dotby.app/v1/workspaces/acme/projects/ENG/cycles" \ -H "Authorization: Bearer $DOTBY_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{"name":"Platform work","startDate":1754006400000,"endDate":1756684800000}'Response: the resulting object as JSON.
Errors
Section titled “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_requiredmeans 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: sameIdempotency-Key, different body. Mint a new key.429—rate_limited: back off for the number of seconds inRetry-After, then retry.400—validation_failed: the request shape is wrong. Fix the request; retrying unchanged will fail again.