Build powerful workflows with the Flying Donut API

Manage projects, sprints, cards, and tasks with a modern JSON API built for personal automation and system integrations.

Browse all docs

Get started

Flying Donut API v2 is available at https://api.flyingdonut.io/api/v2. It uses HTTPS, JSON request and response bodies, and Bearer authentication.

Explore the complete, endpoint and schema reference in the interactive API documentation.

  • Create a Personal API Token in Account Settings → API Access for scripts, tools, and MCP servers acting as you
  • Create a Service Account in Workspace Settings → Service Accounts for CI/CD, reporting, and other system integrations
  • Assign each Service Account only to the workspace projects it needs to access
  • Store tokens securely: each token is shown once when it is created and cannot be retrieved later

Authenticate requests

Send a token in the Authorization header. Personal tokens act with their owner's existing permissions. Service Account tokens act only within their assigned projects.

curl "https://api.flyingdonut.io/api/v2/projects/{projectId}" \
  -H "Authorization: Bearer fd_pat_your_token"

Tokens start with fd_pat_ for personal tokens or fd_sa_ for Service Account tokens. Never include tokens in URLs, query parameters, source control, or logs.

Core resources

The API returns clean JSON designed for straightforward integration. Resource IDs are strings, and dates use the ISO 8601 standard.

  • Projects: POST /projects; GET, PATCH, DELETE /projects/{projectId}
  • Backlog buckets: GET, POST /projects/{projectId}/backlog/buckets; PATCH, DELETE /backlog/buckets/{bucketId}
  • Sprints: GET, POST /projects/{projectId}/sprints; GET, PATCH, DELETE /sprints/{sprintId}
  • Backlog cards: GET /projects/{projectId}/backlog/cards; GET, POST /backlog/buckets/{bucketId}/cards
  • Sprint cards: GET, POST /sprints/{sprintId}/cards; GET, PATCH, DELETE /cards/{cardId}
  • Tasks: GET, POST /cards/{cardId}/tasks; GET, PATCH, DELETE /tasks/{taskId}

Use dedicated action endpoints for workflow changes. For example, start a sprint at /sprints/{sprintId}/start or complete it at /sprints/{sprintId}/complete. Cards use /cards/{cardId}/move,/cards/{cardId}/assign, and /cards/{cardId}/unassign; tasks use /tasks/{taskId}/move and /time/remaining.

Example: create a card

Create a card in a backlog bucket or sprint. The authenticated token determines the actor, so request bodies never include a username.

curl -X POST "https://api.flyingdonut.io/api/v2/backlog/buckets/{bucketId}/cards" \
  -H "Authorization: Bearer fd_pat_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Add password strength indicator",
    "description": "Show a visual strength meter as users type.",
    "estimate": 5
  }'

Pagination and updates

Collection endpoints accept an optional limit and opaque cursor. Continue fetching while nextCursor is not null.

{
  "data": [
    { "id": "…", "title": "Add password strength indicator" }
  ],
  "nextCursor": "opaque-cursor-or-null"
}

Updates use JSON Merge Patch. Send only the fields to change with Content-Type: application/merge-patch+json. Omitted fields are unchanged; send null to clear a nullable field.

Errors and access control

API errors use a consistent response shape. Handle the HTTP status and stable error code rather than parsing the message.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Request validation failed.",
    "details": []
  }
}
  • 400 INVALID_ID or INVALID_REQUEST: malformed IDs or invalid request data
  • 401 UNAUTHENTICATED: the Bearer token is missing, invalid, expired, or revoked
  • 403 FORBIDDEN: the authenticated token cannot access or change the project
  • 404 NOT_FOUND: the requested resource does not exist in the project
  • 422 INVALID_TRANSITION: the requested sprint or task workflow transition is not valid

Common questions

Which token should I use?+
Use a Personal API Token for tools acting on your behalf, including MCP servers, CLI tools, and personal scripts. Use a Service Account for shared, non-human integrations such as CI/CD systems, and assign it only to the projects it needs.
Can a Service Account access every workspace project?+
No. Workspace administrators explicitly assign projects to each Service Account. Requests to unassigned projects return 403 FORBIDDEN.
How do I rotate a token?+
Create a new token, update the integration, then revoke the previous token. Service Accounts can have multiple active tokens to support zero-downtime rotation.
How do I discover every endpoint and field?+
Use the interactive API documentation. It is generated from the running v2 API and includes request schemas, responses, and endpoint details.

Put the Flying Donut API to work

Use scoped bearer tokens and the complete OpenAPI reference to automate your Flying Donut workflow.

Browse all docs