API reference

Everything the dashboard does, your scripts can do. Base URL is https://api.incidentflare.com, everything speaks JSON, and every response that fails carries a message written for a human.

Tokens

Create them in Integrations. There are two kinds, and the split is deliberate: a leaked ingest URL can open noise, never read your data.

• Write — full read and write over your workspace. Send it as Authorization: Bearer ift_w_…. Keep it in your CI secret store, not in a repo.
• Ingest — one URL that only opens incidents, for tools that cannot set a header. It can carry a component, so everything arriving on it lands on the right part of your system.

Severity

One scale decides both who gets alerted and what customers read: P1 outage, P2 partial outage, P3 degraded, P4 minor. Which escalation runs comes from your routing table, so the same P1 can page different people depending on the component. Whether customers see it at all is separate — that is visibility.

Incidents

{
  "title": "Checkout is failing",
  "message": "First update customers will see",
  "severity": "P2",
  "component_ids": ["<component id>"]
}

{ "status": "identified", "message": "Bad deploy, rolling back" }

{ "dedup_key": "checkout-5xx", "message": "Back to normal" }

{ "status": "resolved", "message": "Rolled back, checkout is fine" }

Components

{ "name": "Checkout", "description": "Payments and cart" }

{ "manual_status": "degraded" }

Monitors

{
  "name": "API health",
  "type": "http",
  "url": "https://api.example.com/health",
  "interval_seconds": 300,
  "component_id": "<component id>",
  "severity": "P2",
  "failure_threshold": 3
}

Letting another tool page you

An ingest URL takes whatever the sender posts and opens an incident from it. Sentry, Grafana, Alertmanager and anything that can call a webhook are understood without configuration; anything else still works, using the payload's title-ish fields.

curl -X POST https://api.incidentflare.com/v1/ingest/ift_i_… \
  -H 'Content-Type: application/json' \
  -d '{"title":"Disk almost full","severity":"P3"}'

Send the same dedup_key twice and the second call joins the open incident rather than opening a second one. Send "status":"resolved" with that key to close it.

Names, not ids

Every call that opens something takes a dedup_key — your own name for the problem. Send it again while the incident is open and you get that incident back rather than a second one, and you can close it with the same key later. Leave it out and the title is used, which is usually what you meant.

This is the difference between a deploy job that has to remember our id and hand it to whatever closes the incident, and two independent jobs that only agree on a string. We return ids too, and you can use them — but nothing requires you to keep one.

A complete example

Open an incident on a component from a deploy script; close it from somewhere else entirely.

# The deploy job opens it. No id to keep.
curl -X POST https://api.incidentflare.com/v1/incidents \
  -H "Authorization: Bearer $IF_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Deploy 1.42 failed","severity":"P2","dedup_key":"deploy-1.42","message":"Rolling back","component_ids":["'"$COMPONENT_ID"'"]}'

# The health check closes it, hours later, knowing only the key.
curl -X POST https://api.incidentflare.com/v1/incidents/resolve \
  -H "Authorization: Bearer $IF_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"dedup_key":"deploy-1.42","message":"Rolled back, all good"}'

Rate limits and errors

Ingest is capped per calling IP rather than per URL, so one noisy sender cannot exhaust another's budget. Over the limit is 429. A 402 means the thing you asked for is on a paid plan, and its body names which one.