Award Travel Finder Airlines API

openapi: 3.2.0
info:
  title: Award Travel Finder API V1 Airlines API
  version: v1
  description: 'API for searching award flight availability and pricing across multiple airlines, plus hotel search (city list and property detail with cash rates and major-chain award pricing). Availability searches that are still running return 202 Accepted with status pending, retry_after, and a Retry-After header (previously 503). A request scoped only to an open-breaker source stays 503, names that source, and includes Retry-After. A multi-airline search returns 200 with partial true and a per-source status list when other sources answered. Optional cached_only=1 is opt-in for every tier: a hit is 200, a miss is 202 pending and enqueues one background search. Per-key rate and concurrency limits return 429 with Retry-After. 202, 429, and 503 do not consume the monthly quota. Each hotel list or detail request counts as one call against the monthly quota.'
  contact:
    name: Award Travel Finder
    url: https://awardtravelfinder.com
servers:
- url: https://awardtravelfinder.com
  description: Production server
- url: http://localhost:3000
  description: Development server
security:
- ApiKeyAuth: []
tags:
- name: Airlines
paths:
  /api/v1/airlines/airports:
    get:
      x-payment-info:
        intent: session
        method: stripe
        amount: 9.99
        currency: USD
        description: Included in a paid Award Travel Finder plan ($9.99/month). Purchase at https://awardtravelfinder.com/pricing
      summary: Get supported airports for all airlines
      tags:
      - Airlines
      description: Retrieves the list of all supported airports for available airlines. Returns airport codes and names organized by airline.
      parameters:
      - name: X-API-Key
        in: header
        required: true
        description: API key for authentication
        schema:
          type: string
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      total_airlines:
                        type: integer
                        example: 1
                      airlines:
                        type: array
                        items:
                          type: object
                          properties:
                            airline:
                              type: string
                              example: Cathay Pacific
                            airline_code:
                              type: string
                              example: CX
                            total_airports:
                              type: integer
                              example: 50
                            airports:
                              type: array
                              items:
                                type: object
                                properties:
                                  code:
                                    type: string
                                    example: HKG
                                  name:
                                    type: string
                                    example: Hong Kong International Airport
                  usage:
                    type: object
                    properties:
                      remaining_calls:
                        type: integer
                        example: 4999
                      monthly_limit:
                        type: integer
                        example: 5000
                      reset_at:
                        type: string
                        format: datetime
                        example: '2025-04-01T00:00:00Z'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: API key required
      operationId: getApiV1AirlinesAirports
      x-operation-id-source: derived
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
      description: 'API key for the REST API and CLI, sent as the X-API-Key header. Autonomous agents can self-register for a free-tier key in one unauthenticated call: POST /api/v1/agent/register. The MCP server at https://mcp.awardtravelfinder.com/mcp does NOT accept this key - it is OAuth 2.1 only (scope mcp:read), with Dynamic Client Registration at POST /oauth/register.'
x-service-info:
  name: Award Travel Finder
  description: 'Award seat availability, award chart pricing and points valuations. Current airline coverage: https://awardtravelfinder.com/coverage.json.'
  categories:
  - travel
  - flight-search
  - loyalty-programs
  documentation: https://awardtravelfinder.com/developers
  pricing_url: https://awardtravelfinder.com/pricing