---
title: "Carriers offering upgrades on an airport pair"
method: GET
path: "/api/v1/routes"
tags: ["Partners"]
---

# Carriers offering upgrades on an airport pair

`GET /api/v1/routes`

## Request

- Base URL: `https://www.upgradeagent.ai`
- URL: `https://www.upgradeagent.ai/api/v1/routes`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://www.upgradeagent.ai/api/oauth/authorize`, token URL `https://www.upgradeagent.ai/api/oauth/token`, scopes: `mcp`)
  - HTTP bearer

Route-level discovery (the MCP `search_upgrade_options` tool with a route). Three labelled evidence layers, never blended: operator inventory (when that upstream is enabled on the deployment), observed upgrade ranges on the pair from anonymized eligibility checks, and hub / home-country matches that may serve the route but are explicitly not confirmed and carry no pricing.

## Query parameters

- `origin` string, required: Origin airport IATA code, e.g. YUL.
- `destination` string, required: Destination airport IATA code, e.g. LHR.
- `date` string: Travel date YYYY-MM-DD; scopes the inventory layer only.
- `cabin` 'BUSINESS' | 'FIRST' | 'PREMIUM_ECONOMY'

## Response `200`

Carriers on the route with their evidence basis.

- RouteSearch
  - `route` object, required
    - `origin` string, required
    - `destination` string, required
    - `originLabel` string, required: City (IATA) when the airport is known.
    - `destinationLabel` string, required
    - `haul` 'short' | 'long', nullable, required
    - `date` string, nullable, required: YYYY-MM-DD as requested; scopes the inventory layer only.
    - `cabin` string, nullable, required
    - `slug` string, required: Public page slug, e.g. yul-lhr (/routes/{slug}).
  - `carriers` RouteCarrier[], required: Ordered inventory → observed → network; at most 12.
    - `code` string, required: IATA code.
    - `name` string, required
    - `slug` string, nullable, required
    - `products` object[], required
      - `id` string, required
      - `label` string, required
    - `basis` 'inventory' | 'observed' | 'network', required: inventory = operator schedule confirmed for the date; observed = real upgrade ranges seen on this pair (either direction); network = hub / home-country match — may serve the route, NOT confirmed, no pricing.
    - `observedPricing` RouteObservedPricing[]: Per-cabin observed ranges; present for observed (and inventory-confirmed) carriers.
      - `cabin` string, required: Target cabin, e.g. BUSINESS.
      - `label` string, required
      - `currency` string, required
      - `min` number, required: Lowest minimum bid observed on this pair.
      - `median` number, required: Median suggested starting bid.
      - `max` number, required: Highest maximum bid observed.
      - `sampleSize` integer, required: Anonymized checks behind the figures.
      - `lastObserved` string, nullable, required: ISO timestamp of the latest check for this carrier on this pair.
    - `observedSamples` integer
    - `directions` string[]: Which directions of the pair the observed rows came from.
    - `inventory` object: Present for inventory-confirmed carriers.
      - `eligibleFlights` integer, required
      - `totalFlights` integer, required
      - `date` string, required
    - `hubMatch` 'hub' | 'home_country': Present when the static network table links this carrier to the route.
    - `note` string, required: One honest sentence about what the basis means for this carrier.
    - `upgradePage` string, nullable, required: Agent-ready upgrade page on Upgrade Agent.
    - `partnerPage` string, nullable, required
  - `layers` object, required
    - `inventory` integer, required
    - `observed` integer, required
    - `network` integer, required
    - `inventoryStatus` 'disabled' | 'ok' | 'partial' | 'unreachable' | 'no_candidates', required
    - `truncated` integer, required: Qualifying carriers cut by the cap.
  - `coverageNote` string, required: Plain-language statement of what the result is based on.
  - `note` string, required

## Other responses

- `400`: origin/destination missing or not IATA codes; invalid date or cabin.
- `401`: Missing, invalid, expired, or revoked bearer token. The WWW-Authenticate challenge points at the OAuth protected-resource metadata.
- `429`: Per-caller rate limit exceeded.

---

[API](https://skmtc.dev/upgradeagent/apis/upgrade-agent-rest-api.md) · [All operations](https://skmtc.dev/upgradeagent/apis/upgrade-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/upgradeagent/apis/upgrade-agent-rest-api/revisions/fbed715712c1?raw)