Initiatives

The strategy layer above projects. Initiatives are a workspace feature module and are OFF by default — every endpoint here fails with an actionable error until a workspace admin enables the module in Settings → Features.

List initiatives

List a workspace’s initiatives (the strategy layer above projects): id, name, state (proposed | planned | active | completed | canceled), health (onTrack | atRisk | offTrack, from the newest posted update, null when none), priority, leadUserId, start/target dates (ms epoch), parentId (a sub-initiative’s parent, null for roots), one-line summary, and lastUpdateAt. truncated: true means the workspace holds more than the 500 returned. Initiatives are OFF by default — this fails with a clear message until a workspace admin enables them in Settings → Features.

GET /v1/workspaces/{workspaceId}/initiatives

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/initiatives"

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 initiative

Create an initiative in a workspace (manager+). Optional: leadUserId (see resolve_member), start/target dates (ms epoch), and parentId to create it as a sub-initiative. Returns the new initiative id. Set the summary or other fields afterwards with update_initiative.

POST /v1/workspaces/{workspaceId}/initiatives

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

Get one initiative: the list_initiatives fields plus labels, resources (links), ancestors (parent chain, root first), leadName, and its projects — the EFFECTIVE set (this initiative’s own projects plus its sub-initiatives’), only those you can access; effectiveProjectTotal is the honest total (effectiveProjectTotalIsFloor marks a “100+” floor). include: ["description"] adds descriptionText (plain text — can be long, so never returned unless asked).

GET /v1/workspaces/{workspaceId}/initiatives/{initiativeId}

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/initiatives/INITIATIVE_ID"

Response: the resulting object as JSON.

Update initiative

Update an initiative’s fields (manager+). Only pass the fields to change — values only, no clearing over MCP. summary is the one-line plain-text description (max 280 chars). Health is NOT set here — post_initiative_update is the only health write (health always comes from the newest update).

PATCH /v1/workspaces/{workspaceId}/initiatives/{initiativeId}

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

Response: the resulting object as JSON.

Get initiative progress

The task rollup across an initiative’s effective projects (sub-initiatives included, accessible-to-you only): issueCount, completedCount, stateTypeCounts by the five buckets (backlog | unstarted | started | completed | canceled), plus effectiveProjectCount/Total and a capped flag when a very large project truncated the count. Use it to answer “is this initiative on track?” together with health from list_initiative_updates.

GET /v1/workspaces/{workspaceId}/initiatives/{initiativeId}/progress

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/initiatives/INITIATIVE_ID/progress"

Response: the resulting object as JSON.

List initiative updates

An initiative’s posted health updates, newest first: id, health (onTrack | atRisk | offTrack), bodyText (plain text), authorId/authorName, createdAt (ms epoch). The newest row drives the initiative’s current health chip. Answers “what changed lately” — limit defaults to 10 (max 50), no pagination.

GET /v1/workspaces/{workspaceId}/initiatives/{initiativeId}/updates

curl -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/initiatives/INITIATIVE_ID/updates?limit=25"

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.

Post initiative update

Post a health update on an initiative (the initiative’s lead, or manager+): health is onTrack | atRisk | offTrack, with an optional plain-text body. This is the ONLY way to set an initiative’s health — the newest update drives the health shown everywhere.

POST /v1/workspaces/{workspaceId}/initiatives/{initiativeId}/updates

curl -X POST "https://api.dotby.app/v1/workspaces/acme/initiatives/INITIATIVE_ID/updates" \
  -H "Authorization: Bearer $DOTBY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"health":"onTrack"}'

Response: the resulting object as JSON.

Add projects to initiative

Add projects to an initiative (manager+). Projects must be in the same workspace and not archived; already-joined projects are skipped (no error).

POST /v1/workspaces/{workspaceId}/initiatives/{initiativeId}/projects

curl -X POST "https://api.dotby.app/v1/workspaces/acme/initiatives/INITIATIVE_ID/projects" \
  -H "Authorization: Bearer $DOTBY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"projectIds":["PROJECT_ID"]}'

Response: the resulting object as JSON.

Remove project from initiative

Remove a project from an initiative (manager+). The project itself is untouched; removing a project that is not in the initiative is a no-op.

DELETE /v1/workspaces/{workspaceId}/initiatives/{initiativeId}/projects/{projectId}

curl -X DELETE -H "Authorization: Bearer $DOTBY_TOKEN" \
  "https://api.dotby.app/v1/workspaces/acme/initiatives/INITIATIVE_ID/projects/ENG"

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.