dotby REST API

The dotby REST API lives at https://api.dotby.app/v1. It is a projection of the same connector registry that serves MCP: full CRUD over tasks, projects, sprints, pages, and initiatives, always with the token owner’s own permissions. The complete machine-readable surface is one request away:

curl "https://api.dotby.app/v1/openapi.json"

That OpenAPI 3.1 document is the source of truth — prefer it over memory for exact schemas.

Authentication

Send a bearer token on every request. Two token types work, same header:

• An OAuth access token from dotby auth login (the dotby CLI).
• A personal access key dotby_pat_…, created in the app under Settings → API keys.

curl -H "Authorization: Bearer $DOTBY_TOKEN" "https://api.dotby.app/v1/me"

API access is a Pro feature — a Free workspace answers 403 with code upgrade_required. Start every session with GET /v1/me to learn your user, workspaces, roles, and plans.

CLI

The official CLI is a thin client of this API. The npm package is named dotby-cli; the command it installs is dotby:

npm i -g dotby-cli   # then: dotby issue list
npx dotby-cli --help # or run it without installing

The published wrapper has no postinstall script — the binary for your platform arrives as an @gattunelabs/cli-* optional dependency, so the install works under --ignore-scripts and under pnpm/yarn script blocking, which is what agent and CI installs run. Authenticate without a browser by piping a personal access key: printf %s "$DOTBY_PAT" | dotby auth login --with-token (or just set DOTBY_TOKEN).

Addressing

Use human identifiers or raw ids interchangeably — reads AND writes:

• Workspace: slug or id (/workspaces/acme or /workspaces/<id>).
• Task: KEY-N or id (ENG-42 works everywhere an issue id is expected in a path).
• Project: KEY or id (ENG).

Pagination

Every list endpoint returns the envelope { data, has_more, next_cursor }. While has_more is true, pass next_cursor back as cursor. limit defaults to 25, max 100. Page until has_more is false before concluding something is absent — post-filters can thin a page without ending the list.

Rate limits

Per token: 300 reads/min and 60 writes/min. A 429 carries Retry-After in seconds — wait that long, then retry. Do not busy-retry.

Idempotency

Send an Idempotency-Key header (any unique string, e.g. a UUID) on every POST. Replaying the same key with the same body returns the original result instead of duplicating the write; the same key with a DIFFERENT body is a 409 idempotency_conflict.

Delta polling

To sync changes instead of re-reading everything, poll tasks with updatedAfter (ms epoch):

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/issues?updatedAfter=1754006400000"

It returns only tasks meaningfully edited STRICTLY after that time — page until next_cursor is null, then remember your poll time. Caveat: legacy rows that have never been edited since update-stamping began are excluded, so do one full crawl first and use updatedAfter for increments only.

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.