{ "openapi": "3.1.0", "info": { "title": "Farelint Airline Data API", "version": "0.1.0", "description": "Observed airline quotes with explicit provenance. No booking or checkout confirmation." }, "servers": [ { "url": "https://api.farelint.com", "description": "Production" }, { "url": "http://127.0.0.1:4188", "description": "Local development" } ], "paths": { "/v1/searches": { "post": { "operationId": "createSearch", "security": [ { "bearerKey": [] } ], "responses": { "202": { "description": "Accepted job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Structured API error (400)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "401": { "description": "Structured API error (401)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "402": { "description": "Structured API error (402)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "404": { "description": "Structured API error (404)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "409": { "description": "Structured API error (409)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "410": { "description": "Structured API error (410)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "413": { "description": "Structured API error (413)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "422": { "description": "Structured API error (422)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "429": { "description": "Structured API error (429)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "500": { "description": "Structured API error (500)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "503": { "description": "Structured API error (503)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ] } }, "/v1/searches/{id}": { "get": { "operationId": "getSearch", "security": [ { "bearerKey": [] } ], "responses": { "200": { "description": "Job state and result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Structured API error (400)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "401": { "description": "Structured API error (401)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "404": { "description": "Structured API error (404)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "410": { "description": "Structured API error (410)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "429": { "description": "Structured API error (429)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "500": { "description": "Structured API error (500)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/jobs/{id}": { "get": { "operationId": "getJob", "security": [ { "bearerKey": [] } ], "responses": { "200": { "description": "Job state and result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Structured API error (400)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "401": { "description": "Structured API error (401)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "404": { "description": "Structured API error (404)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "410": { "description": "Structured API error (410)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "429": { "description": "Structured API error (429)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "500": { "description": "Structured API error (500)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/v1/offers/{id}/details": { "post": { "operationId": "getOfferDetails", "security": [ { "bearerKey": [] } ], "responses": { "202": { "description": "Accepted job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Structured API error (400)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "401": { "description": "Structured API error (401)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "402": { "description": "Structured API error (402)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "404": { "description": "Structured API error (404)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "409": { "description": "Structured API error (409)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "410": { "description": "Structured API error (410)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "413": { "description": "Structured API error (413)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "422": { "description": "Structured API error (422)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "429": { "description": "Structured API error (429)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "500": { "description": "Structured API error (500)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "503": { "description": "Structured API error (503)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailsRequest" } } } } } }, "/v1/airlines": { "get": { "operationId": "listAirlines", "security": [ { "bearerKey": [] } ], "responses": { "200": { "description": "Supported airlines, current search availability, credit prices and request options.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AirlineList" } } } }, "400": { "description": "Structured API error (400)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "401": { "description": "Structured API error (401)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "404": { "description": "Structured API error (404)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "410": { "description": "Structured API error (410)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "429": { "description": "Structured API error (429)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "500": { "description": "Structured API error (500)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "security": [ { "bearerKey": [] } ], "responses": { "200": { "description": "Workspace credit usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "400": { "description": "Structured API error (400)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "401": { "description": "Structured API error (401)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "404": { "description": "Structured API error (404)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "410": { "description": "Structured API error (410)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "429": { "description": "Structured API error (429)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "500": { "description": "Structured API error (500)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } } }, "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/searches/async": { "post": { "operationId": "searchAsync", "security": [ { "bearerKey": [] } ], "responses": { "202": { "description": "Accepted job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Structured API error (400)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "401": { "description": "Structured API error (401)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "402": { "description": "Structured API error (402)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "404": { "description": "Structured API error (404)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "409": { "description": "Structured API error (409)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "410": { "description": "Structured API error (410)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "413": { "description": "Structured API error (413)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "422": { "description": "Structured API error (422)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "429": { "description": "Structured API error (429)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "500": { "description": "Structured API error (500)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "503": { "description": "Structured API error (503)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "summary": "Queue an airline search (source credits only)" } }, "/v1/searches/sync": { "post": { "operationId": "searchSync", "security": [ { "bearerKey": [] } ], "responses": { "200": { "description": "Accepted job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "400": { "description": "Structured API error (400)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "401": { "description": "Structured API error (401)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "402": { "description": "Structured API error (402)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "404": { "description": "Structured API error (404)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "409": { "description": "Structured API error (409)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "410": { "description": "Structured API error (410)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "413": { "description": "Structured API error (413)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "422": { "description": "Structured API error (422)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "429": { "description": "Structured API error (429)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "500": { "description": "Structured API error (500)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } }, "503": { "description": "Structured API error (503)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ApiError" } }, "required": [ "error" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "summary": "Wait for an airline search (source credits + 2)", "description": "Waits for the same durable job until terminal, bounded by its job deadline. A disconnect does not cancel the accepted job. Reuse the same Idempotency-Key or poll the job; do not submit a fresh request. Complete results charge the frozen source price plus 2; partial/failed results release the whole reservation." } }, "/v1/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "summary": "List workspace webhook endpoints", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "required": [ "endpoints" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "401": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "404": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "422": { "description": "Invalid input, unavailable endpoint or authentication failure." } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Register a signed completion endpoint", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreated" } } } }, "400": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "401": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "404": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "422": { "description": "Invalid input, unavailable endpoint or authentication failure." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointInput" } } } } } }, "/v1/webhook-endpoints/{id}": { "delete": { "operationId": "disableWebhookEndpoint", "summary": "Disable a workspace webhook endpoint", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "401": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "404": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "422": { "description": "Invalid input, unavailable endpoint or authentication failure." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/webhook-deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List retained webhook delivery history", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "401": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "404": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "422": { "description": "Invalid input, unavailable endpoint or authentication failure." } }, "parameters": [ { "name": "job_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/webhook-deliveries/{id}": { "get": { "operationId": "webhookDeliveryAttempts", "summary": "Inspect webhook delivery attempts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "401": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "404": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "422": { "description": "Invalid input, unavailable endpoint or authentication failure." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/webhook-deliveries/{id}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Redrive a retained dead delivery", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "401": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "404": { "description": "Invalid input, unavailable endpoint or authentication failure." }, "422": { "description": "Invalid input, unavailable endpoint or authentication failure." } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/jobs/{id}/html": { "get": { "summary": "Legacy signed HTML link", "description": "Compatibility endpoint for previously issued signed URLs. New job responses use clean capture URLs.", "operationId": "getSavedHtml", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspace", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Opaque signed-link parameter; use html.url unchanged." }, { "name": "attempt", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Opaque signed-link parameter; use html.url unchanged." }, { "name": "expires", "in": "query", "required": true, "schema": { "type": "integer" }, "description": "Opaque signed-link parameter; use html.url unchanged." }, { "name": "signature", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Opaque signed-link parameter; use html.url unchanged." } ], "responses": { "200": { "description": "Sanitized static HTML", "content": { "text/html": { "schema": { "type": "string" } } } }, "403": { "description": "Invalid or expired signed link" }, "404": { "description": "The retained job no longer exists" }, "410": { "description": "Capture no longer available" } }, "deprecated": true } }, "/v1/captures/{id}/html": { "get": { "operationId": "getCaptureHtml", "summary": "Open saved HTML", "description": "Anyone holding this opaque capture URL can view its static HTML until the 24-hour capture expiry. No API key or signature parameters are needed.", "security": [], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The unguessable capture ID from html.url; treat the full URL as private." } ], "responses": { "200": { "description": "Sanitized static HTML", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "The retained job no longer exists" }, "410": { "description": "Capture no longer available" } } } } }, "components": { "securitySchemes": { "bearerKey": { "type": "http", "scheme": "bearer" } }, "schemas": { "SearchRequest": { "type": "object", "properties": { "airline": { "type": "string", "enum": [ "ryanair", "easyjet", "aegean", "emirates", "qatar", "latam", "ethiopian", "copa", "avianca", "kenya" ] }, "origin": { "type": "string", "pattern": "^[A-Z]{3}$" }, "destination": { "type": "string", "pattern": "^[A-Z]{3}$" }, "departure_date": { "type": "string", "format": "date" }, "return_date": { "type": [ "string", "null" ], "format": "date" }, "passengers": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 9 }, "children": { "type": "array", "items": { "type": "object", "properties": { "age": { "type": "integer", "minimum": 2, "maximum": 17 } }, "required": [ "age" ], "additionalProperties": false } }, "infants": { "type": "array", "items": { "type": "object", "properties": { "age": { "type": "integer", "minimum": 0, "maximum": 1 }, "seat": { "type": "boolean" } }, "required": [ "age", "seat" ], "additionalProperties": false } } }, "required": [ "adults", "children", "infants" ], "additionalProperties": false }, "cabin": { "enum": [ "economy", "premium_economy", "business", "first" ] }, "market": { "type": "string", "pattern": "^[A-Z]{2}$" }, "language": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "max_credits": { "type": "integer", "minimum": 0, "maximum": 10000 }, "max_results": { "type": "integer", "minimum": 1, "maximum": 2, "description": "Premium search shortlist size; default 2. Not an exhaustive inventory request. Supported for Emirates/Qatar only." }, "webhook_endpoint_id": { "type": "string", "format": "uuid", "description": "An active webhook endpoint in your workspace. Terminal delivery adds no credits." } }, "required": [ "airline", "origin", "destination", "departure_date", "return_date", "passengers", "cabin", "market", "language", "currency" ], "additionalProperties": false }, "Price": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+(\\.\\d{1,4})?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "kind": { "enum": [ "fare_total", "cabin_starting_quote", "supplement" ] }, "basis": { "enum": [ "per_adult", "party" ] }, "quantity": { "type": "integer", "minimum": 1 }, "party_total": { "type": [ "string", "null" ], "pattern": "^\\d+(\\.\\d{1,4})?$" }, "total_method": { "enum": [ "observed", "derived", null ] }, "net": { "type": [ "string", "null" ], "pattern": "^\\d+(\\.\\d{1,4})?$" }, "taxes": { "type": [ "string", "null" ], "pattern": "^\\d+(\\.\\d{1,4})?$" }, "extras_included": { "const": false }, "checkout_verified": { "const": false }, "scope": { "enum": [ "itinerary", "outbound", "inbound", "unknown" ], "description": "Price journey scope. Bound prices inside return searches are not full return totals." } }, "required": [ "amount", "currency", "kind", "basis", "quantity", "party_total", "total_method", "net", "taxes", "extras_included", "checkout_verified" ], "additionalProperties": false }, "Segment": { "type": "object", "properties": { "origin": { "type": "string", "pattern": "^[A-Z]{3}$" }, "destination": { "type": "string", "pattern": "^[A-Z]{3}$" }, "flight_number": { "type": "string" }, "marketing_airline": { "type": [ "string", "null" ] }, "operating_airline": { "type": [ "string", "null" ] }, "departure_local": { "type": [ "string", "null" ] }, "arrival_local": { "type": [ "string", "null" ] }, "departure_utc": { "type": [ "string", "null" ], "format": "date-time" }, "arrival_utc": { "type": [ "string", "null" ], "format": "date-time" }, "direction": { "enum": [ "outbound", "inbound" ], "description": "Direction within the requested itinerary; supplied by connecting-carrier adapters." } }, "required": [ "origin", "destination", "flight_number", "marketing_airline", "operating_airline", "departure_local", "arrival_local", "departure_utc", "arrival_utc" ], "additionalProperties": false }, "Baggage": { "type": "object", "properties": { "relation": { "enum": [ "and", "or", "unknown" ] }, "personal_item": { "type": [ "boolean", "null" ] }, "cabin_bag": { "type": [ "boolean", "null" ] }, "cabin_max_kg": { "type": [ "number", "null" ], "minimum": 0 }, "cabin_dimensions_cm": { "type": [ "array", "null" ], "items": { "type": "number" }, "minItems": 3, "maxItems": 3 }, "checked_pieces": { "type": [ "integer", "null" ], "minimum": 0 }, "checked_max_kg": { "type": [ "number", "null" ], "minimum": 0 }, "source_summary": { "type": [ "string", "null" ] } }, "required": [ "relation", "personal_item", "cabin_bag", "cabin_max_kg", "cabin_dimensions_cm", "checked_pieces", "checked_max_kg", "source_summary" ], "additionalProperties": false }, "FareFamily": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "$ref": "#/components/schemas/Price" }, "baggage": { "$ref": "#/components/schemas/Baggage" }, "restrictions_summary": { "type": [ "string", "null" ] }, "conditions_status": { "enum": [ "visible_summary_only", "not_captured" ] } }, "required": [ "name", "price", "baggage", "restrictions_summary", "conditions_status" ], "additionalProperties": false }, "Offer": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "flight_numbers": { "type": "array", "items": { "type": "string" } }, "origin": { "type": "string", "pattern": "^[A-Z]{3}$" }, "destination": { "type": "string", "pattern": "^[A-Z]{3}$" }, "departure_date": { "type": "string", "format": "date" }, "return_date": { "type": [ "string", "null" ], "format": "date" }, "segments": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Segment" } }, "duration_minutes": { "type": [ "integer", "null" ], "minimum": 0 }, "stops": { "type": [ "integer", "null" ], "minimum": 0 }, "operator_name": { "type": [ "string", "null" ] }, "price": { "$ref": "#/components/schemas/Price" }, "fare_families": { "type": "array", "items": { "$ref": "#/components/schemas/FareFamily" } }, "baggage": { "$ref": "#/components/schemas/Baggage" }, "missing_fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "flight_numbers", "origin", "destination", "departure_date", "return_date", "segments", "duration_minutes", "stops", "operator_name", "price", "fare_families", "baggage", "missing_fields" ], "additionalProperties": false }, "OperationResult": { "type": "object", "properties": { "schema_version": { "const": "1" }, "airline": { "type": "string", "enum": [ "ryanair", "easyjet", "aegean", "emirates", "qatar", "latam", "ethiopian", "copa", "avianca", "kenya" ] }, "operation": { "enum": [ "search", "details" ] }, "observed_at": { "type": "string", "format": "date-time" }, "source_priced_at": { "type": [ "string", "null" ], "format": "date-time" }, "request": { "$ref": "#/components/schemas/SearchRequest" }, "effective_request": { "$ref": "#/components/schemas/EffectiveRequest" }, "outcome": { "enum": [ "offers", "no_flights", "offer_unavailable", "offer_unmatched", "error" ] }, "completeness": { "type": "object", "properties": { "complete": { "type": "boolean" }, "missing_fields": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "complete", "missing_fields", "warnings" ], "additionalProperties": false }, "capture_scope": { "const": "captured_results" }, "itineraries": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "source": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "link_kind": { "enum": [ "search", "session_bound", "homepage", "none" ] }, "parser_version": { "type": "string" } }, "required": [ "url", "link_kind", "parser_version" ], "additionalProperties": false }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ApiError" }, { "type": "null" } ] }, "coverage": { "type": "object", "properties": { "requested_max_results": { "type": "integer", "minimum": 1, "maximum": 2 }, "returned_results": { "type": "integer", "minimum": 0, "maximum": 2 }, "exhaustive": { "const": false }, "selection": { "enum": [ "fixed_outbound_return_alternatives", "nonstop_alternatives", "one_way_alternatives" ] } }, "required": [ "requested_max_results", "returned_results", "exhaustive", "selection" ], "additionalProperties": false } }, "required": [ "schema_version", "airline", "operation", "observed_at", "source_priced_at", "request", "effective_request", "outcome", "completeness", "capture_scope", "itineraries", "source", "error" ], "additionalProperties": false }, "ApiError": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry_after_seconds": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "code", "message", "retry_after_seconds" ], "additionalProperties": false }, "DetailsRequest": { "type": "object", "properties": { "max_credits": { "type": "integer", "minimum": 0, "maximum": 10000 }, "webhook_endpoint_id": { "type": "string", "format": "uuid" } }, "required": [], "additionalProperties": false }, "Job": { "type": "object", "properties": { "id": { "type": "string" }, "operation": { "enum": [ "search", "details" ] }, "airline": { "type": "string", "enum": [ "ryanair", "easyjet", "aegean", "emirates", "qatar", "latam", "ethiopian", "copa", "avianca", "kenya" ] }, "state": { "enum": [ "queued", "running", "completed", "partial", "failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "reserved_credits": { "type": "integer", "minimum": 0 }, "charged_credits": { "type": "integer", "minimum": 0 }, "cost_version": { "type": "string" }, "poll_url": { "type": "string" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/OperationResult" }, { "type": "null" } ] }, "error": { "anyOf": [ { "$ref": "#/components/schemas/ApiError" }, { "type": "null" } ] }, "attempts": { "type": "integer", "minimum": 0 }, "credit_quote": { "type": "object", "properties": { "source_credits": { "type": "integer", "minimum": 1 }, "sync_surcharge": { "enum": [ 0, 2 ] }, "total_credits": { "type": "integer", "minimum": 1 }, "delivery_mode": { "enum": [ "async", "sync" ] }, "basis": { "enum": [ "legacy", "unmeasured", "provisional", "measured" ] } }, "required": [ "source_credits", "sync_surcharge", "total_credits", "delivery_mode", "basis" ], "additionalProperties": false }, "html": { "description": "Clean link to the latest finished attempt’s saved static HTML. Works without an API key or signature parameters until expires_at, 24 hours after the capture was saved. Anyone holding the URL can view that capture. Null when no retained HTML is available; reading the job does not extend retention.", "anyOf": [ { "type": "null" }, { "type": "object", "additionalProperties": false, "properties": { "url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "url", "expires_at" ] } ] } }, "required": [ "id", "operation", "airline", "state", "created_at", "updated_at", "observed_at", "reserved_credits", "charged_credits", "cost_version", "poll_url", "result", "error", "attempts" ], "additionalProperties": false }, "EffectiveRequest": { "type": "object", "properties": { "airline": { "type": "string", "enum": [ "ryanair", "easyjet", "aegean", "emirates", "qatar", "latam", "ethiopian", "copa", "avianca", "kenya" ] }, "origin": { "type": "string", "pattern": "^[A-Z]{3}$" }, "destination": { "type": "string", "pattern": "^[A-Z]{3}$" }, "departure_date": { "type": "string", "format": "date" }, "return_date": { "type": [ "string", "null" ], "format": "date" }, "passengers": { "type": "object", "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 9 }, "children": { "type": "array", "items": { "type": "object", "properties": { "age": { "type": "integer", "minimum": 2, "maximum": 17 } }, "required": [ "age" ], "additionalProperties": false } }, "infants": { "type": "array", "items": { "type": "object", "properties": { "age": { "type": "integer", "minimum": 0, "maximum": 1 }, "seat": { "type": "boolean" } }, "required": [ "age", "seat" ], "additionalProperties": false } } }, "required": [ "adults", "children", "infants" ], "additionalProperties": false }, "cabin": { "enum": [ "economy", "premium_economy", "business", "first" ] }, "market": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$" }, "language": { "type": [ "string", "null" ], "pattern": "^[a-z]{2}(-[A-Z]{2})?$" }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "max_credits": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "airline", "origin", "destination", "departure_date", "return_date", "passengers", "cabin", "market", "language", "currency" ], "additionalProperties": false }, "LedgerEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "job_id": { "type": "string", "format": "uuid" }, "event": { "enum": [ "reserve", "charge", "release" ] }, "amount": { "type": "integer", "minimum": 1 }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "job_id", "event", "amount", "created_at" ], "additionalProperties": false }, "Usage": { "type": "object", "properties": { "period": { "type": "string" }, "granted": { "type": "integer", "minimum": 0 }, "consumed": { "type": "integer", "minimum": 0 }, "reserved": { "type": "integer", "minimum": 0 }, "available": { "type": "integer", "minimum": 0 }, "overages": { "const": false }, "ledger": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "period", "granted", "consumed", "reserved", "available", "overages", "ledger", "next_cursor" ], "additionalProperties": false }, "WebhookEndpointInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "url": { "type": "string", "format": "uri", "maxLength": 2048 } }, "required": [ "name", "url" ], "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "url", "created_at", "disabled_at" ], "additionalProperties": false }, "WebhookEndpointCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" }, "signing_secret": { "type": "string", "description": "Shown only in this response. Store securely." } }, "required": [ "id", "name", "url", "created_at", "disabled_at", "signing_secret" ], "additionalProperties": false }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "job.completed", "job.partial", "job.failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "job": { "$ref": "#/components/schemas/Job" }, "result_omitted": { "type": "boolean" } }, "required": [ "id", "type", "created_at", "job", "result_omitted" ], "additionalProperties": false }, "Airline": { "type": "object", "properties": { "airline": { "type": "string", "enum": [ "ryanair", "easyjet", "aegean", "emirates", "qatar", "latam", "ethiopian", "copa", "avianca", "kenya" ] }, "name": { "type": "string" }, "iata": { "type": "string", "pattern": "^[A-Z0-9]{2}$" }, "operations": { "type": "object", "properties": { "search": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "async_credits": { "type": [ "integer", "null" ], "minimum": 1 }, "sync_credits": { "type": [ "integer", "null" ], "minimum": 1 } }, "required": [ "enabled", "async_credits", "sync_credits" ], "additionalProperties": false }, "details": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "credits": { "type": "integer", "minimum": 1 } }, "required": [ "enabled" ], "additionalProperties": false } }, "required": [ "search", "details" ], "additionalProperties": false }, "capabilities": { "type": "object", "properties": { "one_way": { "type": "boolean" }, "return": { "type": "boolean" }, "adults": { "type": "object", "properties": { "min": { "type": "integer", "minimum": 1 }, "max": { "type": "integer", "minimum": 1 } }, "required": [ "min", "max" ], "additionalProperties": false }, "children": { "const": false }, "infants": { "const": false }, "cabins": { "type": "array", "items": { "const": "economy" } }, "currencies": { "type": "array", "items": { "type": "string" } }, "languages": { "type": "array", "items": { "type": "string" } }, "routes": { "type": "array", "items": { "type": "object", "properties": { "origin": { "type": "string", "pattern": "^[A-Z]{3}$" }, "destination": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "origin", "destination" ], "additionalProperties": false } } }, "required": [ "one_way", "return", "adults", "children", "infants", "cabins", "currencies", "languages", "routes" ], "additionalProperties": false } }, "required": [ "airline", "name", "iata", "operations", "capabilities" ], "additionalProperties": false }, "AirlineList": { "type": "object", "properties": { "airlines": { "type": "array", "items": { "$ref": "#/components/schemas/Airline" } } }, "required": [ "airlines" ], "additionalProperties": false } } } }