Make your first InBrief request

Three APIs, three jobs. Pick the one you need, then make the smallest request that proves it works.

Choose the surface

Facts before code

API base URL

https://inbrief.example/api/v1 (example host; replace it with your InBrief product host)

Authentication

Authorization: Bearer <key> on write APIs

Content type

application/json

Key isolation

Every key belongs to one status page and one scope.

Traffic limits

The Incident API limits requests per key. The Event API uses a fixed batch ceiling and expects buffered delivery.

Machine-readable reference

The OpenAPI 3.1 document lists the implemented routes, authentication requirements, responses and contract-tested examples.

For the prose around them, /llms.txt indexes every page in both portals and /llms-full.txt is all of them as one Markdown document — what to point an assistant at instead of asking it to crawl the HTML.

Run a public request

This endpoint is the safest connection test because it does not need a secret:

curl https://status.example.com/api/public/acme/summary

const response = await fetch('https://status.example.com/api/public/acme/summary');
if (!response.ok) throw new Error(`InBrief responded ${response.status}`);
const summary = await response.json();

A successful response is 200 JSON with a page slug, last-check time and service list. The hostname and slug must belong to the same page.

Run an authenticated request

Create a scoped key in Dashboard → Settings → API keys. It is displayed once; store it in your secret manager. Send it only from a server, a CI job or a worker you control, never from browser JavaScript. The playground on these pages keeps it in memory for one manual request and nowhere else.

curl -X POST https://inbrief.example/api/v1/incidents \
  -H "Authorization: Bearer ibk_live_<your key>" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Checkout is degraded",
  "summary": "We are investigating elevated payment errors.",
  "monitorSlugs": [
    "checkout"
  ],
  "startedAt": "2026-08-27T14:00:00Z"
}'

const response = await fetch('https://inbrief.example/api/v1/incidents', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.INBRIEF_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "title": "Checkout is degraded",
    "summary": "We are investigating elevated payment errors.",
    "monitorSlugs": [
      "checkout"
    ],
    "startedAt": "2026-08-27T14:00:00Z"
  }),
});
if (!response.ok) throw new Error(`InBrief responded ${response.status}`);
const incident = await response.json();

A successful create returns 201 with the incident id. Keep that id: updates and resolution use it.

Handle errors explicitly

For example, a missing, unknown or revoked key returns 401:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error":"Invalid or revoked API key."}

A 403 usually means the key has the wrong scope or the account does not have the required capability. A 429 means the key exceeded its rate window; wait and retry with exponential backoff.

Make retries safe

The Incident API does not currently accept a client Idempotency-Key header. Do not blindly retry a timed-out create: persist your own operation id and reconcile against the incident response or public ledger before creating another record. Webhook deliveries carry their own unique delivery id; receivers should deduplicate on that id.

Continue