REST API & MCP reference

Authenticate once with an org-scoped key, then drive DarkBird from a script, an internal dashboard, or an AI assistant.

DarkBird exposes the same service layer the web app uses through two surfaces: a REST API (/api/v1/*) and an MCP server (/api/mcp) that an MCP-compatible client such as Claude Code can drive directly. Both authenticate identically, with an org-scoped API key rather than a user login.

Generate an API key

Go to Settings → API Keys (Owners and Admins). Name the key after whatever will use it, and click Generate.

Keys look like dk_live_ followed by 32 random URL-safe characters. Settings lists only the first 14 (dk_live_ plus six) so you can tell keys apart. Revoking is immediate and permanent — anything using that key starts getting 401s on its next request.

Authentication

Every request to both surfaces sends the key as a bearer token. The base URL is https://darkbird.app.

curl https://darkbird.app/api/v1/projects \
  -H "Authorization: Bearer dk_live_your_key_here"

REST endpoints

Create a project

curl -X POST https://darkbird.app/api/v1/projects \
  -H "Authorization: Bearer dk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warehouse Camera Refresh",
    "client": "Acme Logistics"
  }'

name and client are both required and must be non-empty. phaseGroupId is optional — pass a Phase Set id to scope the project's work plan to that set, or omit it (or send null) to show all phases.

Create an Install Card

The POST body is validated against the same schema the card editor uses, so anything the editor accepts the API accepts. Required: name, categoryId (may be null), options, and tickets.

{
  "name": "Access Point Installation",
  "description": "Mount and configure a wireless access point.",
  "categoryId": null,
  "behavior": "Standard",
  "options": [
    {
      "id": "opt-base",
      "name": "Base",
      "unitOfMeasureId": null,
      "unitOfMeasureName": "Each"
    }
  ],
  "tickets": [
    {
      "id": "tkt-1",
      "name": "Mount and terminate AP",
      "phaseId": null,
      "optionId": "opt-base",
      "resourceId": null,
      "quantityRanges": [
        { "id": "qr-1", "startQty": 1, "endQty": 10, "hoursPerUnit": 2 },
        { "id": "qr-2", "startQty": 11, "endQty": null, "hoursPerUnit": 1.5 }
      ],
      "checklist": [
        { "id": "chk-1", "name": "Confirm PoE budget", "completed": false }
      ]
    }
  ]
}

You generate the id values yourself — they only need to be unique within the card, and each ticket's optionId must match one of the options. Name the always-included option exactly "Base" or "Standard", or it renders as an optional add-on instead (see Card behavior modes).

MCP server

The MCP endpoint is https://darkbird.app/api/mcp, using the Streamable HTTP transport with the same bearer key. It is stateless — no session is retained between requests — so clients should not expect server-side conversation state.

Connect Claude Code

claude mcp add --transport http darkbird https://darkbird.app/api/mcp \
  --header "Authorization: Bearer dk_live_your_key_here"

Share the connection with your team

To check the connection into a repo so your whole team gets it, add DarkBird to .mcp.json and reference the key as an environment variable rather than pasting it in — that way the config is shareable and the key never lands in git:

{
  "mcpServers": {
    "darkbird": {
      "type": "http",
      "url": "https://darkbird.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ${DARKBIRD_API_KEY}"
      }
    }
  }
}

Other MCP clients

Any client that speaks the Streamable HTTP transport and lets you set a custom header can connect: point it at https://darkbird.app/api/mcp and send Authorization: Bearer <your-key>. DarkBird does not use OAuth for this surface — authentication is the API key header, nothing else.

Available tools