{ "openapi": "3.1.0", "info": { "title": "AirTreks Routing API", "version": "1.0.0", "description": "Multi-stop flight API for AI agents — the REST twin of the AirTreks MCP server (https://mcp.airtreks.com/mcp). Plan, validate, and price complex multi-city and round-the-world (RTW) itineraries: alliance feasibility, carrier recommendations, hub connections, fare product matching, and consultant handoff. Built by AirTreks, multi-stop flight specialists since 1987.", "contact": { "name": "AirTreks partnerships", "email": "partnerships@airtreks.com", "url": "https://airtreks.com" }, "license": { "name": "AGPL-3.0-only", "identifier": "AGPL-3.0-only" } }, "servers": [ { "url": "https://mcp.airtreks.com" } ], "externalDocs": { "description": "AirTreks developer docs", "url": "https://airtreks.com/developers" }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } }, "paths": { "/api/plan_route": { "post": { "operationId": "plan_route", "summary": "Plan a Multi-City Route", "description": "The primary entry point for any multi-city trip. Give it your cities — it automatically evaluates Star Alliance RTW, oneworld RTW, AND custom mixed-carrier builds, then recommends the best approach. Handles direction detection, backtracking analysis, alliance feasibility, surface sectors, and carrier selection. The customer doesn't need to know if their trip is alliance or custom — this tool figures it out.", "tags": [ "routing" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cities": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of IATA city/airport codes (e.g. ['LAX', 'NRT', 'BKK', 'LIS', 'LAX'])" }, "budget": { "description": "Budget tier — affects carrier selection and fare strategy", "type": "string", "enum": [ "budget", "mid", "premium", "business" ] }, "preferences": { "description": "Travel preferences: 'no-lcc', 'lounge-access', 'short-layovers', 'surface-ok'", "type": "array", "items": { "type": "string" } }, "pax": { "description": "Number of passengers", "type": "number" } }, "required": [ "cities" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result — JSON object, shape varies by tool.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid arguments (body lists the failing fields)." }, "429": { "description": "Rate limit exceeded. Free tier: 100 requests/day per IP." } } } }, "/api/trip_idea_create": { "post": { "operationId": "trip_idea_create", "summary": "Create a Trip Idea (Consultant Handoff)", "description": "Create a trip idea in AirTreks APEX system — hands off to a human consultant. Automatically runs plan_route to include full routing analysis, carrier recommendations, and consultant value assessment in the lead. The consultant starts informed, not cold. Use this when the customer is ready to get a real quote.", "tags": [ "booking" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Customer email address (required)" }, "name": { "description": "Customer full name", "type": "string" }, "phone": { "description": "Customer phone number", "type": "string" }, "cities": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of IATA city/airport codes" }, "dates": { "description": "Departure dates for each leg (ISO format, e.g. '2026-09-15')", "type": "array", "items": { "type": "string" } }, "passengers": { "description": "Number of passengers (default 1)", "type": "number" }, "cabin": { "description": "Cabin class preference", "type": "string", "enum": [ "economy", "premium", "business" ] }, "budget": { "description": "Budget tier", "type": "string", "enum": [ "budget", "mid", "premium", "business" ] }, "flexibleDates": { "description": "Are travel dates flexible?", "type": "boolean" }, "preferences": { "description": "Travel preferences: 'no-lcc', 'lounge-access', 'short-layovers', 'surface-ok'", "type": "array", "items": { "type": "string" } }, "notes": { "description": "Additional notes or special requests from the customer", "type": "string" }, "agentContext": { "description": "Summary of what the AI agent learned about this trip (auto-generated routing analysis, customer preferences discussed, etc.)", "type": "string" } }, "required": [ "email", "cities" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result — JSON object, shape varies by tool.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid arguments (body lists the failing fields)." }, "401": { "description": "Missing or invalid X-API-Key." }, "429": { "description": "Rate limit exceeded. Free tier: 100 requests/day per IP." } } } }, "/api/route_validate": { "post": { "operationId": "route_validate", "summary": "Validate a Multi-City Routing", "description": "Validate a multi-city flight routing for feasibility. Checks alliance carrier rules, identifies dead legs, warns about poison carriers, and estimates bookability. Use this before building an itinerary to catch routing problems early.", "tags": [ "routing" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cities": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of IATA city/airport codes (e.g. ['LAX', 'NRT', 'BKK', 'LHR', 'LAX'])" }, "carriers": { "description": "Optional carrier codes for each leg (e.g. ['NH', 'TG', 'BA', 'BA'])", "type": "array", "items": { "type": "string" } }, "alliance": { "description": "Preferred alliance: 'star' or 'oneworld'", "type": "string" } }, "required": [ "cities" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result — JSON object, shape varies by tool.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid arguments (body lists the failing fields)." }, "429": { "description": "Rate limit exceeded. Free tier: 100 requests/day per IP." } } } }, "/api/route_suggest": { "post": { "operationId": "route_suggest", "summary": "Suggest Multi-Stop Routings", "description": "Get suggested multi-stop flight routings based on regions, direction, and alliance preference. Returns up to 3 proven routing templates with bookability ratings. Great for trip planning inspiration.", "tags": [ "routing" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "regions": { "type": "array", "items": { "type": "string" }, "description": "Regions to visit: 'asia', 'europe', 'oceania', 'americas', 'africa', 'middle east', 'south america'" }, "direction": { "description": "Travel direction preference", "type": "string", "enum": [ "eastbound", "westbound", "either" ] }, "alliance": { "description": "Preferred alliance: 'star' or 'oneworld'", "type": "string" }, "maxStops": { "description": "Maximum number of stops (legs). 3-6 recommended for best bookability.", "type": "number" }, "tripType": { "description": "Trip type hint: 'honeymoon', 'backpacker', 'business', 'family', etc.", "type": "string" } }, "required": [ "regions" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result — JSON object, shape varies by tool.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid arguments (body lists the failing fields)." }, "429": { "description": "Rate limit exceeded. Free tier: 100 requests/day per IP." } } } }, "/api/hub_check": { "post": { "operationId": "hub_check", "summary": "Check Airport Hub Connections", "description": "Check the best connection between two airports. Identifies dead legs (routes that fail on alliance fares), suggests hub routing fixes, and shows proven carrier combinations. Essential for transpacific, kangaroo, and intra-Asia routing.", "tags": [ "routing" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string", "description": "Origin IATA airport code (e.g. 'SYD')" }, "to": { "type": "string", "description": "Destination IATA airport code (e.g. 'JFK')" }, "alliance": { "description": "Preferred alliance: 'star' or 'oneworld'", "type": "string" } }, "required": [ "from", "to" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result — JSON object, shape varies by tool.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid arguments (body lists the failing fields)." }, "429": { "description": "Rate limit exceeded. Free tier: 100 requests/day per IP." } } } }, "/api/fare_product_match": { "post": { "operationId": "fare_product_match", "summary": "Match the Right Fare Product", "description": "Recommend the best fare product type for a route — RTW, Circle Pacific, Circle Atlantic, Open Jaw, or Custom Multi-City. Considers stop count, direction, and backtracking to match the right alliance fare structure.", "tags": [ "routing" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cities": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of IATA city/airport codes" }, "isOneDirection": { "description": "Is the route traveling continuously in one direction (east or west)?", "type": "boolean" }, "includeBacktracking": { "description": "Does the route backtrack or zigzag between regions?", "type": "boolean" } }, "required": [ "cities" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result — JSON object, shape varies by tool.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid arguments (body lists the failing fields)." }, "429": { "description": "Rate limit exceeded. Free tier: 100 requests/day per IP." } } } }, "/api/custom_route_build": { "post": { "operationId": "custom_route_build", "summary": "Build a Custom Segmented Route", "description": "Break a complex multi-city itinerary into individually-ticketable segments with carrier recommendations. Handles routes that don't fit alliance fare rules — mixed carriers, LCCs, Gulf bridge connections, surface sectors. This is how AirTreks consultants build 90% of itineraries. Use this for any route with 4+ stops, backtracking, or region combinations that alliance fares can't cover.", "tags": [ "routing" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cities": { "type": "array", "items": { "type": "string" }, "description": "Ordered list of IATA city/airport codes (e.g. ['LAX', 'NRT', 'BKK', 'CMB', 'NBO', 'LIS', 'LAX'])" }, "budget": { "description": "Budget tier: 'budget' prioritizes LCCs, 'business' prioritizes J-class product quality", "type": "string", "enum": [ "budget", "mid", "premium", "business" ] }, "preferences": { "description": "Preferences: 'no-lcc', 'lounge-access', 'short-layovers', 'surface-ok'", "type": "array", "items": { "type": "string" } }, "pax": { "description": "Number of passengers", "type": "number" } }, "required": [ "cities" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Tool result — JSON object, shape varies by tool.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid arguments (body lists the failing fields)." }, "429": { "description": "Rate limit exceeded. Free tier: 100 requests/day per IP." } } } }, "/register": { "post": { "operationId": "register", "summary": "Register for an API key", "description": "Get an API key for higher rate limits and the consultant-handoff tool (trip_idea_create).", "tags": [ "auth" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "API key issued." }, "403": { "description": "Registration currently requires a secret — contact partnerships@airtreks.com." } } } } } }