{ "openapi": "3.1.0", "info": { "title": "Onward Flights", "version": "1.0.0", "description": "Search real flights and buy an onward ticket (proof of onward travel) for one, paid in USDC with the Machine Payments Protocol.", "x-guidance": "To get a traveller proof of onward travel: GET /api/airports?q= for the IATA code of the airport they leave from, GET /api/flights?origin=XXX&destination=YYY&date=YYYY-MM-DD for flights out (pick a different airline from the one they fly in with, to a different country), then POST /api/purchase with ticket_id, first_name and last_name. It returns 402 with an MPP challenge: pay the USDC on Base (or Ethereum, Optimism, Polygon) and repeat with the transaction hash. You get back the ticket url and pdf. Full guide: https://onward.flights/llms.txt", "contact": { "email": "support@onward.flights", "url": "https://onward.flights/agents" } }, "servers": [ { "url": "https://onward.flights" } ], "x-service-info": { "categories": [ "travel" ], "docs": { "homepage": "https://onward.flights/agents", "llms": "https://onward.flights/llms.txt", "apiReference": "https://onward.flights/llms.txt" } }, "paths": { "/api/airports": { "get": { "summary": "Find airport codes by city, airport or country name", "security": [], "parameters": [ { "name": "q", "required": true, "schema": { "type": "string" }, "description": "e.g. \"Bangkok\"", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "airports": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "city": { "type": "string" }, "airport": { "type": [ "string", "null" ] }, "country": { "type": "string" } } } } } } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/flights": { "get": { "summary": "Search one-way flights to use as an onward ticket", "security": [], "parameters": [ { "name": "origin", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "description": "IATA code of the airport leaving the country", "in": "query" }, { "name": "destination", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z]{3}$" }, "description": "IATA code of where the onward flight goes", "in": "query" }, { "name": "date", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Departure date within 9 months, defaults to 14 days from now", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string" }, "flights": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Pass as ticket_id to buy it" }, "title": { "type": "string" }, "from": { "type": "object", "properties": { "code": { "type": "string" }, "city": { "type": "string" }, "airport": { "type": [ "string", "null" ] }, "country": { "type": "string" } } }, "to": { "type": "object", "properties": { "code": { "type": "string" }, "city": { "type": "string" }, "airport": { "type": [ "string", "null" ] }, "country": { "type": "string" } } }, "departs_local": { "type": "string" }, "departs_utc": { "type": "string" }, "duration": { "type": "string" }, "stops": { "type": "integer" }, "airlines": { "type": "array", "items": { "type": "string" } }, "price_usd": { "type": "integer" }, "preview_url": { "type": "string", "format": "uri" } } } } } } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/tickets/{id}": { "get": { "summary": "One flight, its price and how to pay", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Flight id from /api/flights" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Pass as ticket_id to buy it" }, "title": { "type": "string" }, "from": { "type": "object", "properties": { "code": { "type": "string" }, "city": { "type": "string" }, "airport": { "type": [ "string", "null" ] }, "country": { "type": "string" } } }, "to": { "type": "object", "properties": { "code": { "type": "string" }, "city": { "type": "string" }, "airport": { "type": [ "string", "null" ] }, "country": { "type": "string" } } }, "departs_local": { "type": "string" }, "departs_utc": { "type": "string" }, "duration": { "type": "string" }, "stops": { "type": "integer" }, "airlines": { "type": "array", "items": { "type": "string" } }, "price_usd": { "type": "integer" }, "preview_url": { "type": "string", "format": "uri" } } } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/api/purchase": { "post": { "summary": "Buy an onward ticket for a flight, paid in USDC (5 USDC, 10 departing some countries)", "description": "Without payment this returns 402 with a WWW-Authenticate: Payment challenge per chain (method \"evm\", credential type \"hash\"). Send the USDC, wait for it to be mined, then repeat the request with Authorization: Payment whose payload is {\"type\": \"hash\", \"hash\": \"0x…\"}, or with tx_hash and chain in the body.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ticket_id", "first_name", "last_name" ], "properties": { "ticket_id": { "type": "string", "description": "Flight id from /api/flights" }, "first_name": { "type": "string", "description": "Passenger's first name, as on their passport" }, "last_name": { "type": "string", "description": "Passenger's last name, as on their passport" }, "email": { "type": "string", "format": "email", "description": "Optional, also emails the ticket" }, "tx_hash": { "type": "string", "description": "USDC transfer that paid, instead of an MPP credential" }, "chain": { "type": "string", "enum": [ "base", "ethereum", "optimism", "polygon" ], "default": "base" } } } } } }, "responses": { "200": { "description": "The ticket, with a Payment-Receipt header", "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Unscrambled ticket page" }, "pdf": { "type": "string", "format": "uri", "description": "Ticket as a PDF" }, "emailed_to": { "type": "string" } } }, "receipt": { "type": "object" } } } } } }, "402": { "description": "Payment Required" }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } }, "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "5.000000" }, "protocols": [ { "mpp": { "method": "evm", "intent": "charge", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" } }, { "mpp": { "method": "evm", "intent": "charge", "currency": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" } }, { "mpp": { "method": "evm", "intent": "charge", "currency": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85" } }, { "mpp": { "method": "evm", "intent": "charge", "currency": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359" } } ], "offers": [ { "intent": "charge", "method": "evm", "amount": null, "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "description": "USDC on Base (chain 8453): 5 USDC, or 10 departing some countries" }, { "intent": "charge", "method": "evm", "amount": null, "currency": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "description": "USDC on Ethereum (chain 1): 5 USDC, or 10 departing some countries" }, { "intent": "charge", "method": "evm", "amount": null, "currency": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85", "description": "USDC on Optimism (chain 10): 5 USDC, or 10 departing some countries" }, { "intent": "charge", "method": "evm", "amount": null, "currency": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", "description": "USDC on Polygon (chain 137): 5 USDC, or 10 departing some countries" } ] } } } } }