API: export data, build reports, and extend Flying Donut

The REST API gives you programmatic access to your project data for custom reporting, automation, backups, and third-party integrations.

Browse all docs

What you can do with the API

The Flying Donut API provides read and write access to project data over HTTPS. All data is exchanged as JSON. Common use cases include:

  • Export project data for custom dashboards and analytics
  • Generate reports tailored to your organization's needs
  • Create or update backlog cards programmatically
  • Automate repetitive workflows (e.g., create sprint templates, import external data)
  • Build custom integrations with internal tools
  • Keep a local backup of your project data

Getting started with the API

Enable API Integration for your project from Project Settings → Integrations. Only project Administrators or Owners can enable API access.

  • All API requests use HTTPS at https://www.flyingdonut.io/api/
  • Responses are JSON formatted
  • Create operations require a valid project member username in the request body
  • Update operations use optimistic locking — include the current attribute version to avoid conflicts
  • Force updates by setting version to -1 (use with caution)

Key endpoints

The API covers the main entities in your project. Here is a summary of the most commonly used endpoints:

  • GET /api/projects/{projectId}/backlog/buckets — list all backlog buckets
  • GET /api/projects/{projectId}/backlog/buckets/{bucketId}/items — list cards in a bucket
  • POST /api/projects/{projectId}/backlog/buckets/{bucketId}/items — create one or more cards
  • GET /api/projects/{projectId}/iterations — list all sprints
  • GET /api/projects/{projectId}/iterations/{iterationId}/items — list cards in a sprint
  • GET /api/projects/{projectId}/iterations/{iterationId}/burndown-chart — get burndown data
  • GET /api/projects/{projectId}/items/{itemId} — get card details
  • PUT /api/projects/{projectId}/items/{itemId} — update a card
  • GET /api/projects/{projectId}/items/{itemId}/tasks — list tasks on a card
  • POST /api/projects/{projectId}/items/{itemId}/tasks — create a task on a card

Data model: versioned attributes

Most attributes in the Flying Donut API use a versioned structure. Instead of a flat value, you will see:

{
  "title": {
    "value": "Implement login flow",
    "version": 3
  },
  "estimate": {
    "value": 8,
    "version": 1
  }
}

When updating an attribute, include the current version. If another update has occurred since you read the data, the API returns the current values so you can resolve the conflict. Use version: -1 to force an update regardless of the current version.

Example: creating a card via the API

Create a card by sending a POST request with the card data:

POST /api/projects/{projectId}/backlog/buckets/{bucketId}/items

{
  "username": "jane.smith",
  "title": {
    "value": "Add password strength indicator"
  },
  "summary": {
    "value": {
      "markdown": "Show a visual strength meter as users type their password."
    }
  },
  "estimate": {
    "value": "5"
  }
}

The API returns the full card object with generated IDs, timestamps, and default attribute values. You can create multiple cards in a single request by sending a JSON array.

Example: exporting sprint data for reporting

Fetch sprint cards and burndown data to build a custom sprint report:

  • GET /api/projects/{projectId}/iterations to find the active sprint ID
  • GET /api/projects/{projectId}/iterations/{id}/items to get all sprint cards with status, estimates, and task counters
  • GET /api/projects/{projectId}/iterations/{id}/burndown-chart to get daily remaining hours and original estimates
  • Combine the data in a script or dashboard tool to generate velocity charts, completion rates, or custom KPIs

Example: A team lead writes a Python script that runs after each sprint completion. It fetches the burndown data and card list, calculates velocity (story points completed), and posts a summary to the team's Slack channel with a chart attached.

Timestamps and data types

  • Timestamps use the $date wrapper: { '$date': '2024-01-15T10:30:00.000Z' }
  • All timestamps are in ISO 8601 format (UTC)
  • Object IDs use the $oid wrapper: { '$oid': '54744060c955ca8169c61ee6' }
  • Task estimates are in hours — use decimals for minutes (e.g., 0.5 for 30 minutes)
  • Card estimates (story points) are integers

Common questions

Is there rate limiting on the API?+
The API is designed for reasonable use. Avoid polling in tight loops — use webhooks for real-time updates when available.
Does the API support authentication tokens?+
Currently, write operations require a valid project member username in the payload. OAuth2-based authentication is planned.
Can I delete cards via the API?+
The current API focuses on read and create/update operations. Card deletion is managed through the UI.
Can I access sprint burndown history after completion?+
Yes. The burndown endpoint works for completed sprints — the data is preserved for historical analysis.

Build custom workflows and reports with the API

Export data, automate card creation, and extend Flying Donut with the REST API.

Browse all docs