Flyte API

Point an AI agent at live flight inventory. Plain language in, real fares out, over REST or MCP.

Search only. There is no booking API.

An agent using Flyte can find flights and read their prices. It cannot reserve, pay for, or ticket anything, and there is no endpoint or tool that does. This is not a gap we are about to fill on a timeline you can plan around, so please do not design a booking flow against it. Build search, and hand the traveller off to flyteai.io to complete a booking.

Build it with your coding agent

Each prompt below is self-contained: base URL, auth, the exact endpoint or tool, response shape, errors, limits and what done looks like. Copy one and hand it to your coding agent.

They all assume a key in a FLYTE_API_KEY environment variable. No key yet? The agent can build against mocks while you request one.

Add Flyte to your MCP client

Your assistant gets a search_flights tool, configured and tested with one real call.

Connect this project's MCP client to Flyte's flight search MCP server, so the assistant can search live flights as a tool call.

Facts about the Flyte API (all true today; do not assume anything beyond them):
- Base URL: https://api.flyteai.io. HTTPS only.
- Flyte is SEARCH ONLY. There is no booking, payment or ticketing endpoint or tool. Do not build or stub one. To book, the traveller goes to https://www.flyteai.io.
- API keys look like flyte_sk_... and are issued after approval at https://www.flyteai.io/request-access. The key is shown once. Read it from an environment variable named FLYTE_API_KEY. Never hard-code it, commit it, log it, or send it to a browser.
- A search is a live lookup and takes 30 to 120 seconds. Use a client timeout of at least 150 seconds.
- Adult passengers only. Fares move: never cache a result and show it later as a live price.
- Full reference: https://www.flyteai.io/api-docs

The MCP server:
- URL: https://api.flyteai.io/mcp (remote HTTP server, JSON-RPC 2.0 over POST, protocol revision 2025-06-18). It answers each POST with plain JSON, not an event stream, and issues no session id.
- Auth: header "Authorization: Bearer <FLYTE_API_KEY>". This header is required; x-api-key alone returns 401 here.
- Methods: initialize, tools/list, tools/call. Capabilities: tools only (no resources, no prompts).
- Exactly one tool, search_flights:
  - query (string, required): the trip in plain language, e.g. "ORD to JFK on December 15th" or "cheapest flight to Miami next weekend". City names and relative dates work.
  - conversation_id (string, optional): reuse the same id to refine a search ("make it business class"). If omitted, every call from the key shares one conversation, so pass a unique id per session, prefixed with something of your own.
- Result: { "content": [{ "type": "text", "text": "..." }], "isError": false }. The result is human-readable text, not structured fields.
- A failed search comes back as a normal result with "isError": true and an explanation in the text. Protocol mistakes come back inside HTTP 200 as JSON-RPC errors: -32700 bad JSON, -32600 jsonrpc is not "2.0", -32601 unknown method, -32602 unknown tool or missing query.
- HTTP 401 with {"detail": "..."} means the key is missing, invalid, revoked or expired. Do not retry a 401.
- /mcp is not rate limited today, but every call is a live search. Never call it in a loop or retry automatically more than once.

Do this:
1. Find the MCP config this project or client uses and add a remote HTTP server named "flyte" with the URL and the Authorization header above. The key must come from the FLYTE_API_KEY environment variable, not be pasted into a committed file. If the config format cannot read environment variables, put it in a local, gitignored config and say so.
2. Add one line to the assistant's instructions: "Flyte's search_flights only searches. Do not ask the user for passenger details, passport data or payment. To book, send them to https://www.flyteai.io."
3. Verify from a shell, with FLYTE_API_KEY exported:
   curl -s -X POST https://api.flyteai.io/mcp \
     -H "Authorization: Bearer $FLYTE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   It must list search_flights. Then run one tools/call:
   -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_flights","arguments":{"query":"ORD to JFK next Friday","conversation_id":"myapp-test-1"}}}'
   Allow up to 150 seconds.

Done when: the client lists search_flights, one real search returns isError false with fares in the text, the key lives only in the environment or a gitignored file, and nothing in the change offers to book or pay. If you do not have a key yet, stop after step 2 and tell me to request one at https://www.flyteai.io/request-access.

Give your agent a flight search tool

A typed REST client and tool definition that return structured fares, with tests.

Add a "search_flights" tool to the AI agent in this codebase, backed by Flyte's REST API, returning structured flight data the agent can reason about.

Facts about the Flyte API (all true today; do not assume anything beyond them):
- Base URL: https://api.flyteai.io. HTTPS only.
- Flyte is SEARCH ONLY. There is no booking, payment or ticketing endpoint or tool. Do not build or stub one. To book, the traveller goes to https://www.flyteai.io.
- API keys look like flyte_sk_... and are issued after approval at https://www.flyteai.io/request-access. The key is shown once. Read it from an environment variable named FLYTE_API_KEY. Never hard-code it, commit it, log it, or send it to a browser.
- A search is a live lookup and takes 30 to 120 seconds. Use a client timeout of at least 150 seconds.
- Adult passengers only. Fares move: never cache a result and show it later as a live price.
- Full reference: https://www.flyteai.io/api-docs

The endpoint:
- POST https://api.flyteai.io/api/process
- Headers: "x-api-key: <FLYTE_API_KEY>", "Content-Type: application/json".
- Body: { "message": string (required, the trip in plain language), "conversation_id": string (send one), "sender_id": string (your app's name) }.
- conversation_id keeps multi-turn context: reuse it to refine ("make it business class"), use a new one to start over. Ids are global, not per key, so prefix them with your app name plus a random part, e.g. "myapp-<uuid>". One id per end-user session.
- Response 200: { "response": string, "slot_summary": string, "status": "success", "metadata": object | null }.
  - response is prose for a human. Its wording changes often; never parse it.
  - metadata is null on turns with no flight, such as a clarifying question. In that case return the response text to the agent so it can ask the user.
  - metadata.flightOffer, when present, is the flight as data:
    { legs: [{ from, to, departAt, arriveAt, stops, via, durationMinutes, segments: [{ from, to, departAt, arriveAt, carrier, carrierName, flightNumber, cabin, durationMinutes }] }],
      tripType, validatingCarrier, validatingCarrierName,
      price: { total, currency, baseFare, taxes }, fareType, refundable,
      baggage: { checked, carryOn }, resultsCount }
    baggage values are often null. Treat every field as possibly missing and validate before use.
  - If metadata.content_type is "payment_request", do not act on it. Tell the user booking happens at https://www.flyteai.io.
- Errors: 401 {"detail": ...} bad or missing key (do not retry). 403 the conversation_id belongs to someone else (start a new id). 422 body failed validation. 429 rate limited. 500 the search failed.
- Rate limit: 30 requests per minute per IP address (not per key) on /api/process. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; read them.
- Retries: on 429 or any 5xx, retry at most once after a backoff (use X-RateLimit-Reset when present), then give up with a clear error. Never retry 401, 403 or 422. Never loop.

Build:
1. A small typed client in the project's language: searchFlights({ query, conversationId }) -> { offer | null, text, slotSummary }, with a 150 second timeout and the error handling above.
2. A tool definition the agent can call: name "search_flights", input { query: string, conversation_id?: string }, output a compact JSON summary of the offer (route, times, stops, carrier, flight numbers, total price and currency, refundable) or the clarifying text.
3. A tool description that says it searches only and cannot book.
4. Tests that mock the HTTP layer only (not the client under test): a flight result, a null-metadata clarifying turn, 401, 429 then success, and a timeout.

Done when: the tests pass, the agent can call the tool and answer "what's the cheapest flight from Chicago to New York next Friday" from the structured offer, the key comes from FLYTE_API_KEY, and nothing offers to book or pay. If you do not have a key yet, build and test against mocks and tell me to request one at https://www.flyteai.io/request-access.

Put flight search on your website

A server route plus a search box that streams progress and shows a live fare card.

Build a minimal "search flights" widget for this website: a text box where a visitor types a trip in plain language and sees a live fare from Flyte, with progress while it searches.

Facts about the Flyte API (all true today; do not assume anything beyond them):
- Base URL: https://api.flyteai.io. HTTPS only.
- Flyte is SEARCH ONLY. There is no booking, payment or ticketing endpoint or tool. Do not build or stub one. To book, the traveller goes to https://www.flyteai.io.
- API keys look like flyte_sk_... and are issued after approval at https://www.flyteai.io/request-access. The key is shown once. Read it from an environment variable named FLYTE_API_KEY. Never hard-code it, commit it, log it, or send it to a browser.
- A search is a live lookup and takes 30 to 120 seconds. Use a client timeout of at least 150 seconds.
- Adult passengers only. Fares move: never cache a result and show it later as a live price.
- Full reference: https://www.flyteai.io/api-docs

Architecture rule: the browser must never hold the key, and Flyte's API does not allow cross-origin browser calls from other sites. So the widget calls a route on THIS app's server, and that route calls Flyte with the key from FLYTE_API_KEY.

The upstream endpoint (call it from your server only):
- POST https://api.flyteai.io/api/process/stream
- Headers: "x-api-key: <FLYTE_API_KEY>", "Content-Type: application/json".
- Body: { "message": string (required), "conversation_id": string, "sender_id": string }. Generate conversation_id on the server per visitor session as "<yoursite>-<uuid>"; ids are global, so the prefix matters. Reuse it so a visitor can refine ("make it nonstop").
- The response is newline-delimited JSON, one object per line:
  {"type":"stage","stage":"searching","origin":"ORD","destination":"JFK"}
  {"type":"ping"}                       (every 15 seconds of silence; ignore)
  {"type":"stage","stage":"found","count":8}
  {"type":"result","slot_summary":"...","response":"...","metadata":{...}}
  or a final {"type":"error","detail":"..."}.
  Exactly one result or error line ends the stream. Ignore unknown types and stage names you do not recognise.
- metadata is null when Flyte asks a clarifying question; then show the response text. When metadata.flightOffer exists, render from it, not from the prose:
  legs[] (from, to, departAt, arriveAt, stops, durationMinutes, segments[] with carrierName and flightNumber), price { total, currency }, refundable, resultsCount. Treat every field as possibly missing; baggage is usually null, so do not show it.
  If metadata.content_type is "payment_request", do not render any payment UI.
- Errors before the stream opens: 401 bad key, 403 conversation id belongs to someone else (mint a new one), 422 bad body, 429 rate limited, 5xx failure. Rate limit is 30 requests per minute per IP, and because your server makes the calls, all your visitors share your server's budget. Add your own per-visitor limit (for example 5 searches per minute) and debounce submits. Retry at most once on 429 or 5xx, never in a loop.

Build:
1. A server route (for example POST /api/flight-search) that validates the input (non-empty, max 300 characters), forwards to the stream endpoint with a 150 second timeout, and streams the NDJSON lines back to the browser unchanged except that it never forwards headers or the key.
2. A client component: input + submit, a status line driven by stage events ("Searching ORD to JFK...", "Found 8 flights"), then a result card with route, departure and arrival times, stops, carrier and flight number, and total price with currency. A "Book on Flyte" link to https://www.flyteai.io. A clear error state and a disabled button while a search runs.
3. Accessible: labelled input, status updates in an aria-live="polite" region, keyboard usable, works at 390px wide and in light and dark mode.
4. Copy under the card: "Live fare, not held. Prices can change."

Done when: a real search shows stage updates and then a fare card, the key never appears in browser network traffic or bundles, refreshing mid-search does not crash the server route, a clarifying question renders as text, errors render a readable message, and the widget offers no payment. If you do not have a key yet, build it against a mocked stream and tell me to request one at https://www.flyteai.io/request-access.

Getting a key

Keys are issued on request, not self-serve. Ask for one at /request-access. Tell us what you are building; we would rather know.

A key looks like flyte_sk_.... The prefix is there so that if one ever leaks into a repository or a log, whoever finds it can tell what it is.

The key is shown once and never again. We store only a hash, so we could not show it to you a second time even if you asked. Copy it when you get it. If you lose it, revoke it and take another.

Ten keys per account. Use a separate key per environment so you can revoke one without breaking the others. Once you are signed in you can list and revoke your own keys by their last four characters; revocation takes effect within a minute.

Authenticating

Send the key in an x-api-key header. HTTPS only; plain HTTP is redirected.

curl https://api.flyteai.io/api/environment \
  -H "x-api-key: flyte_sk_your_key_here"

Authorization: ApiKey flyte_sk_... works too, if your HTTP client insists on putting credentials there.

Prefer x-api-key on REST.

Authorization: Bearer flyte_sk_... is also accepted, but signed-in user sessions use the same header, so x-api-key is the clearer choice. The MCP endpoint is different; see below.

GET /api/health is the only endpoint that answers without a credential.

MCP server

Flyte speaks MCP, so an AI assistant can search flights as a tool call. JSON-RPC 2.0 over HTTP POST, protocol revision 2025-06-18.

MCP needs the key as a bearer token.

Send Authorization: Bearer flyte_sk_..., the one header most MCP clients can send. x-api-key alone returns 401 here. The config below sends both, which also works.

{
  "mcpServers": {
    "flyte": {
      "url": "https://api.flyteai.io/mcp",
      "headers": {
        "x-api-key": "flyte_sk_your_key_here",
        "Authorization": "Bearer flyte_sk_your_key_here"
      }
    }
  }
}

The server implements initialize, tools/list and tools/call, and advertises tools only: no resources, no prompts. There is exactly one tool.

{
  "name": "search_flights",
  "description": "Search live flight inventory using plain language...",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The travel request in plain language, e.g. 'ORD to JFK on December 15th'."
      },
      "conversation_id": {
        "type": "string",
        "description": "Optional. Reuse the same id across calls to refine a search."
      }
    },
    "required": ["query"]
  }
}

A call, and what comes back:

curl -X POST https://api.flyteai.io/mcp \
  -H "x-api-key: flyte_sk_your_key_here" \
  -H "Authorization: Bearer flyte_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_flights",
      "arguments": {
        "query": "ORD to JFK on December 15th",
        "conversation_id": "my-agent-session-1"
      }
    }
  }'
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Flight Found!\n\nOUTBOUND - Tue, Dec 15, 2026\nORD to JFK\nDelta Air Lines DL 5035\n1:35 PM ORD - 5:05 PM JFK\n3h 30m - Direct\n\nCabin: Economy (Y class)\nRefundable: No\nBase Fare: USD 108.70\nTaxes & Fees: USD 24.00\nTotal: USD 132.70\n\n8 flights available - Showing best price"
      }
    ],
    "isError": false
  }
}

Two things to plan for. The tool returns text, not structured fields. If your agent needs a decimal price or a carrier code to work with, call the REST endpoint and read metadata.flightOffer instead. And the text may go on to ask for passenger details, because the same assistant powers the chat product on flyteai.io; over MCP there is nothing to send them to. Worth a line in your system prompt telling the model not to collect them.

Omitting conversation_id makes every call from your key share a single conversation. Pass your own id for anything concurrent.

When a search fails you get a normal successful result with isError: true and an explanation in the text, rather than a JSON-RPC error. The call worked; the search did not, and a model can read the difference.

Paying with USDC on Solana

Partner storefronts only, and off unless enabled.

This rail exists for storefronts whose travellers hold USDC on Solana. It is switched off by default. When it is off, payment requests offer Base only and the endpoint below returns 404.

When a conversation reaches payment, the response metadata has content_type: "payment_request". With the rail on it also carries paymentRails: ["base", "solana"] and a solana block. The amount is fixed by the server when the request opens. Send exactly amountAtomic of mint to escrowTokenAccount, signed by the traveller's own wallet.

"solana": {
  "network": "solana",
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "escrowAddress": "<escrow owner>",
  "escrowTokenAccount": "<escrow USDC token account>",
  "amount": "412.60",
  "amountAtomic": 412600000,
  "decimals": 6,
  "claimEndpoint": "/api/payment-success/solana/start"
}

Once the transfer is sent, claim it. The traveller must be signed in: send their Flyte session as the bearer token and the identity token from their wallet sign-in in the body. The Solana wallet must be linked to the same account as the wallet that started the conversation.

curl -X POST https://api.flyteai.io/api/payment-success/solana/start \
  -H "x-api-key: flyte_sk_your_key_here" \
  -H "Authorization: Bearer <flyte session>" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "conv-123",
       "signature": "<base58 transaction signature>",
       "payer": "<traveller's Solana address>",
       "identity_token": "<sign-in identity token>"}'

# 202 {"status": "pending", "payment_reference": "sol_..."}

Then poll GET /api/payment-status with conversation_id and tx_hash=<payment_reference> until the status is not pending. Only booked means a ticket. A payment is checked only once the transaction is finalized, which takes around 15 seconds. A wrong token, the wrong recipient or a transfer from another wallet is not a payment. A wrong amount is refunded to the wallet it came from. If the trip was already paid on any rail, the second payment is refunded.

400 malformed signature or address, 401 identity token not valid, 403 wallet not linked to this account or a different Solana wallet is already paying, 409 no payment requested or this signature was already used. Every refusal happens before the signature is claimed, so it can be presented again once fixed.

Rate limits and errors

POST /api/process and POST /api/process/stream allow 30 requests per minute. POST /api/reset-conversation allows 10. Every limited response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; read them rather than guessing.

Limits are counted per IP address, not per key. If you are behind a shared egress address you are sharing a budget with whoever else is there.

POST /mcp is not rate limited today. Please do not treat that as an invitation: every call is a live inventory search, and an agent in a retry loop is the thing most likely to get a key revoked.

  • 401: key missing, malformed, revoked or expired. On MCP, also a missing bearer token
  • 422: the request body did not validate
  • 429: rate limited. Back off; do not loop
  • 500: the search failed. Usually transient; retry once, then stop

Over MCP, protocol mistakes come back inside a 200 as JSON-RPC errors: -32700 for unparseable JSON, -32600 if jsonrpc is not "2.0", -32601 for an unknown method, and -32602 for an unknown tool name or a missing query.

Things worth knowing before you build

  • Booking is not available through the API or MCP. Search returns real, live fares; nothing here issues a ticket or moves money.
  • Adult passengers only. Our certification with the inventory provider covers the adult passenger type. Search will not warn you about a trip involving children. The check happens later, in the booking flow on flyteai.io, which refuses it.
  • Fares move. A result is a quote at a moment, not a held price. Re-search rather than caching results, and never show a stored price as though it were still live.
  • Baggage allowances are often absent. The baggage fields come back null more often than not. Do not present them as authoritative.