Async briefings endpoint

The Flight Briefing API provides an asynchronous endpoint for generating flight-focused NOTAM briefings with intelligent chip-based output formatting. The API supports both structured flight briefings (with origin/destination/alternate roles) and flexible location-based briefings. The endpoint provides briefing with Briefings chips system to clearly indicate which notams are relevant for the flight.

Endpoint Structure

The briefing API uses an asynchronous pattern requiring two steps:

1. POST /api/v2/notams/briefing - Submit briefing request

2. GET /api/v2/notams/briefing/{uuid} - Pull for results

Request Body

The API supports two briefing formats:

Structured Flight Briefing

Traditional flight briefing with specific roles for each location:

{
  "locations": [
    {
      "location": "EPWA",
      "type": "origin",
      "starts_at": "2025-08-11T10:00:00Z",
      "ends_at": "2025-08-11T16:00:00Z"
    },
    {
      "location": "EGLL",
      "type": "destination",
      "starts_at": "2025-08-11T11:30:00Z",
      "ends_at": "2025-08-11T18:00:00Z"
    },
    {
      "location": "EPRZ",
      "type": "alternate",
      "starts_at": "2025-08-11T10:00:00Z",
      "ends_at": "2025-08-11T20:00:00Z"
    }
  ],
  "origin_runway": "RWY11",
  "destination_runway": "RWY27L",
  "destination_procedure": "ILS27L",
  "aircraft_type": "B738"
}

Flexible Location Briefing

Flexible briefing without structured location roles:

{
  "locations": [
    {
      "location": "EPWA",
      "starts_at": "2025-08-11T10:00:00Z",
      "ends_at": "2025-08-11T16:00:00Z"
    },
    {
      "location": "EGLL",
      "starts_at": "2025-08-11T11:30:00Z",
      "ends_at": "2025-08-11T18:00:00Z"
    },
    {
      "location": "KZNY",
      "type": "fir",
      "starts_at": "2025-08-11T10:00:00Z",
      "ends_at": "2025-08-11T20:00:00Z"
    }
  ],
  "aircraft_type": "A320"
}

Generate flight briefing

post

Generate a flight-focused NOTAM briefing asynchronously. Supports both structured flight briefings (with origin/destination/alternate types) and flexible location-based briefings.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

origin_runwayany ofOptional

The planned origin airport runway (e.g. 33)

string · min: 1 · max: 7Optional

or

nullOptional

destination_runwayany ofOptional

The planned destination airport runway (e.g. 18R)

string · min: 1 · max: 7Optional

or

nullOptional

destination_procedureany ofOptional

The planned destination airport landing procedure (e.g. ILS18R etc.)

string · min: 1 · max: 15Optional

or

nullOptional

aircraft_typeany ofOptional

The type of aircraft (e.g. A320, B737, etc.)

string · min: 1 · max: 15Optional

or

nullOptional

aircraft_detailsany ofOptional

The details of the aircraft

or

nullOptional

Responses

201

Briefing job created successfully

application/json

400

Invalid request body

application/json

post

/notams/briefing

HTTPcURLJavaScriptPython

POST /api/v2/notams/briefing HTTP/1.1
Host: api.notamify.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 445

{
  "locations": [
    {
      "location": "EPWA",
      "type": "origin",
      "starts_at": "2025-08-11T10:00:00Z",
      "ends_at": "2025-08-11T16:00:00Z"
    },
    {
      "location": "EGLL",
      "type": "destination",
      "starts_at": "2025-08-11T11:30:00Z",
      "ends_at": "2025-08-11T18:00:00Z"
    },
    {
      "location": "EPRZ",
      "type": "alternate",
      "starts_at": "2025-08-11T10:00:00Z",
      "ends_at": "2025-08-11T20:00:00Z"
    }
  ],
  "origin_runway": "RWY11",
  "destination_runway": "RWY27L",
  "destination_procedure": "ILS27L",
  "aircraft_type": "B738"
}

Structured flight briefingFlexible location briefing

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status_url": "/api/v2/notams/briefing/550e8400-e29b-41d4-a716-446655440000"
}

Get briefing job status

get

Get the status and result of a briefing job by UUID

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

uuidstringRequired

The UUID of the briefing job

Responses

200

Briefing completed successfully

application/json

DTO returned by the status endpoint for a briefing job.

uuidstringRequired

Unique identifier for the briefing job

statusstring · enumRequired

Current job status

Possible values:

created_atstring · date-timeRequired

When the job was created

updated_atstring · date-timeRequired

When the job was last updated

responseany ofOptional

Generated briefing response if completed

or

nullOptional

202

Briefing job still processing

application/json

404

Briefing job not found

application/json

500

Briefing job failed

application/json

get

/notams/briefing/{uuid}

HTTPcURLJavaScriptPython

GET /api/v2/notams/briefing/{uuid} HTTP/1.1
Host: api.notamify.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:05:30Z",
  "response": {
    "locations": [
      {
        "location": "EPWA",
        "type": "origin",
        "starts_at": "2025-08-11T10:00:00Z",
        "ends_at": "2025-08-11T16:00:00Z"
      }
    ],
    "briefing": {
      "highlights": [
        "Runway 11/29 closed at EPWA affecting planned takeoff runway"
      ],
      "text": "## Origin: EPWA\n\n**Runway Operations:**\n- Runway 11/29 closed for maintenance [A1234/25](notam-link)\n\n## Destination: EGLL\n\n**Navigation Aids:**\n- ILS 27L out of service [B5678/25](notam-link)"
    }
  }
}

Best Practices

Polling Strategy

1. Initial Delay: Wait 2-3 seconds before first poll

2. Maximum Polls: Limit to 120 polls (approximately 4 minutes)

3. Error Handling: Implement retry logic for network failures

Example Polling Implementation

async function pollBriefingStatus(uuid) {
  const maxPolls = 120;
  let pollCount = 0;
  let delay = 2000;
  
  while (pollCount < maxPolls) {
    try {
      const response = await fetch(`/api/v2/notams/briefing/${uuid}`, {
        headers: { 'Authorization': 'Bearer your_token_here' }
      });
      
      if (response.status === 200) {
        return await response.json(); // Completed
      } else if (response.status === 202) {
        // Still processing, continue polling
        await new Promise(resolve => setTimeout(resolve, delay));
        pollCount++;
      } else {
        throw new Error(`Briefing failed: ${response.status}`);
      }
    } catch (error) {
      console.error('Polling error:', error);
      throw error;
    }
  }
  
  throw new Error('Briefing timeout - maximum polls reached');
}