openapi.yaml

openapi: 3.0.3
info:
  title: Flight Enrichment API
  description: |
    REST API for accessing flight enrichment data extracted from ACARS messages.

    This API provides access to operational flight data including routes, runways,
    SIDs, squawk codes, and passenger counts. Data is keyed by aircraft ICAO hex
    address, callsign, and flight date.

    Data is written to PostgreSQL by `acars_parser live` and
    `acars_parser reparse -enrich`; this API only reads it. "Today" means the
    current UTC date. Path values for `icao_hex` and `callsign` are converted to
    upper case and are not otherwise validated.

    ## Authentication

    Authentication is optional and disabled by default. When the server is
    started with `-auth`, every endpoint (including `/health`) requires an API
    key supplied via the first present of:
    - `X-API-Key` header
    - `Authorization: Bearer <key>` header
    - `api_key` query parameter

    A missing key returns `401`; a key that is not configured returns `403`.

    ## Errors

    Errors raised by the handlers are returned as `{"error": "<message>"}`.
    Requests that match no route receive a plain-text `404` or `405` from the
    router instead.

    ## Rate Limiting

    No rate limiting is enforced.
  version: 1.0.0
  contact:
    name: ACARS Parser

servers:
  - url: http://localhost:8081/api/v1
    description: Local development server

tags:
  - name: Health
    description: Health check endpoints
  - name: Enrichment
    description: Flight enrichment data endpoints

paths:
  /health:
    get:
      tags:
        - Health
      summary: Health check
      description: |
        Returns the health status of the API server. The database is not
        queried. When authentication is enabled, this endpoint also requires an
        API key.
      operationId: getHealth
      responses:
        '200':
          description: Server is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

  /enrichment/{icao_hex}:
    get:
      tags:
        - Enrichment
      summary: Get enrichments by aircraft
      description: |
        Returns all flight enrichments for an aircraft on today's date (UTC),
        ordered by most recently updated first. An aircraft may have multiple
        enrichments if it operated multiple flights. When there are none, the
        response is `404` rather than an empty array.
      operationId: getEnrichmentByAircraft
      parameters:
        - $ref: '#/components/parameters/ICAOHex'
      responses:
        '200':
          description: Enrichment data found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FlightEnrichment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No enrichment data found for the aircraft
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'No enrichment data found for aircraft'
        '500':
          $ref: '#/components/responses/InternalError'

  /enrichment/{icao_hex}/{callsign}:
    get:
      tags:
        - Enrichment
      summary: Get enrichment by aircraft and callsign
      description: |
        Returns the enrichment for a specific flight (aircraft and callsign) on
        today's date (UTC). The callsign is matched on its trailing digits, so
        IATA and ICAO forms of the same flight number return the same record.
      operationId: getEnrichmentByCallsign
      parameters:
        - $ref: '#/components/parameters/ICAOHex'
        - $ref: '#/components/parameters/Callsign'
      responses:
        '200':
          description: Enrichment data found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightEnrichment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /enrichment/{icao_hex}/{callsign}/{date}:
    get:
      tags:
        - Enrichment
      summary: Get enrichment by aircraft, callsign, and date
      description: |
        Returns the enrichment for a specific flight on a specific date. Use
        this for historical lookups. Callsign matching is the same as for
        `getEnrichmentByCallsign`.
      operationId: getEnrichmentByDate
      parameters:
        - $ref: '#/components/parameters/ICAOHex'
        - $ref: '#/components/parameters/Callsign'
        - $ref: '#/components/parameters/FlightDate'
      responses:
        '200':
          description: Enrichment data found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightEnrichment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'

  /enrichment/batch:
    post:
      tags:
        - Enrichment
      summary: Batch lookup enrichments
      description: |
        Look up enrichments for multiple aircraft in a single request.
        Maximum 100 aircraft per request. Returns today's (UTC) data.

        Entries with an empty `icao_hex` are skipped. Aircraft with no data are
        omitted from `results`. A database error for an individual aircraft is
        reported in `errors` and does not fail the request.
      operationId: batchEnrichment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Batch results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          description: |
            The body is not valid JSON, `aircraft` is empty, or `aircraft` has
            more than 100 entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'Maximum 100 aircraft per batch request'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'

components:
  parameters:
    ICAOHex:
      name: icao_hex
      in: path
      required: true
      description: |
        Aircraft ICAO 24-bit address in hexadecimal (e.g., "7C6CA3"). The value
        is converted to upper case; its format is not validated.
      schema:
        type: string
        example: '7C6CA3'

    Callsign:
      name: callsign
      in: path
      required: true
      description: |
        Flight callsign or flight number in IATA or ICAO form (e.g., "QF9",
        "QFA9"). The value is converted to upper case; its format is not
        validated. Leading zeros in the numeric part are not removed, so
        "QFA008" does not match a stored "QFA8".
      schema:
        type: string
        example: 'QFA9'

    FlightDate:
      name: date
      in: path
      required: true
      description: Flight date in YYYY-MM-DD format (UTC).
      schema:
        type: string
        format: date
        example: '2026-01-30'

  schemas:
    HealthResponse:
      type: object
      required:
        - status
        - time
      properties:
        status:
          type: string
          description: Health status
          example: 'ok'
        time:
          type: string
          format: date-time
          description: Current server time (UTC)
          example: '2026-01-30T14:30:00Z'

    FlightEnrichment:
      type: object
      required:
        - icao_hex
        - callsign
        - flight_date
        - last_updated
      properties:
        icao_hex:
          type: string
          description: Aircraft ICAO 24-bit hex address
          example: '7C6CA3'
        callsign:
          type: string
          description: Flight callsign as stored; may be IATA or ICAO form
          example: 'QFA9'
        flight_date:
          type: string
          format: date
          description: Flight date (the date the data was received)
          example: '2026-01-30'
        origin:
          type: string
          description: Origin airport code as reported; may be ICAO or IATA
          example: 'YPPH'
        destination:
          type: string
          description: Destination airport code as reported; may be ICAO or IATA
          example: 'EGLL'
        route:
          type: array
          description: Route waypoints
          items:
            type: string
          example: ['JULIM', 'BEVLY', 'ORRSU', 'LONSU']
        eta:
          type: string
          description: Estimated time of arrival (HH:MM). Currently never populated.
          example: '14:30'
        departure_runway:
          type: string
          description: Departure runway
          example: '03'
        arrival_runway:
          type: string
          description: Arrival runway. Currently never populated.
          example: '27R'
        sid:
          type: string
          description: Standard Instrument Departure procedure
          example: 'JULIM6'
        squawk:
          type: string
          description: Assigned transponder code
          example: '4521'
        pax_count:
          type: integer
          description: Total passenger count; omitted when zero or unknown
          example: 350
        pax_breakdown:
          type: object
          description: Passenger count by cabin class. Currently never populated.
          additionalProperties:
            type: integer
          example:
            J: 14
            W: 56
            Y: 280
        last_updated:
          type: string
          format: date-time
          description: |
            When this enrichment was last updated (RFC 3339). The offset is the
            local time zone of the host running the API, so it may not be `Z`.
          example: '2026-01-30T08:45:00Z'

    BatchRequest:
      type: object
      required:
        - aircraft
      properties:
        aircraft:
          type: array
          description: List of aircraft to look up (max 100)
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/BatchAircraftQuery'

    BatchAircraftQuery:
      type: object
      required:
        - icao_hex
      properties:
        icao_hex:
          type: string
          description: Aircraft ICAO 24-bit hex address; entries with an empty value are skipped
          example: '7C6CA3'
        callsign:
          type: string
          description: Optional callsign; when set, at most one record is returned
          example: 'QFA9'

    BatchResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: object
          description: |
            Enrichments keyed by upper-case ICAO hex. Aircraft with no data are
            omitted.
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/FlightEnrichment'
        errors:
          type: object
          description: |
            Database error text keyed by ICAO hex. Omitted when no lookup
            failed.
          additionalProperties:
            type: string

    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message
          example: 'No enrichment data found'

  responses:
    BadRequest:
      description: Invalid date format
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'Invalid date format (use YYYY-MM-DD)'

    Unauthorized:
      description: Authentication is enabled and no API key was supplied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'API key required'

    Forbidden:
      description: Authentication is enabled and the API key is not valid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'Invalid API key'

    NotFound:
      description: No enrichment data found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'No enrichment data found'

    InternalError:
      description: Database error; the message contains the underlying error text
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key passed in X-API-Key header

    BearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token

    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key passed as query parameter (for testing only)

# Authentication is optional (disabled by default). The empty requirement `{}`
# indicates that requests without a key are accepted when it is disabled.
security:
  - {}
  - ApiKeyHeader: []
  - BearerAuth: []
  - ApiKeyQuery: []