> For the complete documentation index, see [llms.txt](https://skymerse.gitbook.io/notamify-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://skymerse.gitbook.io/notamify-api/async-briefings.md). # Async flight 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](/notamify-api/async-briefings/briefings-chips-system.md) 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: ```json { "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: ```json { "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" } ``` #### Python SDK Example ```python import time from datetime import datetime, timedelta from notamify_sdk import ( NotamifyClient, GenerateFlightBriefingRequest, LocationWithType, ) client = NotamifyClient(token="YOUR_API_KEY") request = GenerateFlightBriefingRequest( locations=[ LocationWithType(location="EPWA", type="origin", starts_at=datetime.now() + timedelta(hours=3), ends_at=datetime.now() + timedelta(hours=3)), LocationWithType(location="EGLL", type="destination", starts_at=datetime.now() + timedelta(hours=6), ends_at=datetime.now() + timedelta(hours=8)), ], origin_runway="RWY11", destination_runway="RWY27L", aircraft_type="B738", ) # Step 1: Submit the briefing job job = client.create_briefing(request) print(f"Briefing job created: {job.uuid}") # Step 2: Poll for results while True: status = client.get_briefing_status(job.uuid) if status.status == "completed": print(status.response) break elif status.status == "failed": raise RuntimeError("Briefing failed") time.sleep(2) ``` ## Generate flight briefing > Generate a flight-focused NOTAM briefing asynchronously. Supports both structured flight briefings (with origin/destination/alternate types) and flexible location-based briefings. ```json {"openapi":"3.1.1","info":{"title":"Notamify API V2","version":"0.0.14"},"servers":[{"url":"https://api.notamify.com/api/v2"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"GenerateFlightBriefingRequest":{"properties":{"locations":{"items":{"$ref":"#/components/schemas/LocationWithType"},"type":"array","maxItems":30,"minItems":1,"title":"Locations","description":"List of locations (airports/FIRs) with their types and time windows"},"origin_runway":{"anyOf":[{"type":"string","maxLength":7,"minLength":1},{"type":"null"}],"title":"Origin Runway","description":"The planned origin airport runway (e.g. 33)"},"destination_runway":{"anyOf":[{"type":"string","maxLength":7,"minLength":1},{"type":"null"}],"title":"Destination Runway","description":"The planned destination airport runway (e.g. 18R)"},"destination_procedure":{"anyOf":[{"type":"string","maxLength":15,"minLength":1},{"type":"null"}],"title":"Destination Procedure","description":"The planned destination airport landing procedure (e.g. ILS18R etc.)"},"aircraft_type":{"anyOf":[{"type":"string","maxLength":15,"minLength":1},{"type":"null"}],"title":"Aircraft Type","description":"The type of aircraft (e.g. A320, B737, etc.)"},"aircraft_details":{"anyOf":[{"$ref":"#/components/schemas/AircraftDetails"},{"type":"null"}],"description":"The details of the aircraft"}},"type":"object","required":["locations"],"title":"GenerateFlightBriefingRequest"},"LocationWithType":{"properties":{"location":{"type":"string","maxLength":4,"minLength":1,"title":"Location","description":"The ICAO code of the location (e.g. KLAX for airport, KZNY for FIR)"},"type":{"anyOf":[{"$ref":"#/components/schemas/LocationType"},{"type":"null"}],"description":"The type of location in the flight plan (optional for flexible briefings)"},"starts_at":{"type":"string","format":"date-time","title":"Starts At","description":"The start time of the window (e.g. 2025-01-01T00:00:00Z). Must be in the future."},"ends_at":{"type":"string","format":"date-time","title":"Ends At","description":"The end time of the window (e.g. 2025-01-01T00:00:00Z). Must be in the future."},"always_include_est":{"type":"boolean","title":"Always Include Est","description":"Whether to always include EST times in the window, even if the notam ends_at is expired but notams it not in cancelled.","default":true},"excluded_classifications":{"anyOf":[{"items":{"type":"string","enum":["DOM","FDC","INTL","MIL"]},"type":"array","minItems":1},{"type":"null"}],"title":"Excluded Classifications","description":"Classifications to exclude: DOM, FDC, INTL, MIL. When empty, no classifications are excluded."}},"type":"object","required":["location","starts_at","ends_at"],"title":"LocationWithType","description":"Location (airport or FIR) with optional type and time window."},"LocationType":{"type":"string","enum":["origin","destination","alternate","fir"],"title":"LocationType","description":"Types of locations in a flight plan."},"AircraftDetails":{"properties":{"equipment":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Equipment","description":"List of equipment codes as per ICAO flight plan (e.g., 'S' for standard equipment)."},"surveillance":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Surveillance","description":"List of surveillance equipment codes (e.g., 'SSR' for Secondary Surveillance Radar)."},"adsb":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Adsb","description":"List of ADS-B equipment codes (e.g., 'B1' for ADS-B with dedicated 1090 MHz out capability)."},"adsc":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Adsc","description":"List of ADS-C equipment codes (e.g., 'D1' for ADS-C with FANS 1/A capability)."},"faa_domestic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Faa Domestic","description":"FAA domestic equipment code (e.g., 'A' for RNAV capability)."},"fuel_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fuel Type","description":"Type of fuel used by the aircraft (e.g., 'Jet A1')."},"persons_on_board":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Persons On Board","description":"Number of persons on board the aircraft."},"pbn_levels":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pbn Levels","description":"Performance Based Navigation levels (e.g., 'C2' for RNAV 2)."},"nav_augmentations":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nav Augmentations","description":"Navigation augmentations used (e.g., 'SBAS' for Satellite-Based Augmentation System)."},"other_information":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Other Information","description":"Any other relevant information of the aircraft equipment and configuration."},"cwt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cwt","description":"Category Wake Turbulence (e.g., 'M' for Medium, 'H' for Heavy, 'J' for Super)."},"mtow_kg":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mtow Kg","description":"Maximum Takeoff Weight in kilograms."},"mtow_lb":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mtow Lb","description":"Maximum Takeoff Weight in pounds."},"num_engines":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Num Engines","description":"Number of engines on the aircraft."},"wingspan_m":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Wingspan M","description":"Wingspan in meters (rounded to 1 decimal place)."},"wingspan_ft":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Wingspan Ft","description":"Wingspan in feet (rounded to 1 decimal place)."},"physical_class_engine":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Physical Class Engine","description":"Physical class of engine (e.g., 'Jet', 'Propeller', 'Piston')."}},"type":"object","title":"AircraftDetails"}}},"paths":{"/notams/briefing":{"post":{"summary":"Generate flight briefing","description":"Generate a flight-focused NOTAM briefing asynchronously. Supports both structured flight briefings (with origin/destination/alternate types) and flexible location-based briefings.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateFlightBriefingRequest"}}},"required":true},"responses":{"201":{"description":"Briefing job created successfully","headers":{"Location":{"description":"URL to check the briefing job status","required":false,"deprecated":false,"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"properties":{"uuid":{"type":"string","description":"Unique identifier for the briefing job"},"status_url":{"type":"string","description":"URL to check the briefing job status"}},"type":"object"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}}}},"deprecated":false}}}} ``` ## Get briefing job status > Get the status and result of a briefing job by UUID ```json {"openapi":"3.1.1","info":{"title":"Notamify API V2","version":"0.0.14"},"servers":[{"url":"https://api.notamify.com/api/v2"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"BriefingJobStatus":{"properties":{"uuid":{"type":"string","title":"Uuid","description":"Unique identifier for the briefing job"},"status":{"$ref":"#/components/schemas/BriefingStatus","description":"Current job status"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the job was created"},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"When the job was last updated"},"response":{"anyOf":[{"$ref":"#/components/schemas/GenerateFlightBriefingResponse"},{"type":"null"}],"description":"Generated briefing response if completed"}},"type":"object","required":["uuid","status","created_at","updated_at"],"title":"BriefingJobStatus","description":"Status payload returned by the briefing job status endpoint."},"BriefingStatus":{"type":"string","enum":["pending","processing","completed","failed"],"title":"BriefingStatus","description":"Status of a briefing job."},"GenerateFlightBriefingResponse":{"properties":{"locations":{"items":{"$ref":"#/components/schemas/LocationWithType"},"type":"array","title":"Locations","description":"The locations that are affected by the flight briefing"},"briefing":{"$ref":"#/components/schemas/BriefingResponse","description":"The flight briefing"}},"type":"object","required":["locations","briefing"],"title":"GenerateFlightBriefingResponse"},"LocationWithType":{"properties":{"location":{"type":"string","maxLength":4,"minLength":1,"title":"Location","description":"The ICAO code of the location (e.g. KLAX for airport, KZNY for FIR)"},"type":{"anyOf":[{"$ref":"#/components/schemas/LocationType"},{"type":"null"}],"description":"The type of location in the flight plan (optional for flexible briefings)"},"starts_at":{"type":"string","format":"date-time","title":"Starts At","description":"The start time of the window (e.g. 2025-01-01T00:00:00Z). Must be in the future."},"ends_at":{"type":"string","format":"date-time","title":"Ends At","description":"The end time of the window (e.g. 2025-01-01T00:00:00Z). Must be in the future."},"always_include_est":{"type":"boolean","title":"Always Include Est","description":"Whether to always include EST times in the window, even if the notam ends_at is expired but notams it not in cancelled.","default":true},"excluded_classifications":{"anyOf":[{"items":{"type":"string","enum":["DOM","FDC","INTL","MIL"]},"type":"array","minItems":1},{"type":"null"}],"title":"Excluded Classifications","description":"Classifications to exclude: DOM, FDC, INTL, MIL. When empty, no classifications are excluded."}},"type":"object","required":["location","starts_at","ends_at"],"title":"LocationWithType","description":"Location (airport or FIR) with optional type and time window."},"LocationType":{"type":"string","enum":["origin","destination","alternate","fir"],"title":"LocationType","description":"Types of locations in a flight plan."},"BriefingResponse":{"properties":{"critical_operational_restrictions":{"items":{"$ref":"#/components/schemas/CriticalOperationalRestrictionGroup"},"type":"array","title":"Critical Operational Restrictions","description":"Critical operational restrictions grouped by flight location so the client can render one heading per location."},"text":{"type":"string","title":"Text","description":"The flight briefing text"}},"type":"object","required":["text"],"title":"BriefingResponse"},"CriticalOperationalRestrictionGroup":{"properties":{"location_code":{"type":"string","title":"Location Code","description":"ICAO code of the location this restriction group belongs to."},"location_role":{"anyOf":[{"$ref":"#/components/schemas/LocationType"},{"type":"null"}],"description":"Flight role of the location, used by the client to render labels such as Origin or Destination."},"items":{"items":{"type":"string"},"type":"array","title":"Items","description":"Critical operational restriction items for this location. Items must not repeat the location label."}},"type":"object","required":["location_code"],"title":"CriticalOperationalRestrictionGroup"}}},"paths":{"/notams/briefing/{uuid}":{"get":{"summary":"Get briefing job status","description":"Get the status and result of a briefing job by UUID","parameters":[{"description":"The UUID of the briefing job","required":true,"deprecated":false,"schema":{"type":"string"},"name":"uuid","in":"path","allowEmptyValue":false,"allowReserved":false}],"responses":{"200":{"description":"Briefing completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefingJobStatus"}}}},"202":{"description":"Briefing job still processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefingJobStatus"}}}},"404":{"description":"Briefing job not found","content":{"application/json":{"schema":{"properties":{"error":{"type":"string"}},"type":"object"}}}},"500":{"description":"Briefing job failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefingJobStatus"}}}}},"deprecated":false}}}} ``` ### 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 ```javascript 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'); } ```