AwardSecrets Api.php API

openapi: 3.2.0
info:
  title: AwardSecrets Award Availability Api.php API
  version: 1.6.0
  description: 'Queries the AwardSecrets data set: award-travel intelligence, AI-augmented and derived from GDS inventory and lived award-travel experience (not scraped from airline websites). Returns business, first and economy AWARD (points/miles) seat availability. Access is by monthly API membership (Sandbox or Developer, started online at https://awardsecrets.com/api.html#pricing; Enterprise by arrangement), each with a monthly query allowance and no per-query charges.


    IMPORTANT — this is a LITERAL query: each call covers exactly ONE origin airport, ONE destination airport, ONE airline, and ONE date. It does NOT accept lists, ranges, or vague inputs. If the user is flexible (multiple airports, a date range, ''any airline'', ''sometime in August''), resolve to ONE concrete value for each field and make SEPARATE calls — one per combination — then aggregate the results yourself.


    The response contains facts only (carrier, flight number, route, times, cabin, seat count). It does NOT include pricing or mileage cost. Availability is a point-in-time observation, not a reservation: confirm with the airline or loyalty programme before transferring points.


    Compatibility: new response fields may be added at any time; clients should ignore fields they don''t recognise. Existing fields won''t be removed or changed without notice to members. Changelog: 1.1.0 (10 Oct 2026) added observed_at. 1.2.0 (11 Oct 2026) added the redemption pricing endpoint, /points.php. 1.3.0 (11 Oct 2026) added journeys: itinerary on each flight, itineraries per date (with bookable seats), itinerary_count. 1.4.0 (11 Oct 2026) pricing: optional date; round_trip, season, season_miles. 1.4.1 (12 Oct 2026) no field changes: connections where only some segments show 9 are now returned (journeys are judged by their lowest segment); descriptions clarified for operated_by, via, airport_change, legs and price_type. 1.5.0 (18 Oct 2026) documents fields already returned: each reachable_from entry (currency, ratio, points_needed, transfer_time, bonus), with points_needed rounded up to whole transfer blocks; confidence, pricing_model, surcharge_basis, surcharge_confidence and valuation_cpp on each option; valuation_cpp, count_unpriced_dynamic and count_unpriced_no_data on the result; pricing_basis values two_awards, mixed_journey and mixed_per_sum; and the list of programme codes (x-programme-codes on PriceOption.programme). New programmes since 1.4.1: AER_LINGUS_AERCLUB, CHINA_SOUTHERN_SKY_PEARL, EVA_INFINITY, FINNAIR_PLUS, THAI_ROYAL_ORCHID_PLUS, VIETNAM_LOTUSMILES, ETIHAN_GUEST, JAL_MILEAGE_BANK, QATAR_PRIVILEGE_CLUB and VELOCITY cover more partner airlines.'
  contact:
    name: AwardSecrets
    url: https://awardsecrets.com
servers:
- url: https://awardsecrets.com
  description: Production
tags:
- name: Api.php
paths:
  /api.php:
    post:
      operationId: searchAwardAvailability
      summary: Query award seat availability for one route, one airline, one date
      description: Returns available AWARD seats (redeemable with points/miles) for a SINGLE origin, SINGLE destination, SINGLE airline, and SINGLE date. Use the 2-letter IATA airline code (e.g. VS=Virgin Atlantic, CX=Cathay Pacific, QR=Qatar, JL=Japan Airlines, IB=Iberia, NH=ANA, AF=Air France). For flexible searches, call this once per concrete (origin, destination, airline, date) combination. Each query uses one unit of the membership's monthly query allowance; there are no per-query charges.
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Search completed (may or may not have found seats; check the 'found' field). If 'searched' is false, no search was made (see not_searched_reason) and no quota was used.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
      tags:
      - Api.php
components:
  schemas:
    SearchResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    SearchRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true