API overview

Firefight exposes a JSON REST API for reading and writing incidents, reading your workspace’s configuration, and managing service catalog entries. Anything you can automate around your incident response, from declaring incidents out of your monitoring pipeline to syncing the catalog from your infrastructure, goes through this API.

Base URL and versioning

All endpoints live under a versioned path.

https://app.firefight.app/api/v1

The version is part of the URL. Breaking changes ship as a new version, so v1 responses stay stable.

Creating API keys

Create and manage keys under Settings → API Keys in the Firefight web app. Every key belongs to your workspace and can optionally carry an expiry date. The token itself starts with ff_ and is shown once, at creation time. Store it somewhere safe, because Firefight keeps only a hash.

There are two kinds of key.

Kind	Who can create it	What it can do
Service key	Workspace admins	A standalone integration identity with granular permissions you pick per resource and action. Use it for monitoring pipelines, CI, and other headless automation.
Personal token	Any member, for themselves	Acts as you. It reads everything you can see and can write nothing. Use it for your own scripts and agent sessions.

Personal tokens are deliberately read-only. If your automation needs to create or update anything, mint a service key with exactly the permissions it needs.

You can rename a key, edit a service key’s permissions, deactivate it temporarily, or delete it at any time from the same settings page.

Authentication

Pass your token in the Authorization header on every request.

Authorization: Bearer ff_4kWm2xPqR8vNcT6yBhJd3fLzGaU9sEnQoXwA

Requests without a valid token get a 401 response. Requests with a valid token that lacks the needed permission get a 403.

Resources and permissions

Service key permissions are a matrix of resources and actions. A key only holds the permissions you grant it, and each endpoint checks one specific pair.

Resource	Actions with effect	What they unlock
incidents	read, create, update	List, fetch, declare, and update incidents
severities	read	List your workspace’s severity levels
statuses	read	List your workspace’s incident statuses
incident_types	read	List your workspace’s incident types
custom_fields	read	List your workspace’s custom field definitions
catalog	read, create, update, delete	Read catalog types, and manage catalog entries
alerts	read	Search ingested alerts through the MCP server
policies	read	Dry-run alert routing through the MCP server

The alerts and policies resources currently apply only to MCP tools. There are no REST endpoints for them yet.

Tip

Grant the narrowest set that works. A key that only declares incidents from your alerting pipeline needs incidents:create and nothing else.

Rate limits

Each key may make up to 1,000 requests per minute. Beyond that, requests get a 429 response until the window resets. See Using the API for the error format.

Your first request

List the most recent incidents in your workspace.

curl https://app.firefight.app/api/v1/incidents \
  -H "Authorization: Bearer ff_4kWm2xPqR8vNcT6yBhJd3fLzGaU9sEnQoXwA"

{
  "incidents": [
    {
      "id": "0d9b2c1e-7f3a-4b8e-9c5d-2a6e8f1b4d70",
      "identifier": "INC-42",
      "name": "Checkout latency spike in eu-west",
      "summary": "p99 latency on the checkout service exceeded 4s.",
      "status": {
        "id": "b1f6a2d4-8c3e-4f5a-9b7d-1e2c3a4b5d6f",
        "name": "Investigating",
        "lifecycle_stage": "active"
      },
      "severity": {
        "id": "c7e2f9a1-3b4d-4c6e-8f0a-5d6b7c8e9f01",
        "name": "SEV2",
        "rank": 2
      },
      "type": null,
      "lead": {
        "id": "e4a8b2c6-1d3f-4e5a-b7c9-0f1a2b3c4d5e",
        "type": "user",
        "name": "Maja Kovac",
        "email": "maja@example.com"
      },
      "source": "datadog",
      "declared_by": null,
      "declared_at": "2026-07-18T09:12:44Z",
      "detected_at": null,
      "resolved_at": null,
      "created_at": "2026-07-18T09:12:44Z",
      "updated_at": "2026-07-18T09:40:02Z",
      "custom_fields": {},
      "visibility": "public"
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

From here, read Using the API for idempotent incident creation, error handling, and pagination, or set up outbound webhooks to push events to your systems instead of polling.