RESTMCPJSON

Flight search API,
without provider-shaped data.

Search Google Flights and Booking results through one normalized contract. Use REST from an application or expose the same search as an MCP tool to an AI agent.

BASE URLhttps://flight-mcp.com Live

Getting started

Authentication

Create an API key in the dashboard and send it as a Bearer token. Keys start with fm_ and are displayed only once. Keep them on your server and never embed them in browser or mobile client code.

Recommended headerAuthorization: Bearer $FLIGHT_MCP_API_KEY

You can alternatively use x-api-key. Sending both authentication headers is rejected.

REST API

Search flights

POST/v1/flights/searchAuthenticated

Returns price-sorted, normalized offers from every enabled provider. One-way and round-trip searches use the same endpoint. New to the workflow? Read the flight search API integration guide.

cURLProduction

curl --request POST \
  https://flight-mcp.com/v1/flights/search \
  --header "Authorization: Bearer $FLIGHT_MCP_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "origin": "HND",
    "destination": "SFO",
    "departureDate": "2026-09-18",
    "returnDate": "2026-09-25",
    "adults": 1,
    "cabinClass": "economy",
    "currency": "JPY",
    "locale": "ja-JP",
    "pointOfSaleCountry": "JP",
    "maxResults": 20,
    "cacheTtlSeconds": 300
  }'

Request body

Parameters

The JSON body is strict: unknown fields are rejected. Traveler totals cannot exceed nine, and a return date cannot precede the departure date.

Field	Type	Required / default	Description
`origin`	string	required	Three-letter uppercase IATA airport code.
`destination`	string	required	Three-letter uppercase IATA code; must differ from origin.
`departureDate`	date	required	Outbound date in YYYY-MM-DD format.
`returnDate`	date	optional	Return date. Omit for one-way searches.
`adults`	integer	1	Adult travelers, from 1 to 9.
`children`	integer	0	Child travelers, from 0 to 8.
`infants`	integer	0	Infants, from 0 to 8; cannot exceed adults.
`cabinClass`	enum	economy	economy, premium_economy, business, or first.
`currency`	string	JPY	Uppercase ISO 4217 currency code.
`locale`	string	ja-JP	Language and regional formatting, such as en or ja-JP.
`pointOfSaleCountry`	string	JP	Uppercase ISO 3166-1 alpha-2 sales country.
`maxResults`	integer	20	Number of combined offers to return, from 1 to 100.
`cacheTtlSeconds`	integer	300	Accepted cache age, from 60 to 259,200 seconds (3 days).

200 OK

Response

Prices use minor currency units: 98640 JPY means ¥98,640. Use meta.cached to distinguish a free cache hit from a billable provider fetch.

offers[].itineraries

One itinerary for one-way results; outbound and inbound itineraries for round trips.

meta.quota

The monthly limit, used and remaining billable calls, and the UTC reset time.

cacheExpiresAt

The absolute expiry of the returned cached flight data.

requestId

Include this identifier when contacting support about a request.

JSON responseExample

{
  "requestId": "a6b25f60-9a10-4be6-a222-5e541a5c13e0",
  "query": {
    "origin": "HND",
    "destination": "SFO",
    "departureDate": "2026-09-18",
    "returnDate": "2026-09-25",
    "adults": 1,
    "children": 0,
    "infants": 0,
    "cabinClass": "economy",
    "currency": "JPY",
    "locale": "ja-JP",
    "pointOfSaleCountry": "JP",
    "maxResults": 20,
    "cacheTtlSeconds": 300
  },
  "offers": [
    {
      "id": "offer_7fd62c",
      "price": { "amountMinor": 98640, "currency": "JPY" },
      "cabinClass": "economy",
      "itineraries": [
        {
          "durationMinutes": 545,
          "stops": 0,
          "segments": [
            {
              "origin": "HND",
              "destination": "SFO",
              "departureAt": "2026-09-18T17:45:00+09:00",
              "arrivalAt": "2026-09-18T10:50:00-07:00",
              "marketingCarrier": { "code": "JL", "name": "Japan Airlines" },
              "flightNumber": "JL2",
              "durationMinutes": 545,
              "aircraft": "Boeing 777-300ER"
            }
          ]
      }
    ],
      "fetchedAt": "2026-08-25T00:15:30.000Z"
    }
  ],
  "meta": {
    "cached": false,
    "cacheTtlSeconds": 300,
    "cacheExpiresAt": "2026-08-25T00:20:30.000Z",
    "durationMs": 6910,
    "quota": {
      "limit": 10000,
      "used": 1,
      "remaining": 9999,
      "resetAt": "2026-09-01T00:00:00.000Z"
    }
  }
}

For AI agents

MCP server

Connect a Streamable HTTP MCP client to https://flight-mcp.com/mcp. The server exposes one tool, flight_search, with the same input and structured output as the REST endpoint. See the MCP flight search guide for an agent-oriented walkthrough.

MCP configurationStreamable HTTP

{
  "mcpServers": {
    "flight-search": {
      "url": "https://flight-mcp.com/mcp",
      "headers": {
        "Authorization": "Bearer $FLIGHT_MCP_API_KEY"
      }
    }
  }
}

Tool name: flight_search
Transport: Streamable HTTP
Methods: GET, POST, DELETE
Authentication: Same API key as REST

Usage model

Cache and quota

Cache miss1 billable call

A successful request that fetches new provider data consumes one monthly call.

Cache hit0 billable calls

Equivalent cached searches are returned without consuming the monthly allowance.

cacheTtlSeconds accepts 60 to 259,200 seconds and does not fragment equivalent cache keys.
Authentication failures, invalid requests, provider failures, and internal failures are not billable.
Monthly quotas reset at 00:00 UTC on the first day of each month.
Production burst limits are 120 requests/IP/minute and 60 requests/API key/minute, including cache hits.

Choosing a production default? Compare freshness patterns in the flight API caching guide.

Response header	Meaning
`ratelimit-limit`	Monthly billable-call allowance for the current plan.
`ratelimit-remaining`	Monthly billable calls remaining.
`ratelimit-reset`	Seconds until the UTC monthly reset.
`x-ratelimit-reset`	UTC reset time as Unix epoch seconds.
`x-request-id`	Request identifier also returned in the JSON body.
`retry-after`	Seconds to wait after a quota or burst-rate rejection.

Error model

Errors

Every API error returns JSON with a stable machine-readable code, a safe message, and a request ID. Validation errors also include field-level details.

Error response400

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The flight search request is invalid.",
    "requestId": "a6b25f60-9a10-4be6-a222-5e541a5c13e0",
    "details": [
      { "path": "destination", "message": "destination must differ from origin" }
    ]
  }
}

HTTP	Code	Meaning
400	`INVALID_REQUEST`	Malformed JSON, unsupported fields, or invalid search values.
401	`UNAUTHORIZED`	The API key is missing, malformed, expired, or revoked.
404	`NOT_FOUND`	The requested API route does not exist.
405	`METHOD_NOT_ALLOWED`	The endpoint does not accept the HTTP method.
429	`RATE_LIMITED`	The short-term IP or API-key burst limit was exceeded.
429	`QUOTA_EXCEEDED`	The plan's monthly billable-call allowance was reached.
502	`PROVIDER_UNAVAILABLE`	Upstream flight data is temporarily unavailable.
503	`REDIS_UNAVAILABLE`	Cache or quota enforcement is temporarily unavailable.
503	`SERVICE_UNAVAILABLE`	Authentication or entitlement verification is unavailable.
503	`PROVIDER_DISABLED`	The configured provider is disabled.
504	`PROVIDER_TIMEOUT`	The provider did not respond before the timeout.
500	`INTERNAL_ERROR`	An unexpected server error occurred.

Ready to make a real request?

Create a key and ship your first search.

Open dashboard OpenAPI JSON