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.

Machine-readable description

Everything on this page and the next is also published as an OpenAPI document, so you can generate a client, load the API into an explorer, or hand it to an AI agent as a tool list.

https://firefight.app/openapi.json
https://firefight.app/openapi.yaml

Every operation in it carries a unique ID, a description, typed parameters, and a response schema. The permission an operation checks is on the operation itself as x-firefight-permission, so you can tell before calling it which grant a service key needs.

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 writes only what your own role lets you change. Use it for your own scripts and agent sessions.

A personal token carries your own authority and nothing more, so a member’s token reads without writing, and an admin’s token can also change workspace configuration. For headless automation, mint a service key with exactly the permissions it needs rather than lending it yours.

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. The one exception is sending an alert in, which authenticates with the alert source’s own token rather than an API key.

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	Read, declare and update incidents, read a timeline and dismiss a note, assign incident roles, and take part: raise and pick up work, claim a runbook step, escalate, invite, link, and give a shoutout
severities	read, create, update, delete	List your severity levels, and manage them
statuses	read, create, update, delete	List your incident statuses, and manage them
incident_types	read, create, update, delete	List your incident types, and manage them
custom_fields	read, create, update	List your custom field definitions, and create or change one
forms	read, update	Read a lifecycle form, and change which fields it asks for
catalog	read, create, update, delete	Read catalog types, and manage catalog entries
runbooks	read, create, update	List and fetch runbooks, and create or change one
alerts	read, create, update, delete	Search ingested alerts, and manage alert sources
policies	read, create, update, delete	Dry-run alert routing, and manage routing rules
approvals	read, update	List approval requests, and approve or deny one
permissions	admins only	Abilities, principals, permission sets, grants, approval rules and the activity log. Cannot be granted to a key, so use a personal token
incident_roles	read, create, update, delete	List your incident roles, and manage them
webhooks	read, create, update, delete	List outbound webhooks, and manage them
api_keys	admins only	Service keys. Cannot be granted to a key, so use a personal token

Almost every pair has a REST endpoint behind it. Creating and changing runbooks, and managing alert routing rules, are the two exceptions, and both are MCP tools instead. Everything else on this table is reachable over REST, over MCP, and on the dashboard. The same resources are what you grant a person under Permissions.

Which surface a request came through makes no difference to what it is allowed to do, because the permission is checked the same way in all three. A key that can change severities on the dashboard can change them over the API and over MCP, and one that cannot change them anywhere cannot change them here. See Configuring your workspace.

custom_fields and forms are deliberately separate. custom_fields covers what a field is, such as adding an Affected region dropdown. forms covers which fields responders are asked for and when, so a key that lets an agent define a field does not also let it make Name required on every declaration. See Incident forms.

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.