Guides · API Reference

Public REST API

Everything Norba exposes to travel agencies. JSON-over-HTTPS.

Work in Progress

The Norba API is actively under development. New endpoints, data sources, and features are being added daily. Please report any discrepancies or issues you encounter at hello@norba.io. We appreciate your patience as we build this platform.

Base URL

api.norba.io

Version

Protocol

HTTPS / JSON

Conventions

Base path/v1/
AuthAuthorization: Bearer <api-key> on every authenticated endpoint.
TimesRFC 3339 UTC — 2026-06-15T10:00:00Z
Money{ "amount": 542.10, "currency": "GBP" } — ISO 4217 currency.
IDsULID for internal entities; opaque strings for airline-owned IDs.
Errors{ "error": "<code>", "message": "<human>", "request_id": "<ulid>" }

Public endpoints (no auth)

Method	Path	Description
GET	/v1/health	Liveness probe (DB + Redis ping). Returns 200 with { "status": "ok" }.

Aviation data

Method	Path	Description
GET	/v1/airlines	List supported airlines from refdata.
GET	/v1/airports?q=lond	Airport autocomplete (refdata).

Shopping

Method	Path	Description
POST	/v1/shopping/offers	Search for flights. Returns ranked offers from all connected airlines.
POST	/v1/shopping/offers/price	Price-lock a specific offer (valid 5–15 min).
POST	/v1/shopping/services	Ancillary catalogue — bags, meals, lounges.
POST	/v1/shopping/seats	Seat map for a specific segment.

SearchRequest body

JSON·search-request.json

{
  "origin":         "MAD",
  "destination":    "LHR",
  "departure_date": "2026-06-15",
  "return_date":    "2026-06-22",
  "passengers":     [
    { "type": "ADT", "count": 2 },
    { "type": "CHD", "count": 1 }
  ],
  "cabin_class":    "economy",
  "currency":       "GBP",
  "airlines":       ["BA", "IB"]
}

Orders

Method	Path	Description
POST	/v1/orders	Create from a priced offer + passengers (+ optional payment).
GET	/v1/orders/{id}	Retrieve current state.
POST	/v1/orders/{id}/pay	Submit payment to ticket a pending order.
POST	/v1/orders/{id}/change	Voluntary change of itinerary or passenger data.
POST	/v1/orders/{id}/reshop	Get alternatives (disruption or voluntary change).
POST	/v1/orders/{id}/refund	Cancel and refund.
DELETE	/v1/orders/{id}	Cancel (no refund).
GET	/v1/orders/{id}/history	Audit trail (order_events).
GET	/v1/orders	List orders by agency, paginated.

Servicing

Method	Path	Description
POST	/v1/orders/{id}/seats	Assign or change seats.
POST	/v1/orders/{id}/ancillaries	Add bags, meals, lounges, or Wi-Fi.
POST	/v1/orders/{id}/ssrs	Add Special Service Requests and APIS data.

Webhooks

Method	Path	Description
GET	/v1/webhooks/subscriptions	List your subscriptions.
POST	/v1/webhooks/subscriptions	Create a subscription.
DELETE	/v1/webhooks/subscriptions/{id}	Remove a subscription.
GET	/v1/webhooks/attempts?subscription_id=…	Delivery log.

Webhook payloads

All events are JSON-over-HTTPS POST with a X-Norba-Signature header (HMAC-SHA256 of the raw body using your webhook secret). Verify this signature before processing any payload.

Error codes

HTTP	Error code	Meaning
400	invalid_request	Missing or malformed field in the request body.
401	unauthorized	Missing or invalid Bearer token.
403	forbidden	Token valid but lacks permission for this resource.
404	not_found	The requested resource does not exist.
409	offer_expired	The OfferID is no longer valid — re-shop and try again.
422	order_validation_failed	Passenger data or payment data failed airline-side validation.
429	rate_limited	You have exceeded the rate limit. Retry-After header indicates when to retry.
502	airline_error	The upstream airline returned an error. The request_id is logged for diagnosis.
503	circuit_open	The adapter for this airline is in open-circuit state. Retry after 30 s.