API documentation

The BRIEFED API

Connect your safety management, quality, HR or reporting systems to BRIEFED. The API gives your software read access to your organization’s briefs, shift coverage, aircraft, people and bases. Webhooks tell your systems the moment a brief is submitted, a NO-GO is called, an aircraft’s status changes or a shift is missed.

Included for every organization

Your Account Admin creates keys in the Admin Console under API & webhooks. There’s nothing extra to switch on.

Your data only

Each key belongs to one organization and can only ever read that organization’s data. Choose exactly what each key can read, and revoke it at any time.

No patient information

Briefs hold operational data: weather, aircraft, crew names and checklists. BRIEFED never collects patient information, so there’s none in the API.

Quick start

In the Admin Console, open API & webhooks and create a key. Copy it; it’s shown once.
Send it with every request as a bearer token:

curl https://api.briefed.flights/v1/briefs?limit=5 \
  -H "Authorization: Bearer bk_live_…"

Every response is JSON. Times are UTC (ISO 8601); dates are the brief’s own calendar date.

Endpoints

Base address: https://api.briefed.flights/v1

RequestPermissionWhat it returns

GET /company—The company and key you’re using: name, key prefix and permissions.

GET /briefsbriefs:readBriefs, newest first. Filters: since, until (dates), base, tail, pilot_id, weather_call (GO, CAUTION, NO-GO). Paging: limit (up to 200) and cursor.

GET /briefs/{id}briefs:readOne brief. Add ?include=snapshot for everything the pilot saw: weather, NOTAMs, aircraft and checklist.

GET /coveragecoverage:readEvery base’s Day and Night shifts for the last days (1–90, default 7): briefed (within the shift’s first hour), briefed_late, due, missed or upcoming, with coverage %. A brief counts toward a shift only if it was filed during that shift.

GET /aircraftaircraft:readEach aircraft’s current status (GREEN, YELLOW, RED), notes and ACTT.

GET /peoplepeople:readEveryone in the company with role and base. ?include_inactive=true adds switched-off accounts.

GET /basesbases:readThe company’s bases.

Example: `GET /briefs`

{
  "data": [
    {
      "id": "6f1c0e2a-…",
      "date": "2026-10-22",
      "submitted_at": "2026-10-22T14:31:07.000Z",
      "base": "SA03",
      "airport": "KAPA",
      "shift": "08:00-20:00",
      "tail": "N401SA",
      "pilot": { "id": "…", "name": "Ryan Yamamoto" },
      "weather_call": "GO",
      "aircraft_status": "GREEN",
      "actt": 4211.6,
      "fuel": "2:40",
      "crew": ["Dana Ortiz", "Chris Bell"]
    }
  ],
  "next_cursor": "eyJ0Ijoi…"
}

Paging

Lists return up to limit items and a next_cursor. Pass it back as ?cursor=… for the next page; it’s null on the last page. To pick up only new briefs, store the newest submitted_at you’ve seen, or use the brief.submitted webhook.

Webhooks

Add your https:// address in the Admin Console and choose which events to receive. BRIEFED sends a POST with a JSON body as soon as the event happens, and expects a 2xx answer within 8 seconds.

EventWhen it’s sent

brief.submittedA pilot submits a brief. Data: the brief.

brief.no_goA brief is submitted with a NO-GO weather call. Data: the brief.

aircraft.status_changedAn aircraft’s status changes. Data: tail, status, previous status, notes, who changed it.

shift.missedA shift’s first hour passes with no brief. Data: base, date, day or night, shift times.

pingA test sent from the Admin Console.

What a delivery looks like

POST https://your-system.example.com/briefed
Content-Type: application/json
BRIEFED-Event: shift.missed
BRIEFED-Delivery: evt_8Qm2…
BRIEFED-Signature: t=1792644000,v1=5c9f…

{
  "id": "evt_8Qm2…",
  "type": "shift.missed",
  "created_at": "2026-10-22T15:31:00.000Z",
  "api_version": "2026-10-22",
  "company": "summit",
  "data": {
    "base": "SA03", "base_name": "Centennial", "date": "2026-10-22",
    "shift": "day", "shift_times": "08:00-20:00",
    "started_at": "2026-10-22T14:00:00.000Z", "timezone": "America/Denver"
  }
}

Check the signature

Every webhook has its own signing secret (whsec_…), shown in the Admin Console. Recompute the signature from the raw body and reject anything that doesn’t match or is more than 5 minutes old:

import crypto from 'node:crypto';

// rawBody: the request body exactly as received (a string), header: the BRIEFED-Signature header.
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;   // older than 5 minutes
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ''));
}

Deliveries

Each event is sent once. The Admin Console shows the last 25 deliveries for each webhook with your server’s answer, and a webhook is switched off after 50 failed deliveries in a row. If your system was down, catch up with GET /briefs?since=… or GET /coverage.

Single sign-on (OpenID Connect)

People can sign in to BRIEFED with your organization’s identity provider: Okta, Microsoft Entra ID, Google Workspace, OneLogin, JumpCloud or any provider that supports OpenID Connect.

Set up

In your identity provider, create an OpenID Connect web application for BRIEFED. Use the sign-in redirect URI https://api.briefed.flights/sso/callback and the scopes openid email profile, and assign the people who use BRIEFED.
In the BRIEFED Admin Console, open Integrations & SSO → Single sign-on and enter the application’s issuer (for example https://yourcompany.okta.com or https://login.microsoftonline.com/<tenant id>/v2.0), client ID and client secret.
Choose Test sign-in. Once it works, switch SSO on. Your sign-in page then shows a button for it.

How it works

BRIEFED uses the authorization code flow with PKCE and checks every ID token’s signature, issuer, audience, expiry and nonce.
People are matched to their BRIEFED account by email, so make sure each person’s email is on file (HR sync keeps it current).
Require SSO turns off password sign-in for everyone except the Account Admin, who keeps a password as a way back in if your identity provider is unavailable.
Optionally, BRIEFED can create an account the first time someone signs in, with the role you choose for new people.
Your client secret is stored encrypted, and is never shown again after you save it.

HR sync (SCIM 2.0)

BRIEFED accepts SCIM 2.0, the standard identity providers use to add, update and switch off people automatically. Connect it once, and people appear in BRIEFED when they’re hired and lose access the moment they leave.

Set up

In the Admin Console, open API & webhooks → HR sync (SCIM), choose the role new people should get, and create a SCIM token.
In your identity provider’s SCIM (or “automatic provisioning”) settings, enter the base address https://api.briefed.flights/scim/v2 and the token as a bearer token (HTTP header authorization).
Turn on creating, updating and deactivating users, and assign the people or groups who should have BRIEFED.

What syncs

From your systemIn BRIEFED

name.givenName, name.familyNameFirst and last name

emails (primary or work)Email

userNameMatched to an existing person by email or username; for new people, the BRIEFED username is built from it

active, or deleting the userSwitched on or off. Switching off ends every sign-in at once; briefs and history are kept

password (optional)Sets their BRIEFED password if your provider sends one

Roles, bases and managers stay under your administrators’ control in Users & Roles; new people get the role you chose. The Account Admin can’t be changed through SCIM. With single sign-on switched on, synced people simply sign in with your identity provider; without it, your provider can send a password, or an administrator sets one in Users & Roles.

Supported: /Users (list, filter on userName, externalId or emails.value, create, replace, patch, delete), /ServiceProviderConfig, /ResourceTypes and /Schemas. Groups aren’t used.

Errors and limits

Errors use normal HTTP status codes with a JSON body:

{ "error": { "code": "forbidden", "message": "This key does not have the people:read permission." } }

401 unauthorized: missing, wrong or revoked key
403 forbidden: the key doesn’t have that permission, or the organization’s account is switched off
404 not_found: no such endpoint or record
400 bad_request: a filter is malformed
429 rate_limited / daily_limit: slow down (see Retry-After)

Each key can make 120 requests a minute and 20,000 a day. Need more? Tell us what you’re building.

Versions and changes

This is version 1, and every response carries a BRIEFED-API-Version header. New fields and endpoints are added without notice, so ignore fields you don’t recognize. Anything that would break an existing integration goes into a new version (/v2), and /v1 keeps working alongside it. Changes are announced on What’s new.

Test against demo data

Building an integration before you go live? We can issue a key for our fictional demo organization, Summit Air Medical: real-shaped briefs, bases, aircraft and coverage that update every shift, and no real people’s data. Ask us for a test key.

API documentation

The BRIEFED API

Included for every organization

Your data only

No patient information

Quick start

Endpoints

Example: GET /briefs

Paging

Webhooks

What a delivery looks like

Check the signature

Deliveries

Single sign-on (OpenID Connect)

Set up

How it works

HR sync (SCIM 2.0)

Set up

What syncs

Errors and limits

Versions and changes

Test against demo data

Example: `GET /briefs`