{ "openapi": "3.1.1", "info": { "title": "Orbit Travel API", "description": "Search destinations, flights and seat maps, book and pay, manage saved passengers and Orbit Miles, and receive booking and payment events by webhook or from the Events API.\n\nEvery request needs an API key in the `x-api-key` header, or an OAuth access token from Create an access token in `Authorization: Bearer …`. Each credential can make 60 requests a minute.", "version": "1.0.0", "contact": {} }, "servers": [ { "url": "http://localhost:3010", "description": "Local" }, { "url": "https://api.orbit-travel.example", "description": "Production" } ], "tags": [ { "name": "Authentication" }, { "name": "Destinations" }, { "name": "Flights" }, { "name": "Seats" }, { "name": "Bookings" }, { "name": "Passengers" }, { "name": "Payments" }, { "name": "Loyalty" }, { "name": "Events" }, { "name": "Webhooks" } ], "paths": { "/v1/bookings": { "get": { "operationId": "list-bookings", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Items per page.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number", "examples": [ 20 ] } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor from the previous page's `nextCursor`. Omit for the first page.", "schema": { "type": "string", "examples": [ "eyJpZCI6ImJrXzEwIn0" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingListDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "List bookings", "tags": [ "Bookings" ], "description": "Lists your bookings, newest first.", "x-orbitdocs-order": 2, "x-orbitdocs-handler": "BookingsController_list_v1" }, "post": { "operationId": "create-a-booking", "parameters": [ { "name": "Idempotency-Key", "required": false, "in": "header", "schema": { "type": "string", "examples": [ "a3f1c2d4-booking-8812" ] }, "description": "Unique key per booking attempt; retries with the same key return the first result." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBookingDto" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No flight with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "409": { "description": "Not enough seats left in this cabin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 409, "message": "Conflict", "error": "Conflict" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Create a booking", "tags": [ "Bookings" ], "x-codeSamples": [ { "lang": "typescript", "label": "TypeScript SDK", "source": "const booking = await orbit.bookings.create({\n flightId: 'flt_2031_proxima',\n cabin: 'economy',\n passengers: [{ name: 'Ada Lovelace', email: 'ada@example.com' }],\n});" } ], "description": "Books seats on a flight for one or more passengers. The booking is\nconfirmed immediately when seats are available; a `booking.confirmed`\nwebhook follows.\n\nSend an `Idempotency-Key` so a retried request never books twice.", "x-orbitdocs-order": 1, "x-orbitdocs-handler": "BookingsController_create_v1" } }, "/v1/bookings/{id}": { "get": { "operationId": "get-a-booking", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Booking id.", "schema": { "type": "string", "examples": [ "bk_7Hq2xP" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No booking with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Get a booking", "tags": [ "Bookings" ], "description": "Returns one booking.\n\n> [!TIP]\n> Store the booking \\`id\\` you get from Create a booking; it is the only way to fetch it later.", "x-orbitdocs-order": 3, "x-orbitdocs-handler": "BookingsController_get_v1" }, "patch": { "operationId": "update-a-booking", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Booking id.", "schema": { "type": "string", "examples": [ "bk_7Hq2xP" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBookingDto" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No booking with this id, or no active hold with `holdId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "409": { "description": "The booking is cancelled, or a seat is taken.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 409, "message": "Conflict", "error": "Conflict" } } } } } }, "422": { "description": "The number of passengers or seats does not match the booking, or a seat is in another cabin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 422, "message": "Unprocessable Entity" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Update a booking", "tags": [ "Bookings" ], "description": "Changes a booking: correct passenger details, choose seats or change\nyour reference. Send only what changes. Seats come one per passenger, in\npassenger order; assign held seats by sending the hold's `holdId`. A\n`booking.changed` webhook follows, with the previous values.", "x-orbitdocs-order": 4, "x-orbitdocs-handler": "BookingsController_update_v1" } }, "/v1/bookings/{id}/boarding-pass": { "get": { "operationId": "download-a-boarding-pass", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Booking id.", "schema": { "type": "string", "examples": [ "bk_7Hq2xP" ] } }, { "name": "format", "required": false, "in": "query", "description": "`pdf` to print, `png` for the barcode image (wallet apps), `json` to render your own.", "schema": { "$ref": "#/components/schemas/BoardingPassFormat" } }, { "name": "passenger", "required": false, "in": "query", "description": "Only this passenger (0-based position on the booking). Omit for everyone.", "schema": { "minimum": 0, "type": "number", "examples": [ 0 ] } } ], "responses": { "200": { "description": "The boarding pass, in the format asked for.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } }, "Content-Disposition": { "description": "File name to save as (PDF and PNG).", "schema": { "type": "string", "examples": [ "attachment; filename=\"boarding-pass-bk_7Hq2xP.pdf\"" ] } } }, "content": { "application/pdf": { "schema": { "description": "One page per passenger." } }, "image/png": { "schema": { "description": "Barcode of the first passenger (or of `passenger`)." } }, "application/json": { "schema": { "$ref": "#/components/schemas/BoardingPassDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No booking with this id, or no such passenger.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "409": { "description": "The booking is cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 409, "message": "Conflict", "error": "Conflict" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Download a boarding pass", "tags": [ "Bookings" ], "description": "Downloads the boarding pass of a confirmed booking: a printable PDF\n(default), a PNG of the barcode for wallet apps (`format=png`), or the\ndata as JSON to render your own (`format=json`).", "x-orbitdocs-order": 8, "x-orbitdocs-handler": "BookingsController_boardingPass_v1" } }, "/v1/bookings/{id}/cancel": { "post": { "operationId": "cancel-a-booking", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Booking id.", "schema": { "type": "string", "examples": [ "bk_7Hq2xP" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelBookingDto" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No booking with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Cancel a booking", "tags": [ "Bookings" ], "x-orbitdocs-content": [ { "markdown": "> [!WARNING]\n> Cancelling less than 24 hours before departure is not refunded.", "position": "after-description" } ], "description": "Cancels a booking and releases its seats. Cancelling twice is a no-op.", "x-orbitdocs-order": 5, "x-orbitdocs-handler": "BookingsController_cancel_v1" } }, "/v1/bookings/{id}/documents": { "get": { "operationId": "list-travel-documents", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Booking id.", "schema": { "type": "string", "examples": [ "bk_7Hq2xP" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelDocumentListDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No booking with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "List travel documents", "tags": [ "Bookings" ], "description": "Lists the travel documents uploaded to a booking, with their review\nstatus. Passports are usually verified within an hour.", "x-orbitdocs-order": 7, "x-orbitdocs-handler": "BookingsController_documents_v1" }, "post": { "operationId": "upload-a-travel-document", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Booking id.", "schema": { "type": "string", "examples": [ "bk_7Hq2xP" ] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadDocumentDto" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No booking with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Upload a travel document", "tags": [ "Bookings" ], "description": "Attaches a travel document (passport or visa scan) to a booking.", "x-orbitdocs-order": 6, "x-orbitdocs-stability": "beta", "x-orbitdocs-handler": "BookingsController_upload_v1" } }, "/v1/bookings/{id}/payments": { "post": { "operationId": "pay-for-a-booking", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Booking id.", "schema": { "type": "string", "examples": [ "bk_9Rz4Wt" ] } }, { "name": "Idempotency-Key", "required": true, "in": "header", "schema": { "type": "string", "examples": [ "8e03978e-40d5-43e8-bc93-6894a57f9324" ] }, "description": "Unique key per payment attempt (a UUID works). Keys are kept for 24 hours." } ], "requestBody": { "required": true, "description": "One of three shapes, told apart by `type`.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CardPaymentRequestDto" }, { "$ref": "#/components/schemas/WalletPaymentRequestDto" }, { "$ref": "#/components/schemas/BankTransferPaymentRequestDto" } ], "discriminator": { "propertyName": "type", "mapping": { "card": "#/components/schemas/CardPaymentRequestDto", "wallet": "#/components/schemas/WalletPaymentRequestDto", "bank_transfer": "#/components/schemas/BankTransferPaymentRequestDto" } } } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } }, "Idempotent-Replayed": { "description": "`true` when this is the stored response to an earlier request with the same key.", "schema": { "type": "string", "examples": [ "true" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentDto" } } } }, "400": { "description": "The body is invalid, or the `Idempotency-Key` header is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No booking with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "409": { "description": "The booking is cancelled or already paid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 409, "message": "Conflict", "error": "Conflict" } } } } } }, "422": { "description": "This `Idempotency-Key` was already used with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 422, "message": "Unprocessable Entity" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Pay for a booking", "tags": [ "Payments" ], "description": "Pays for a booking by card, digital wallet or bank transfer; `type`\npicks which. Cards and wallets are charged at once and the payment is\n`succeeded` or `failed` (a `payment.succeeded` or `payment.failed`\nwebhook follows). Bank transfers stay `pending` until the money arrives;\n`method.bankTransfer` says where to send it.\n\nThe `Idempotency-Key` header is required: retrying with the same key\nreturns the first payment (with `Idempotent-Replayed: true`) and never\ncharges twice.", "x-orbitdocs-order": 1, "x-orbitdocs-handler": "PaymentsController_create_v1" } }, "/v1/destinations": { "get": { "operationId": "list-destinations", "parameters": [ { "name": "climate", "required": false, "in": "query", "description": "Only destinations with this climate.", "schema": { "$ref": "#/components/schemas/Climate" } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number", "examples": [ 20 ] } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor from the previous page's `nextCursor`. Omit for the first page.", "schema": { "type": "string", "examples": [ "eyJpZCI6ImJrXzEwIn0" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationListDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "List destinations", "tags": [ "Destinations" ], "description": "Lists the destinations you can book, newest first. Filter by climate.", "x-orbitdocs-order": 1, "x-orbitdocs-handler": "DestinationsController_list_v1" } }, "/v1/destinations/{id}": { "get": { "operationId": "get-a-destination", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Destination id.", "schema": { "type": "string", "examples": [ "dst_kepler22b" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No destination with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Get a destination", "tags": [ "Destinations" ], "description": "Returns one destination with its travel conditions.", "x-orbitdocs-order": 2, "x-orbitdocs-handler": "DestinationsController_get_v1" } }, "/v1/events": { "get": { "operationId": "list-events", "parameters": [ { "name": "type", "required": false, "in": "query", "description": "Only events of this type.", "schema": { "$ref": "#/components/schemas/WebhookEvent" } }, { "name": "created[gte]", "required": false, "in": "query", "description": "Only events created at or after this time.", "schema": { "format": "date-time", "type": "string", "examples": [ "2026-10-01T00:00:00Z" ] } }, { "name": "created[lte]", "required": false, "in": "query", "description": "Only events created at or before this time.", "schema": { "format": "date-time", "type": "string", "examples": [ "2026-10-31T23:59:59Z" ] } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number", "examples": [ 20 ] } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor from the previous page's `nextCursor`. Omit for the first page.", "schema": { "type": "string", "examples": [ "eyJpZCI6ImJrXzEwIn0" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventListDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "List events", "tags": [ "Events" ], "description": "Lists events from the last 30 days, newest first: the same payloads\nwebhooks deliver. Use it to catch up after downtime, or instead of\nwebhooks if you cannot receive them.", "x-orbitdocs-order": 1, "x-orbitdocs-handler": "EventsController_list_v1" } }, "/v1/events/{id}": { "get": { "operationId": "get-an-event", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Event id.", "schema": { "type": "string", "examples": [ "evt_N3wB9k" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No event with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Get an event", "tags": [ "Events" ], "description": "Returns one event. Webhook deliveries carry its `id`: fetch it to check a\ndelivery is genuine without verifying the signature.", "x-orbitdocs-order": 2, "x-orbitdocs-handler": "EventsController_get_v1" } }, "/v1/flights": { "get": { "operationId": "search-flights", "parameters": [ { "name": "departsAfter", "required": false, "in": "query", "description": "Earliest departure date (UTC).", "schema": { "format": "date", "type": "string", "examples": [ "2031-01-01" ] } }, { "name": "destinationId", "required": false, "in": "query", "description": "Destination id to fly to.", "schema": { "type": "string", "examples": [ "dst_proxima_b" ] } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number", "examples": [ 20 ] } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor from the previous page's `nextCursor`. Omit for the first page.", "schema": { "type": "string", "examples": [ "eyJpZCI6ImJrXzEwIn0" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlightListDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Search flights", "tags": [ "Flights" ], "description": "Searches scheduled flights. Results are ordered by departure time.", "x-orbitdocs-order": 1, "x-orbitdocs-handler": "FlightsController_search_v1" } }, "/v1/flights/{id}": { "get": { "operationId": "get-a-flight", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Flight id.", "schema": { "type": "string", "examples": [ "flt_2031_proxima" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlightDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No flight with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Get a flight", "tags": [ "Flights" ], "description": "Returns one flight with its current fares and seat availability.", "x-orbitdocs-order": 2, "x-orbitdocs-handler": "FlightsController_get_v1" } }, "/v1/flights/{id}/seat-holds": { "post": { "operationId": "hold-seats", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Flight id.", "schema": { "type": "string", "examples": [ "flt_2031_proxima" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSeatHoldDto" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatHoldDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No flight with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "409": { "description": "A seat is taken or already held.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 409, "message": "Conflict", "error": "Conflict" } } } } } }, "422": { "description": "A seat does not exist on this flight, or the seats span cabins.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 422, "message": "Unprocessable Entity" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Hold seats", "tags": [ "Seats" ], "description": "Holds seats for 15 minutes while your customer finishes checking out.\nAssign them with Update a booking (`holdId`) before `expiresAt`, or they\nare released.", "x-orbitdocs-order": 2, "x-orbitdocs-handler": "SeatsController_hold_v1" } }, "/v1/flights/{id}/seats": { "get": { "operationId": "get-a-seat-map", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Flight id.", "schema": { "type": "string", "examples": [ "flt_2031_proxima" ] } }, { "name": "cabin", "required": false, "in": "query", "description": "Only this cabin.", "schema": { "$ref": "#/components/schemas/CabinClass" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeatMapDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No flight with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Get a seat map", "tags": [ "Seats" ], "description": "Returns the seat map of a flight: every cabin, row and seat, with what is\nfree right now. Seats in the exit row cost extra.", "x-orbitdocs-order": 1, "x-orbitdocs-handler": "SeatsController_seatMap_v1" } }, "/v1/flights/search-legacy": { "get": { "operationId": "legacy-flight-search", "parameters": [ { "name": "destination", "required": false, "in": "query", "description": "Destination id (renamed `destinationId` in Search flights).", "schema": { "type": "string", "examples": [ "dst_proxima_b" ] } }, { "name": "page", "required": false, "in": "query", "description": "Page number, starting at 1.", "schema": { "minimum": 1, "default": 1, "type": "number", "examples": [ 1 ] } }, { "name": "perPage", "required": false, "in": "query", "description": "Flights per page.", "schema": { "minimum": 1, "maximum": 50, "default": 10, "type": "number", "examples": [ 10 ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } }, "Deprecation": { "description": "Always `true`: this endpoint is deprecated.", "schema": { "type": "string", "examples": [ "true" ] } }, "Sunset": { "description": "When the endpoint stops working (HTTP date).", "schema": { "type": "string", "examples": [ "Wed, 31 Mar 2032 00:00:00 GMT" ] } }, "Link": { "description": "The replacement endpoint.", "schema": { "type": "string", "examples": [ "; rel=\"successor-version\"" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyFlightSearchDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Legacy flight search", "tags": [ "Flights" ], "description": "The first flight search, with page numbers instead of cursors. It is\nslower on large result sets and is switched off on 31 March 2032.\n\n> [!WARNING]\n> Deprecated: use [Search flights](#search-flights). Rename `destination`\n> to `destinationId`, and follow `page.nextCursor` instead of counting pages.", "x-orbitdocs-order": 3, "x-orbitdocs-stability": "deprecated", "deprecated": true, "x-orbitdocs-handler": "FlightsController_searchLegacy_v1" } }, "/v1/loyalty/account": { "get": { "operationId": "get-the-loyalty-account", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyAccountDto" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Get the loyalty account", "tags": [ "Loyalty" ], "description": "Returns the Orbit Miles account of the customer the key belongs to:\nbalance, tier and how far the next tier is. Paid bookings earn one point\nper dollar.", "x-orbitdocs-order": 1, "x-orbitdocs-handler": "LoyaltyController_account_v1" } }, "/v1/loyalty/redemptions": { "post": { "operationId": "redeem-points", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRedemptionDto" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No booking with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "409": { "description": "Not enough points for this reward.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 409, "message": "Conflict", "error": "Conflict" } } } } } }, "422": { "description": "This reward needs a `bookingId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 422, "message": "Unprocessable Entity" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Redeem points", "tags": [ "Loyalty" ], "description": "Spends points on a reward. The points leave the balance at once and a\n`redeem` transaction is recorded.", "x-orbitdocs-order": 3, "x-orbitdocs-handler": "LoyaltyController_redeem_v1" } }, "/v1/loyalty/transactions": { "get": { "operationId": "list-loyalty-transactions", "parameters": [ { "name": "type", "required": false, "in": "query", "description": "Only transactions of this type.", "schema": { "$ref": "#/components/schemas/LoyaltyTransactionType" } }, { "name": "limit", "required": false, "in": "query", "description": "Items per page.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number", "examples": [ 20 ] } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor from the previous page's `nextCursor`. Omit for the first page.", "schema": { "type": "string", "examples": [ "eyJpZCI6ImJrXzEwIn0" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoyaltyTransactionListDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "List loyalty transactions", "tags": [ "Loyalty" ], "description": "Lists points earned, spent, expired and adjusted, newest first.", "x-orbitdocs-order": 2, "x-orbitdocs-handler": "LoyaltyController_transactions_v1" } }, "/v1/oauth/token": { "post": { "operationId": "create-an-access-token", "parameters": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequestDto" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponseDto" } } } }, "400": { "description": "Malformed request, unsupported `grant_type` or unknown scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorDto" } } } }, "401": { "description": "Unknown client or wrong secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthErrorDto" } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "summary": "Create an access token", "tags": [ "Authentication" ], "description": "Exchanges your client id and secret for an access token (OAuth 2.0\nclient credentials grant). Send the token as `Authorization: Bearer …`\ninstead of an API key; it expires after an hour.\n\nThis endpoint takes no API key or token itself.", "x-orbitdocs-order": 1, "x-orbitdocs-handler": "OAuthController_token_v1" } }, "/v1/passengers": { "get": { "operationId": "list-passengers", "parameters": [ { "name": "limit", "required": false, "in": "query", "description": "Items per page.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "number", "examples": [ 20 ] } }, { "name": "cursor", "required": false, "in": "query", "description": "Cursor from the previous page's `nextCursor`. Omit for the first page.", "schema": { "type": "string", "examples": [ "eyJpZCI6ImJrXzEwIn0" ] } }, { "name": "email", "required": false, "in": "query", "description": "Only the passenger with this email.", "schema": { "format": "email", "type": "string", "examples": [ "ada@example.com" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassengerListDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "List passengers", "tags": [ "Passengers" ], "description": "Lists saved passengers, newest first. Filter by email to find one.", "x-orbitdocs-order": 2, "x-orbitdocs-handler": "PassengersController_list_v1" }, "post": { "operationId": "create-a-passenger", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePassengerDto" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassengerProfileDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "409": { "description": "A passenger with this email already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 409, "message": "Conflict", "error": "Conflict" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Create a passenger", "tags": [ "Passengers" ], "description": "Saves a passenger profile so you can book them again without retyping\ntheir passport details.", "x-orbitdocs-order": 1, "x-orbitdocs-handler": "PassengersController_create_v1" } }, "/v1/passengers/{id}": { "get": { "operationId": "get-a-passenger", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Passenger id.", "schema": { "type": "string", "examples": [ "psg_8Fk2Lm" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassengerProfileDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No passenger with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Get a passenger", "tags": [ "Passengers" ], "description": "Returns one saved passenger.", "x-orbitdocs-order": 3, "x-orbitdocs-handler": "PassengersController_get_v1" }, "delete": { "operationId": "delete-a-passenger", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Passenger id.", "schema": { "type": "string", "examples": [ "psg_8Fk2Lm" ] } } ], "responses": { "204": { "description": "No content", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No passenger with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Delete a passenger", "tags": [ "Passengers" ], "description": "Deletes a saved passenger. Bookings they are on are not affected.", "x-orbitdocs-order": 5, "x-orbitdocs-handler": "PassengersController_remove_v1" }, "patch": { "operationId": "update-a-passenger", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Passenger id.", "schema": { "type": "string", "examples": [ "psg_8Fk2Lm" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePassengerDto" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PassengerProfileDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No passenger with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "409": { "description": "Another passenger already has this email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 409, "message": "Conflict", "error": "Conflict" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Update a passenger", "tags": [ "Passengers" ], "description": "Changes some fields of a passenger; fields you leave out keep their\nvalue. Send `passport: null` to remove the passport, and an empty string\nfor a `metadata` key to remove that key.", "x-orbitdocs-order": 4, "x-orbitdocs-handler": "PassengersController_update_v1" } }, "/v1/payments/{id}": { "get": { "operationId": "get-a-payment", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Payment id.", "schema": { "type": "string", "examples": [ "pay_3kTq9Z" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No payment with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Get a payment", "tags": [ "Payments" ], "description": "Returns one payment with its refunds.", "x-orbitdocs-order": 2, "x-orbitdocs-handler": "PaymentsController_get_v1" } }, "/v1/payments/{id}/refunds": { "post": { "operationId": "refund-a-payment", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Payment id.", "schema": { "type": "string", "examples": [ "pay_3kTq9Z" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundDto" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No payment with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "409": { "description": "The payment has not succeeded, or is already fully refunded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 409, "message": "Conflict", "error": "Conflict" } } } } } }, "422": { "description": "`amount` is more than what is left to refund.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 422, "message": "Unprocessable Entity" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Refund a payment", "tags": [ "Payments" ], "description": "Returns money to the customer, all of it or part. Refund several times\nuntil the payment is fully refunded. Refunding does not cancel the\nbooking; cancel it first if the customer is not flying.", "x-orbitdocs-order": 3, "x-orbitdocs-handler": "PaymentsController_refund_v1" } }, "/v1/webhook-endpoints": { "get": { "operationId": "list-webhook-endpoints", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointListDto" } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "List webhook endpoints", "tags": [ "Webhooks" ], "description": "Lists your webhook endpoints.", "x-orbitdocs-order": 2, "x-orbitdocs-handler": "WebhooksController_list_v1" }, "post": { "operationId": "create-a-webhook-endpoint", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointDto" } } } }, "responses": { "201": { "description": "Created", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Create a webhook endpoint", "tags": [ "Webhooks" ], "description": "Registers a URL to receive booking and payment events. Deliveries are signed with the\nreturned `secret`; verify the `Orbit-Signature` header before trusting them.", "x-orbitdocs-order": 1, "x-orbitdocs-handler": "WebhooksController_create_v1" } }, "/v1/webhook-endpoints/{id}": { "delete": { "operationId": "delete-a-webhook-endpoint", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Endpoint id.", "schema": { "type": "string", "examples": [ "whe_91ka2" ] } } ], "responses": { "204": { "description": "No content", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No webhook endpoint with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "description": "Stops deliveries to an endpoint and deletes it.", "x-orbitdocs-order": 3, "x-orbitdocs-handler": "WebhooksController_remove_v1" } }, "/v1/webhook-endpoints/{id}/test": { "post": { "operationId": "send-a-test-event", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "Endpoint id.", "schema": { "type": "string", "examples": [ "whe_91ka2" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestWebhookEndpointDto" } } } }, "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryDto" } } } }, "400": { "description": "The request is invalid: a parameter or body field failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 400, "message": [ "email must be an email" ], "error": "Bad Request" } } } } } }, "401": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 401, "message": "Unauthorized" } } } } } }, "403": { "description": "Authenticated, but not allowed to do this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 403, "message": "Forbidden resource", "error": "Forbidden" } } } } } }, "404": { "description": "No webhook endpoint with this id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 404, "message": "Not Found" } } } } } }, "429": { "description": "Too many requests: more than 60 a minute. Wait `Retry-After` seconds, then retry.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 42 ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this credential.", "schema": { "type": "integer", "examples": [ 60 ] } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer", "examples": [ 59 ] } }, "X-RateLimit-Reset": { "description": "When the window resets, in Unix seconds.", "schema": { "type": "integer", "examples": [ 1949398800 ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 429, "message": "Rate limit exceeded: 60 requests per minute. Wait Retry-After seconds." } } } } } }, "500": { "description": "Something failed on the server. Retry with backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "default": { "value": { "statusCode": 500, "message": "Internal server error" } } } } } } }, "security": [ { "apiKey": [] }, { "bearer": [] } ], "summary": "Send a test event", "tags": [ "Webhooks" ], "description": "Sends a signed sample event to the endpoint right away and reports how\nyour server answered, so you can check signature verification before\nreal traffic arrives. The endpoint does not have to subscribe to the\nevent type. Test events are not listed by List events.", "x-orbitdocs-order": 4, "x-orbitdocs-handler": "WebhooksController_test_v1" } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your API key. The sample server accepts `otk_test_4f9a2c1b8e7d6a5f`." }, "bearer": { "type": "http", "scheme": "bearer", "description": "An OAuth access token from `POST /v1/oauth/token` (client credentials). The sample server accepts client `oc_test_orbit_demo` with secret `ocs_test_5e8d2a7c9b1f`. Tokens last an hour." } }, "schemas": { "BankTransferInstructionsDto": { "type": "object", "properties": { "dueAt": { "type": "string", "format": "date-time", "description": "Pay by then, or the booking is cancelled.", "examples": [ "2026-10-11T12:00:00Z" ] }, "iban": { "type": "string", "description": "Account to send the money to.", "examples": [ "DE89370400440532013000" ] }, "bic": { "type": "string", "description": "Bank identifier.", "examples": [ "COBADEFFXXX" ] }, "reference": { "type": "string", "description": "Put this in the transfer's reference so we can match it.", "examples": [ "ORBIT-BK7HQ2XP" ] } }, "required": [ "dueAt", "iban", "bic", "reference" ] }, "BankTransferPaymentRequestDto": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Up to 20 key-value pairs of your own, returned on the payment and in its webhooks.", "examples": [ { "orderId": "order-8812", "channel": "web" } ] }, "type": { "type": "string", "enum": [ "bank_transfer" ], "description": "Pay by bank transfer. The payment stays `pending` until the money arrives.", "examples": [ "bank_transfer" ] }, "accountHolderName": { "type": "string", "description": "Name on the paying account.", "examples": [ "Ada Lovelace" ] }, "country": { "type": "string", "description": "Country of the paying bank, ISO 3166-1 alpha-2 (SEPA countries only).", "pattern": "^[A-Z]{2}$", "examples": [ "DE" ] } }, "required": [ "type", "accountHolderName", "country" ] }, "BoardingGroup": { "type": "string", "enum": [ "A", "B", "C" ], "description": "Boarding group, called in order." }, "BoardingPassDto": { "type": "object", "properties": { "boardingAt": { "type": "string", "format": "date-time", "description": "Boarding opens (45 minutes before departure).", "examples": [ "2031-04-12T07:15:00Z" ] }, "departsAt": { "type": "string", "format": "date-time", "description": "Departure time (UTC).", "examples": [ "2031-04-12T08:00:00Z" ] }, "bookingId": { "type": "string", "description": "Booking id.", "examples": [ "bk_7Hq2xP" ] }, "flightId": { "type": "string", "description": "Flight id.", "examples": [ "flt_2031_proxima" ] }, "from": { "type": "string", "description": "Departure spaceport code.", "examples": [ "KSC" ] }, "to": { "type": "string", "description": "Destination name.", "examples": [ "Proxima b" ] }, "gate": { "type": "string", "description": "Launch pad.", "examples": [ "Pad 39A" ] }, "passengers": { "description": "One entry per passenger.", "type": "array", "items": { "$ref": "#/components/schemas/BoardingPassPassengerDto" } } }, "required": [ "boardingAt", "departsAt", "bookingId", "flightId", "from", "to", "gate", "passengers" ] }, "BoardingPassFormat": { "type": "string", "enum": [ "pdf", "png", "json" ] }, "BoardingPassPassengerDto": { "type": "object", "properties": { "seat": { "type": [ "string", "null" ], "description": "Seat number; `null` when it is assigned at the gate.", "examples": [ "24A" ] }, "boardingGroup": { "description": "Boarding group, called in order.", "allOf": [ { "$ref": "#/components/schemas/BoardingGroup" } ], "examples": [ "A" ] }, "name": { "type": "string", "description": "Passenger name.", "examples": [ "Ada Lovelace" ] }, "barcode": { "type": "string", "description": "Payload of the boarding barcode (IATA BCBP style).", "examples": [ "M1LOVELACE/ADA EBK7HQ2X KSCPRXOT 2031 102Y024A 0001" ] } }, "required": [ "seat", "boardingGroup", "name", "barcode" ] }, "BookingDto": { "type": "object", "properties": { "status": { "description": "Where the booking is in its life.", "allOf": [ { "$ref": "#/components/schemas/BookingStatus" } ], "examples": [ "confirmed" ] }, "cabin": { "description": "Cabin booked.", "allOf": [ { "$ref": "#/components/schemas/CabinClass" } ], "examples": [ "economy" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the booking was created.", "examples": [ "2026-10-03T12:00:00Z" ] }, "id": { "type": "string", "description": "Booking id.", "examples": [ "bk_7Hq2xP" ] }, "flightId": { "type": "string", "description": "Flight booked.", "examples": [ "flt_2031_proxima" ] }, "passengers": { "description": "Everyone travelling.", "type": "array", "items": { "$ref": "#/components/schemas/PassengerDto" } }, "totalAmount": { "type": "number", "description": "Total charged, in cents.", "examples": [ 2599800 ] }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "examples": [ "USD" ] }, "reference": { "type": "string", "description": "Your reference, if you sent one.", "examples": [ "order-8812" ] }, "documents": { "description": "Travel documents uploaded for this booking.", "type": "array", "items": { "type": "string" }, "examples": [ [ "passport-ada.pdf" ] ] }, "seats": { "description": "Seat numbers, one per passenger in the same order. Empty until seats are\nchosen with Update a booking.", "type": "array", "items": { "type": "string" }, "examples": [ [ "24A", "24B" ] ] } }, "required": [ "status", "cabin", "createdAt", "id", "flightId", "passengers", "totalAmount", "currency", "documents", "seats" ] }, "BookingListDto": { "type": "object", "properties": { "data": { "description": "Bookings on this page, newest first.", "type": "array", "items": { "$ref": "#/components/schemas/BookingDto" } }, "page": { "description": "Pagination cursor.", "allOf": [ { "$ref": "#/components/schemas/PageInfoDto" } ] } }, "required": [ "data", "page" ] }, "BookingStatus": { "type": "string", "enum": [ "pending", "confirmed", "cancelled" ], "description": "Where the booking is in its life." }, "CabinClass": { "type": "string", "enum": [ "economy", "business", "cryosleep" ], "description": "Cabin." }, "CabinSeatMapDto": { "type": "object", "properties": { "cabin": { "description": "Cabin.", "allOf": [ { "$ref": "#/components/schemas/CabinClass" } ], "examples": [ "economy" ] }, "layout": { "description": "Column letters, left to right; an empty string marks an aisle.", "type": "array", "items": { "type": "string" }, "examples": [ [ "A", "B", "C", "", "D", "E", "F" ] ] }, "rows": { "description": "Rows, front to back.", "type": "array", "items": { "$ref": "#/components/schemas/SeatRowDto" } } }, "required": [ "cabin", "layout", "rows" ] }, "CancelBookingDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why the booking is cancelled (kept for your records).", "examples": [ "Passenger request" ] } } }, "CardBrand": { "type": "string", "enum": [ "visa", "mastercard", "amex" ], "description": "Card network." }, "CardDetailsDto": { "type": "object", "properties": { "brand": { "description": "Card network.", "allOf": [ { "$ref": "#/components/schemas/CardBrand" } ], "examples": [ "visa" ] }, "last4": { "type": "string", "description": "Last four digits.", "examples": [ "4242" ] }, "expMonth": { "type": "number", "description": "Expiry month (1–12).", "examples": [ 8 ] }, "expYear": { "type": "number", "description": "Expiry year.", "examples": [ 2033 ] } }, "required": [ "brand", "last4", "expMonth", "expYear" ] }, "CardPaymentRequestDto": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Up to 20 key-value pairs of your own, returned on the payment and in its webhooks.", "examples": [ { "orderId": "order-8812", "channel": "web" } ] }, "type": { "type": "string", "enum": [ "card" ], "description": "Pay by card.", "examples": [ "card" ] }, "token": { "type": "string", "description": "Card token from Orbit.js. Raw card numbers are never accepted. In test\nmode, `tok_chargeDeclined` fails.", "pattern": "^tok_\\w+$", "examples": [ "tok_visa_4242" ] }, "saveCard": { "type": "boolean", "description": "Keep the card for this customer's next booking." } }, "required": [ "type", "token" ] }, "Climate": { "type": "string", "enum": [ "temperate", "arid", "frozen", "oceanic" ] }, "CreateBookingDto": { "type": "object", "properties": { "cabin": { "description": "Cabin to book.", "allOf": [ { "$ref": "#/components/schemas/CabinClass" } ], "examples": [ "economy" ] }, "flightId": { "type": "string", "description": "Flight to book.", "examples": [ "flt_2031_proxima" ] }, "passengers": { "description": "Everyone travelling. At least one.", "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/PassengerDto" } }, "reference": { "type": "string", "description": "Your own reference, echoed back in webhooks.", "examples": [ "order-8812" ] } }, "required": [ "cabin", "flightId", "passengers" ] }, "CreatePassengerDto": { "type": "object", "properties": { "dateOfBirth": { "type": "string", "format": "date", "description": "Date of birth.", "examples": [ "1990-12-10" ] }, "passport": { "description": "Passport details; `null` when not on file yet.", "type": [ "object", "null" ], "allOf": [ { "$ref": "#/components/schemas/PassportDto" } ] }, "loyaltyNumber": { "type": [ "string", "null" ], "description": "Orbit Miles member number, if any.", "examples": [ "OT 4410 2291" ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Up to 20 key-value pairs of your own. Values are strings; send an empty string to remove a key.", "examples": [ { "crmId": "cus_10442", "segment": "frequent-flyer" } ] }, "firstName": { "type": "string", "description": "Given name as on the passport.", "examples": [ "Ada" ] }, "lastName": { "type": "string", "description": "Family name as on the passport.", "examples": [ "Lovelace" ] }, "email": { "type": "string", "description": "Contact email; unique per account.", "format": "email", "examples": [ "ada@example.com" ] }, "nationality": { "type": "string", "description": "Nationality, ISO 3166-1 alpha-2.", "pattern": "^[A-Z]{2}$", "examples": [ "GB" ] }, "preferences": { "description": "Seat and meal preferences.", "allOf": [ { "$ref": "#/components/schemas/TravelPreferencesDto" } ] } }, "required": [ "dateOfBirth", "firstName", "lastName", "email", "nationality" ] }, "CreateRedemptionDto": { "type": "object", "properties": { "reward": { "description": "Reward to buy. Costs: `cabin_upgrade` 40,000, `booking_credit` 10,000 ($100 off), `extra_baggage` 8,000, `lounge_access` 5,000.", "allOf": [ { "$ref": "#/components/schemas/RewardType" } ], "examples": [ "lounge_access" ] }, "bookingId": { "type": "string", "description": "Booking the reward applies to. Required for `cabin_upgrade` and `extra_baggage`.", "examples": [ "bk_7Hq2xP" ] } }, "required": [ "reward" ] }, "CreateRefundDto": { "type": "object", "properties": { "reason": { "description": "Why you are refunding.", "allOf": [ { "$ref": "#/components/schemas/RefundReason" } ], "examples": [ "requested_by_customer" ] }, "amount": { "type": "number", "description": "Amount to refund, in cents. Defaults to everything not yet refunded.", "minimum": 1, "examples": [ 50000 ] } }, "required": [ "reason" ] }, "CreateSeatHoldDto": { "type": "object", "properties": { "seats": { "description": "Seats to hold, all in one cabin. Up to nine.", "minItems": 1, "maxItems": 9, "type": "array", "items": { "type": "string", "pattern": "^\\d{1,2}[A-F]$" }, "examples": [ [ "24A", "24B" ] ] } }, "required": [ "seats" ] }, "CreateWebhookEndpointDto": { "type": "object", "properties": { "events": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "description": "Events to send.", "examples": [ [ "booking.confirmed" ] ] }, "url": { "type": "string", "description": "HTTPS URL that receives events.", "format": "uri", "examples": [ "https://example.com/webhooks/orbit" ] } }, "required": [ "events", "url" ] }, "DestinationDto": { "type": "object", "properties": { "climate": { "description": "Typical surface conditions.", "allOf": [ { "$ref": "#/components/schemas/Climate" } ], "examples": [ "oceanic" ] }, "id": { "type": "string", "description": "Destination id.", "examples": [ "dst_kepler22b" ] }, "name": { "type": "string", "description": "Display name.", "examples": [ "Kepler-22b" ] }, "system": { "type": "string", "description": "Star system it orbits.", "examples": [ "Kepler-22" ] }, "distanceLy": { "type": "number", "description": "Distance from Earth in light years.", "examples": [ 638 ] }, "gravity": { "type": "number", "description": "Gravity relative to Earth (1.0 = Earth).", "examples": [ 2.4 ] } }, "required": [ "climate", "id", "name", "system", "distanceLy", "gravity" ] }, "DestinationListDto": { "type": "object", "properties": { "data": { "description": "Destinations on this page.", "type": "array", "items": { "$ref": "#/components/schemas/DestinationDto" } }, "page": { "description": "Pagination cursor.", "allOf": [ { "$ref": "#/components/schemas/PageInfoDto" } ] } }, "required": [ "data", "page" ] }, "DocumentKind": { "type": "string", "enum": [ "passport", "visa", "health_certificate", "other" ], "description": "What the document is, detected from the scan." }, "DocumentStatus": { "type": "string", "enum": [ "pending_review", "verified", "rejected" ], "description": "Review status. Boarding needs a verified passport." }, "ErrorResponse": { "type": "object", "description": "Error body returned for every 4xx and 5xx response.", "required": [ "statusCode", "message" ], "properties": { "statusCode": { "type": "integer", "description": "HTTP status code, repeated in the body.", "examples": [ 404 ] }, "message": { "description": "What went wrong, for people. Validation failures list one entry per problem. Do not branch on this text.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "examples": [ "Booking not found" ] }, "error": { "type": "string", "description": "Short name of the status.", "examples": [ "Not Found" ] } } }, "EventDataDto": { "type": "object", "properties": { "object": { "oneOf": [ { "$ref": "#/components/schemas/BookingDto" }, { "$ref": "#/components/schemas/PaymentDto" } ], "description": "The object the event is about, as it was right after the change: a booking for `booking.*` events, a payment for `payment.*` events." }, "previousAttributes": { "type": [ "object", "null" ], "additionalProperties": true, "description": "For `booking.changed`: the changed fields with their previous values. `null` for other events.", "examples": [ { "seats": [] } ] } }, "required": [ "object", "previousAttributes" ] }, "EventDto": { "type": "object", "properties": { "type": { "description": "What happened.", "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" } ], "examples": [ "booking.confirmed" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the event happened.", "examples": [ "2026-10-03T12:00:01Z" ] }, "id": { "type": "string", "description": "Event id. Deliveries of the same event share it, so use it to skip duplicates.", "examples": [ "evt_N3wB9k" ] }, "apiVersion": { "type": "string", "description": "API version the payload is shaped by.", "examples": [ "2031-01-01" ] }, "data": { "description": "What changed.", "allOf": [ { "$ref": "#/components/schemas/EventDataDto" } ] } }, "required": [ "type", "createdAt", "id", "apiVersion", "data" ] }, "EventListDto": { "type": "object", "properties": { "data": { "description": "Events on this page, newest first.", "type": "array", "items": { "$ref": "#/components/schemas/EventDto" } }, "page": { "description": "Pagination cursor.", "allOf": [ { "$ref": "#/components/schemas/PageInfoDto" } ] } }, "required": [ "data", "page" ] }, "FareDto": { "type": "object", "properties": { "cabin": { "description": "Cabin.", "allOf": [ { "$ref": "#/components/schemas/CabinClass" } ], "examples": [ "economy" ] }, "amount": { "type": "number", "description": "Price in the smallest currency unit (cents).", "examples": [ 1299900 ] }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "examples": [ "USD" ] }, "seatsLeft": { "type": "number", "description": "Seats left at this fare.", "examples": [ 12 ] } }, "required": [ "cabin", "amount", "currency", "seatsLeft" ] }, "FlightDto": { "type": "object", "properties": { "departsAt": { "type": "string", "format": "date-time", "description": "Departure time (UTC).", "examples": [ "2031-04-12T08:00:00Z" ] }, "id": { "type": "string", "description": "Flight id.", "examples": [ "flt_2031_proxima" ] }, "from": { "type": "string", "description": "Departure spaceport code.", "examples": [ "KSC" ] }, "destinationId": { "type": "string", "description": "Destination id.", "examples": [ "dst_proxima_b" ] }, "durationDays": { "type": "number", "description": "Journey length in days.", "examples": [ 210 ] }, "fares": { "description": "Available fares, cheapest first.", "type": "array", "items": { "$ref": "#/components/schemas/FareDto" } } }, "required": [ "departsAt", "id", "from", "destinationId", "durationDays", "fares" ] }, "FlightListDto": { "type": "object", "properties": { "data": { "description": "Flights on this page.", "type": "array", "items": { "$ref": "#/components/schemas/FlightDto" } }, "page": { "description": "Pagination cursor.", "allOf": [ { "$ref": "#/components/schemas/PageInfoDto" } ] } }, "required": [ "data", "page" ] }, "GrantType": { "type": "string", "enum": [ "client_credentials" ], "description": "Always `client_credentials`." }, "LegacyFlightSearchDto": { "type": "object", "properties": { "results": { "description": "Flights on this page.", "type": "array", "items": { "$ref": "#/components/schemas/FlightDto" } }, "total": { "type": "number", "description": "Flights matching the search, on all pages.", "examples": [ 2 ] }, "page": { "type": "number", "description": "This page number.", "examples": [ 1 ] }, "perPage": { "type": "number", "description": "Flights per page.", "examples": [ 10 ] } }, "required": [ "results", "total", "page", "perPage" ] }, "LoyaltyAccountDto": { "type": "object", "properties": { "tier": { "description": "Current tier, from lifetime points.", "allOf": [ { "$ref": "#/components/schemas/LoyaltyTier" } ], "examples": [ "voyager" ] }, "pointsExpireOn": { "type": [ "string", "null" ], "format": "date", "description": "When the oldest points expire; `null` if none will.", "examples": [ "2028-10-31" ] }, "memberSince": { "type": "string", "format": "date", "description": "When the account was opened.", "examples": [ "2026-03-14" ] }, "id": { "type": "string", "description": "Account id.", "examples": [ "loy_2Hk9Wd" ] }, "memberNumber": { "type": "string", "description": "Orbit Miles member number, printed on boarding passes.", "examples": [ "OT 4410 2291" ] }, "pointsBalance": { "type": "number", "description": "Points you can spend now.", "examples": [ 48250 ] }, "pointsPending": { "type": "number", "description": "Points from flights not yet flown; they become spendable after departure.", "examples": [ 12999 ] }, "lifetimePoints": { "type": "number", "description": "All points ever earned (sets the tier).", "examples": [ 53000 ] }, "tierProgress": { "description": "Distance to the next tier.", "allOf": [ { "$ref": "#/components/schemas/TierProgressDto" } ] } }, "required": [ "tier", "pointsExpireOn", "memberSince", "id", "memberNumber", "pointsBalance", "pointsPending", "lifetimePoints", "tierProgress" ] }, "LoyaltyTier": { "type": "string", "enum": [ "explorer", "voyager", "pioneer", "admiral" ], "description": "Current tier, from lifetime points." }, "LoyaltyTransactionDto": { "type": "object", "properties": { "type": { "description": "What moved the balance.", "allOf": [ { "$ref": "#/components/schemas/LoyaltyTransactionType" } ], "examples": [ "earn" ] }, "bookingId": { "type": [ "string", "null" ], "description": "Booking it relates to, or `null`.", "examples": [ "bk_7Hq2xP" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When it happened.", "examples": [ "2026-10-03T12:01:00Z" ] }, "id": { "type": "string", "description": "Transaction id.", "examples": [ "ltx_9mWq2D" ] }, "points": { "type": "number", "description": "Points added (positive) or taken (negative).", "examples": [ 12999 ] }, "balanceAfter": { "type": "number", "description": "Balance right after this transaction.", "examples": [ 48250 ] }, "description": { "type": "string", "description": "What it was for.", "examples": [ "Flight flt_2031_proxima, economy" ] } }, "required": [ "type", "bookingId", "createdAt", "id", "points", "balanceAfter", "description" ] }, "LoyaltyTransactionListDto": { "type": "object", "properties": { "data": { "description": "Transactions on this page, newest first.", "type": "array", "items": { "$ref": "#/components/schemas/LoyaltyTransactionDto" } }, "page": { "description": "Pagination cursor.", "allOf": [ { "$ref": "#/components/schemas/PageInfoDto" } ] } }, "required": [ "data", "page" ] }, "LoyaltyTransactionType": { "type": "string", "enum": [ "earn", "redeem", "expire", "adjust" ] }, "MealPreference": { "type": "string", "enum": [ "standard", "vegetarian", "vegan", "halal", "kosher", "none" ], "description": "Meal served on board." }, "OAuthErrorCode": { "type": "string", "enum": [ "invalid_request", "invalid_client", "invalid_scope", "unsupported_grant_type" ], "description": "Machine-readable error code." }, "OAuthErrorDto": { "type": "object", "properties": { "error": { "description": "Machine-readable error code.", "allOf": [ { "$ref": "#/components/schemas/OAuthErrorCode" } ], "examples": [ "invalid_client" ] }, "error_description": { "type": "string", "description": "What went wrong, for people.", "examples": [ "Unknown client or wrong secret." ] } }, "required": [ "error", "error_description" ] }, "PageInfoDto": { "type": "object", "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page; `null` on the last page.", "examples": [ "eyJpZCI6ImJrXzIwIn0" ] }, "hasMore": { "type": "boolean", "description": "Whether more items follow.", "examples": [ true ] } }, "required": [ "nextCursor", "hasMore" ] }, "PassengerDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name as on the travel document.", "examples": [ "Ada Lovelace" ] }, "email": { "type": "string", "description": "Contact email for boarding updates.", "format": "email", "examples": [ "ada@example.com" ] } }, "required": [ "name", "email" ] }, "PassengerListDto": { "type": "object", "properties": { "data": { "description": "Passengers on this page, newest first.", "type": "array", "items": { "$ref": "#/components/schemas/PassengerProfileDto" } }, "page": { "description": "Pagination cursor.", "allOf": [ { "$ref": "#/components/schemas/PageInfoDto" } ] } }, "required": [ "data", "page" ] }, "PassengerProfileDto": { "type": "object", "properties": { "dateOfBirth": { "type": "string", "format": "date", "description": "Date of birth.", "examples": [ "1990-12-10" ] }, "passport": { "description": "Passport details; `null` when not on file yet.", "type": [ "object", "null" ], "allOf": [ { "$ref": "#/components/schemas/PassportDto" } ] }, "loyaltyNumber": { "type": [ "string", "null" ], "description": "Orbit Miles member number, or `null`.", "examples": [ "OT 4410 2291" ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Up to 20 key-value pairs of your own. Values are strings; send an empty string to remove a key.", "examples": [ { "crmId": "cus_10442", "segment": "frequent-flyer" } ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the passenger was saved.", "examples": [ "2026-10-03T12:00:00Z" ] }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the passenger last changed.", "examples": [ "2026-10-04T08:15:00Z" ] }, "id": { "type": "string", "description": "Passenger id.", "examples": [ "psg_8Fk2Lm" ] }, "firstName": { "type": "string", "description": "Given name as on the passport.", "examples": [ "Ada" ] }, "lastName": { "type": "string", "description": "Family name as on the passport.", "examples": [ "Lovelace" ] }, "email": { "type": "string", "description": "Contact email.", "examples": [ "ada@example.com" ] }, "nationality": { "type": "string", "description": "Nationality, ISO 3166-1 alpha-2.", "examples": [ "GB" ] }, "preferences": { "description": "Seat and meal preferences.", "allOf": [ { "$ref": "#/components/schemas/TravelPreferencesDto" } ] } }, "required": [ "dateOfBirth", "passport", "loyaltyNumber", "metadata", "createdAt", "updatedAt", "id", "firstName", "lastName", "email", "nationality", "preferences" ] }, "PassportDto": { "type": "object", "properties": { "expiresOn": { "type": "string", "format": "date", "description": "Expiry date. Must be valid six months after departure.", "examples": [ "2034-06-30" ] }, "number": { "type": "string", "description": "Passport number.", "examples": [ "X49201837" ] }, "issuingCountry": { "type": "string", "description": "Issuing country, ISO 3166-1 alpha-2.", "pattern": "^[A-Z]{2}$", "examples": [ "GB" ] } }, "required": [ "expiresOn", "number", "issuingCountry" ] }, "PaymentDto": { "type": "object", "properties": { "status": { "description": "Where the payment is in its life.", "allOf": [ { "$ref": "#/components/schemas/PaymentStatus" } ], "examples": [ "succeeded" ] }, "failureCode": { "type": [ "string", "null" ], "description": "Machine-readable reason when `status` is `failed`, otherwise `null`.", "examples": [ "card_declined" ] }, "failureMessage": { "type": [ "string", "null" ], "description": "Reason for people when `status` is `failed`, otherwise `null`.", "examples": [ "The card was declined." ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Up to 20 key-value pairs of your own, returned on the payment and in its webhooks.", "examples": [ { "orderId": "order-8812", "channel": "web" } ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the payment was created.", "examples": [ "2026-10-03T12:01:00Z" ] }, "id": { "type": "string", "description": "Payment id.", "examples": [ "pay_3kTq9Z" ] }, "bookingId": { "type": "string", "description": "Booking paid for.", "examples": [ "bk_7Hq2xP" ] }, "amount": { "type": "number", "description": "Amount charged, in cents (the booking total).", "examples": [ 1299900 ] }, "amountRefunded": { "type": "number", "description": "Amount refunded so far, in cents.", "examples": [ 0 ] }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "examples": [ "USD" ] }, "method": { "description": "How the customer paid.", "allOf": [ { "$ref": "#/components/schemas/PaymentMethodDetailsDto" } ] }, "refunds": { "description": "Refunds of this payment, oldest first.", "type": "array", "items": { "$ref": "#/components/schemas/RefundDto" } } }, "required": [ "status", "failureCode", "failureMessage", "metadata", "createdAt", "id", "bookingId", "amount", "amountRefunded", "currency", "method", "refunds" ] }, "PaymentMethodDetailsDto": { "type": "object", "properties": { "type": { "description": "How the payment was made. Exactly one of the objects below is set.", "allOf": [ { "$ref": "#/components/schemas/PaymentMethodType" } ], "examples": [ "card" ] }, "card": { "description": "Card details when `type` is `card`, otherwise `null`.", "type": [ "object", "null" ], "allOf": [ { "$ref": "#/components/schemas/CardDetailsDto" } ] }, "wallet": { "example": null, "description": "Wallet when `type` is `wallet`, otherwise `null`.", "anyOf": [ { "$ref": "#/components/schemas/WalletType" }, { "type": "null" } ] }, "bankTransfer": { "description": "Where to send the money when `type` is `bank_transfer`, otherwise `null`.", "type": [ "object", "null" ], "allOf": [ { "$ref": "#/components/schemas/BankTransferInstructionsDto" } ] } }, "required": [ "type", "card", "wallet", "bankTransfer" ] }, "PaymentMethodType": { "type": "string", "enum": [ "card", "wallet", "bank_transfer" ], "description": "How the payment was made. Exactly one of the objects below is set." }, "PaymentStatus": { "type": "string", "enum": [ "pending", "succeeded", "failed", "partially_refunded", "refunded" ], "description": "Where the payment is in its life." }, "RedemptionDto": { "type": "object", "properties": { "reward": { "description": "Reward bought.", "allOf": [ { "$ref": "#/components/schemas/RewardType" } ], "examples": [ "lounge_access" ] }, "bookingId": { "type": [ "string", "null" ], "description": "Booking the reward applies to, or `null`.", "examples": [ "bk_7Hq2xP" ] }, "status": { "description": "Redemptions complete immediately.", "allOf": [ { "$ref": "#/components/schemas/RedemptionStatus" } ], "examples": [ "completed" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the points were spent.", "examples": [ "2026-10-04T09:30:00Z" ] }, "id": { "type": "string", "description": "Redemption id.", "examples": [ "rdm_4TzQ1n" ] }, "points": { "type": "number", "description": "Points spent.", "examples": [ 5000 ] }, "transactionId": { "type": "string", "description": "Loyalty transaction that took the points.", "examples": [ "ltx_5RbX0c" ] } }, "required": [ "reward", "bookingId", "status", "createdAt", "id", "points", "transactionId" ] }, "RedemptionStatus": { "type": "string", "enum": [ "completed" ], "description": "Redemptions complete immediately." }, "RefundDto": { "type": "object", "properties": { "reason": { "description": "Why the money went back.", "allOf": [ { "$ref": "#/components/schemas/RefundReason" } ], "examples": [ "requested_by_customer" ] }, "status": { "description": "Bank transfer refunds stay `pending` for a few days.", "allOf": [ { "$ref": "#/components/schemas/RefundStatus" } ], "examples": [ "succeeded" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the refund was created.", "examples": [ "2026-10-05T10:00:00Z" ] }, "id": { "type": "string", "description": "Refund id.", "examples": [ "re_c81Hq0" ] }, "paymentId": { "type": "string", "description": "Payment refunded.", "examples": [ "pay_3kTq9Z" ] }, "amount": { "type": "number", "description": "Amount refunded, in cents.", "examples": [ 1299900 ] }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "examples": [ "USD" ] } }, "required": [ "reason", "status", "createdAt", "id", "paymentId", "amount", "currency" ] }, "RefundReason": { "type": "string", "enum": [ "requested_by_customer", "duplicate", "flight_cancelled" ], "description": "Why the money went back." }, "RefundStatus": { "type": "string", "enum": [ "pending", "succeeded" ], "description": "Bank transfer refunds stay `pending` for a few days." }, "RewardType": { "type": "string", "enum": [ "cabin_upgrade", "lounge_access", "extra_baggage", "booking_credit" ], "description": "Reward to buy. Costs: `cabin_upgrade` 40,000, `booking_credit` 10,000 ($100 off), `extra_baggage` 8,000, `lounge_access` 5,000." }, "SeatDto": { "type": "object", "properties": { "status": { "description": "Whether the seat can be held.", "allOf": [ { "$ref": "#/components/schemas/SeatStatus" } ], "examples": [ "available" ] }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/SeatFeature" }, "description": "What makes this seat different.", "examples": [ [ "window", "extra_legroom" ] ] }, "price": { "description": "Extra charge for this seat; `null` when it is included in the fare.", "type": [ "object", "null" ], "allOf": [ { "$ref": "#/components/schemas/SeatPriceDto" } ] }, "number": { "type": "string", "description": "Seat number: row and column.", "examples": [ "24A" ] }, "column": { "type": "string", "description": "Column letter.", "examples": [ "A" ] } }, "required": [ "status", "features", "price", "number", "column" ] }, "SeatFeature": { "type": "string", "enum": [ "window", "aisle", "extra_legroom", "exit_row", "viewport" ], "description": "What makes this seat different." }, "SeatHoldDto": { "type": "object", "properties": { "cabin": { "description": "Cabin of the held seats.", "allOf": [ { "$ref": "#/components/schemas/CabinClass" } ], "examples": [ "economy" ] }, "status": { "description": "Active until it is used on a booking or expires.", "allOf": [ { "$ref": "#/components/schemas/SeatHoldStatus" } ], "examples": [ "active" ] }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the seats are released if the hold is not used.", "examples": [ "2026-10-04T09:15:00Z" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "When the hold was created.", "examples": [ "2026-10-04T09:00:00Z" ] }, "id": { "type": "string", "description": "Hold id. Pass it as `holdId` to Update a booking.", "examples": [ "sh_Lq83Zt" ] }, "flightId": { "type": "string", "description": "Flight id.", "examples": [ "flt_2031_proxima" ] }, "seats": { "description": "Seats held.", "type": "array", "items": { "type": "string" }, "examples": [ [ "24A", "24B" ] ] } }, "required": [ "cabin", "status", "expiresAt", "createdAt", "id", "flightId", "seats" ] }, "SeatHoldStatus": { "type": "string", "enum": [ "active", "used", "expired" ], "description": "Active until it is used on a booking or expires." }, "SeatMapDto": { "type": "object", "properties": { "flightId": { "type": "string", "description": "Flight id.", "examples": [ "flt_2031_proxima" ] }, "vessel": { "type": "string", "description": "Vessel type.", "examples": [ "Orbit Clipper OC-9" ] }, "holdDurationSeconds": { "type": "number", "description": "How long a seat hold lasts, in seconds.", "examples": [ 900 ] }, "cabins": { "description": "One map per cabin the flight sells.", "type": "array", "items": { "$ref": "#/components/schemas/CabinSeatMapDto" } } }, "required": [ "flightId", "vessel", "holdDurationSeconds", "cabins" ] }, "SeatPreference": { "type": "string", "enum": [ "window", "aisle", "no_preference" ], "description": "Preferred seat, used when seats are auto-assigned." }, "SeatPriceDto": { "type": "object", "properties": { "amount": { "type": "number", "description": "Extra charge in cents.", "examples": [ 4900 ] }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "examples": [ "USD" ] } }, "required": [ "amount", "currency" ] }, "SeatRowDto": { "type": "object", "properties": { "number": { "type": "number", "description": "Row number.", "examples": [ 24 ] }, "seats": { "description": "Seats in the row, left to right.", "type": "array", "items": { "$ref": "#/components/schemas/SeatDto" } } }, "required": [ "number", "seats" ] }, "SeatStatus": { "type": "string", "enum": [ "available", "held", "occupied", "blocked" ], "description": "Whether the seat can be held." }, "TestWebhookEndpointDto": { "type": "object", "properties": { "type": { "default": "booking.confirmed", "description": "Event type to send, with sample data.", "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" } ] } } }, "TierProgressDto": { "type": "object", "properties": { "nextTier": { "example": "pioneer", "description": "Next tier up; `null` at Admiral.", "anyOf": [ { "$ref": "#/components/schemas/LoyaltyTier" }, { "type": "null" } ] }, "pointsToNextTier": { "type": [ "number", "null" ], "description": "Lifetime points still needed for the next tier; `null` at Admiral.", "examples": [ 22000 ] }, "percent": { "type": "number", "description": "Progress from this tier to the next, 0–100.", "examples": [ 56 ] } }, "required": [ "nextTier", "pointsToNextTier", "percent" ] }, "TokenRequestDto": { "type": "object", "properties": { "grant_type": { "description": "Always `client_credentials`.", "allOf": [ { "$ref": "#/components/schemas/GrantType" } ], "examples": [ "client_credentials" ] }, "client_secret": { "type": "string", "format": "password", "description": "Your OAuth client secret. The sample server accepts `ocs_test_5e8d2a7c9b1f`.", "examples": [ "ocs_test_5e8d2a7c9b1f" ] }, "client_id": { "type": "string", "description": "Your OAuth client id. The sample server accepts `oc_test_orbit_demo`.", "examples": [ "oc_test_orbit_demo" ] }, "scope": { "type": "string", "description": "Space-separated scopes. Omit for every scope the client may use.", "examples": [ "bookings:read bookings:write" ] } }, "required": [ "grant_type", "client_secret", "client_id" ] }, "TokenResponseDto": { "type": "object", "properties": { "token_type": { "enum": [ "Bearer" ], "type": "string", "description": "Token type.", "examples": [ "Bearer" ] }, "access_token": { "type": "string", "description": "Send it as `Authorization: Bearer `.", "examples": [ "oat_test_Q2xpZW50Q3JlZGVudGlhbHM" ] }, "expires_in": { "type": "number", "description": "Seconds until the token expires. Request a new one before then.", "examples": [ 3600 ] }, "scope": { "type": "string", "description": "Scopes granted, space-separated.", "examples": [ "bookings:read bookings:write" ] } }, "required": [ "token_type", "access_token", "expires_in", "scope" ] }, "TravelDocumentDto": { "type": "object", "properties": { "kind": { "description": "What the document is, detected from the scan.", "allOf": [ { "$ref": "#/components/schemas/DocumentKind" } ], "examples": [ "passport" ] }, "contentType": { "type": "string", "enum": [ "application/pdf", "image/png", "image/jpeg" ], "description": "Media type of the file.", "examples": [ "application/pdf" ] }, "status": { "description": "Review status. Boarding needs a verified passport.", "allOf": [ { "$ref": "#/components/schemas/DocumentStatus" } ], "examples": [ "verified" ] }, "rejectionReason": { "type": [ "string", "null" ], "description": "Why the document was rejected; `null` unless `status` is `rejected`.", "examples": [ "The photo page is blurred." ] }, "uploadedAt": { "type": "string", "format": "date-time", "description": "When the document was uploaded.", "examples": [ "2026-10-03T12:05:00Z" ] }, "id": { "type": "string", "description": "Document id.", "examples": [ "doc_Pz71aQ" ] }, "fileName": { "type": "string", "description": "File name as uploaded.", "examples": [ "passport-ada.pdf" ] }, "sizeBytes": { "type": "number", "description": "File size in bytes.", "examples": [ 482113 ] } }, "required": [ "kind", "contentType", "status", "rejectionReason", "uploadedAt", "id", "fileName", "sizeBytes" ] }, "TravelDocumentListDto": { "type": "object", "properties": { "data": { "description": "Documents on the booking, oldest first.", "type": "array", "items": { "$ref": "#/components/schemas/TravelDocumentDto" } } }, "required": [ "data" ] }, "TravelPreferencesDto": { "type": "object", "properties": { "seat": { "description": "Preferred seat, used when seats are auto-assigned.", "allOf": [ { "$ref": "#/components/schemas/SeatPreference" } ], "examples": [ "window" ] }, "meal": { "description": "Meal served on board.", "allOf": [ { "$ref": "#/components/schemas/MealPreference" } ], "examples": [ "vegetarian" ] }, "cryosleep": { "type": "boolean", "description": "Prefers a cryosleep pod on journeys longer than a year." } }, "required": [ "seat", "meal", "cryosleep" ] }, "UpdateBookingDto": { "type": "object", "properties": { "reference": { "type": [ "string", "null" ], "description": "Your reference; `null` removes it.", "examples": [ "order-8812-b" ] }, "passengers": { "description": "Corrected passenger details, same number and order as on the booking. To add or remove passengers, cancel and book again.", "minItems": 1, "maxItems": 9, "type": "array", "items": { "$ref": "#/components/schemas/PassengerDto" } }, "seats": { "description": "Seat numbers, one per passenger in the same order. Each must be free,\nheld by `holdId`, or already on this booking.", "minItems": 1, "type": "array", "items": { "type": "string", "pattern": "^\\d{1,2}[A-F]$" }, "examples": [ [ "24A", "24B" ] ] }, "holdId": { "type": "string", "description": "Seat hold whose seats you are assigning; it is used up.", "examples": [ "sh_Lq83Zt" ] } } }, "UpdatePassengerDto": { "type": "object", "properties": { "dateOfBirth": { "type": "string", "format": "date", "description": "Date of birth.", "examples": [ "1990-12-10" ] }, "passport": { "description": "Passport details; `null` when not on file yet.", "type": [ "object", "null" ], "allOf": [ { "$ref": "#/components/schemas/PassportDto" } ] }, "loyaltyNumber": { "type": [ "string", "null" ], "description": "Orbit Miles member number, if any.", "examples": [ "OT 4410 2291" ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Up to 20 key-value pairs of your own. Values are strings; send an empty string to remove a key.", "examples": [ { "crmId": "cus_10442", "segment": "frequent-flyer" } ] }, "firstName": { "type": "string", "description": "Given name as on the passport.", "examples": [ "Ada" ] }, "lastName": { "type": "string", "description": "Family name as on the passport.", "examples": [ "Lovelace" ] }, "email": { "type": "string", "description": "Contact email; unique per account.", "format": "email", "examples": [ "ada@example.com" ] }, "nationality": { "type": "string", "description": "Nationality, ISO 3166-1 alpha-2.", "pattern": "^[A-Z]{2}$", "examples": [ "GB" ] }, "preferences": { "description": "Preferences to change; the ones you leave out keep their value.", "allOf": [ { "$ref": "#/components/schemas/UpdateTravelPreferencesDto" } ] } } }, "UpdateTravelPreferencesDto": { "type": "object", "properties": { "seat": { "description": "Preferred seat, used when seats are auto-assigned.", "allOf": [ { "$ref": "#/components/schemas/SeatPreference" } ], "examples": [ "window" ] }, "meal": { "description": "Meal served on board.", "allOf": [ { "$ref": "#/components/schemas/MealPreference" } ], "examples": [ "vegetarian" ] }, "cryosleep": { "type": "boolean", "description": "Prefers a cryosleep pod on journeys longer than a year." } } }, "UploadDocumentDto": { "type": "object", "properties": { "file": { "contentMediaType": "application/octet-stream", "description": "Passport or visa scan (PDF, PNG or JPEG, up to 10 MB)." } }, "required": [ "file" ] }, "WalletPaymentRequestDto": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Up to 20 key-value pairs of your own, returned on the payment and in its webhooks.", "examples": [ { "orderId": "order-8812", "channel": "web" } ] }, "type": { "type": "string", "enum": [ "wallet" ], "description": "Pay with a digital wallet.", "examples": [ "wallet" ] }, "wallet": { "description": "Wallet the token comes from.", "allOf": [ { "$ref": "#/components/schemas/WalletType" } ], "examples": [ "apple_pay" ] }, "token": { "type": "string", "description": "Payment token from the wallet's sheet.", "examples": [ "wlt_applepay_8b21f0" ] } }, "required": [ "type", "wallet", "token" ] }, "WalletType": { "type": "string", "enum": [ "apple_pay", "google_pay" ], "description": "Wallet the token comes from." }, "WebhookDeliveryDto": { "type": "object", "properties": { "status": { "description": "`succeeded` when your endpoint answered with a 2xx status.", "allOf": [ { "$ref": "#/components/schemas/WebhookDeliveryStatus" } ], "examples": [ "succeeded" ] }, "responseStatus": { "type": [ "number", "null" ], "description": "HTTP status your endpoint answered with; `null` if it could not be reached.", "examples": [ 200 ] }, "error": { "type": [ "string", "null" ], "description": "Why the delivery failed; `null` when it succeeded.", "examples": [ "connect ECONNREFUSED" ] }, "deliveredAt": { "type": "string", "format": "date-time", "description": "When the delivery was attempted.", "examples": [ "2026-10-04T09:00:00Z" ] }, "id": { "type": "string", "description": "Delivery id.", "examples": [ "whd_s0Ue4M" ] }, "endpointId": { "type": "string", "description": "Endpoint the event was sent to.", "examples": [ "whe_91ka2" ] }, "durationMs": { "type": "number", "description": "Round trip, in milliseconds.", "examples": [ 182 ] }, "signature": { "type": "string", "description": "`Orbit-Signature` header sent: hex HMAC-SHA256 of the body with the endpoint secret.", "examples": [ "5d41402abc4b2a76b9719d911017c592ae2f7c1d6a3e8f2b0c4d5e6f7a8b9c0d" ] }, "event": { "description": "The event that was sent, exactly as your endpoint received it.", "allOf": [ { "$ref": "#/components/schemas/EventDto" } ] } }, "required": [ "status", "responseStatus", "error", "deliveredAt", "id", "endpointId", "durationMs", "signature", "event" ] }, "WebhookDeliveryStatus": { "type": "string", "enum": [ "succeeded", "failed" ], "description": "`succeeded` when your endpoint answered with a 2xx status." }, "WebhookEndpointDto": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" }, "description": "Events sent.", "examples": [ [ "booking.confirmed" ] ] }, "id": { "type": "string", "description": "Endpoint id.", "examples": [ "whe_91ka2" ] }, "url": { "type": "string", "description": "Receiving URL.", "examples": [ "https://example.com/webhooks/orbit" ] }, "secret": { "type": "string", "description": "Secret used to sign deliveries (`Orbit-Signature` header, HMAC-SHA256). Shown once.", "examples": [ "whsec_3b1f9e0c" ] } }, "required": [ "events", "id", "url", "secret" ] }, "WebhookEndpointListDto": { "type": "object", "properties": { "data": { "description": "Your endpoints.", "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointDto" } } }, "required": [ "data" ] }, "WebhookEvent": { "type": "string", "enum": [ "booking.confirmed", "booking.changed", "booking.cancelled", "payment.succeeded", "payment.failed" ] } } } }