Public API Reference

Nexa exposes three distinct API surfaces, each tailored to its audience and load shape. They share the same platform behind them but have different authentication, rate limits, and contracts. Pick the one that matches your integration.

Surface	Audience	Auth	Read this if you are
Operator API	Airline operators (ops console)	OIDC JWT, role-based	Building or extending the operations console for an airline's IROPs team.
Passenger API	Passengers (mobile webapp)	Magic-link / PNR-login session tokens	Building a passenger-facing client (PWA, native app, partner check-in flow).
Partner API	B2B integrators	OAuth2 client credentials, scoped	Integrating an external system: airline DCS, corporate travel desk, OTA, regulator.
Webhooks	Inbound from vendors / outbound to partners	HMAC-signed	Receiving Pomelo / Amadeus events, or registering a partner endpoint to receive Nexa events.
Authentication	All surfaces	—	Understanding the identity model end-to-end.

Common conventions

Every Nexa API surface shares a small set of conventions. Follow them once and they apply everywhere.

Base URLs

Nexa is deployed regionally. Pick the region closest to your operations:

Region	Base URL
North America (default)	https://na.api.nexastudio.io
Europe	https://eu.api.nexastudio.io
South America	https://sa.api.nexastudio.io

Multi-region tenants get a single virtual host (https://api.nexastudio.io) that routes to the closest healthy region. Passenger surfaces use per-tenant subdomains: https://<airline>.passengers.nexastudio.io. Partner surfaces use the same hostname as the operator API with /partner/v1/* path versioning.

Versioning

URL prefix versioning: /v1/*. Breaking changes mint a new prefix (/v2/*); the old version is deprecated with 6 months' notice and removed after 12 months. Header-based versioning is not used.

Identifiers (URNs)

Every identifier on the wire is a URN. URNs are URL-encoded in path components:

GET /v1/cases/urn%3Acase%3Ac-7f8e1

URNs carry vendor and status structurally — urn:reservation:r-8842:vendor:amadeus:status:confirmed. See Data Model for the full registry.

Pagination

Cursor-based, opaque cursor token:

GET /v1/cases?limit=50&cursor=eyJzdGFydCI6Mn0%3D

Response:

{
  "items": [ … ],
  "nextCursor": "eyJzdGFydCI6NTJ9",
  "hasMore": true
}

Offset / page-number pagination is not supported. Sort order is fixed per endpoint.

Errors

RFC 7807 Problem Details:

{
  "type": "https://errors.nexastudio.io/conflict/sub-case-locked",
  "title": "Sub-case is locked by another operator",
  "status": 409,
  "detail": "urn:sub-case:sc-91a4 is held by urn:user:auth0|6510abc, expires in 12s",
  "instance": "urn:correlation:abc123…",
  "lockedBy": "urn:user:auth0|6510abc",
  "expiresInSeconds": 12
}

The instance field is the W3C trace correlation URN — paste it into the platform dashboard to follow the full request trace.

Idempotency

Every write endpoint accepts an Idempotency-Key header. Replays with the same key return the same response (and status code) without re-executing the side effect.

For disruption ingest (POST /partner/v1/disruptions), the idempotency key is the airline's externalEventId field; you can omit the header. Replays are deduplicated server-side and return the same caseUrn.

Rate limits

Per-tenant per-route. Defaults:

Surface	Read RPM	Write RPM	Burst
Operator	600	120	1.5×
Passenger	300	30	2×
Partner	per-partner-tier (Tier-1: 1200/240, Tier-2: 600/120, Tier-3: 60/10)	—	—

Responses include X-RateLimit-Remaining and (on 429) Retry-After. Idempotency-keyed retries within the rate-limit window are exempt from quota.

Observability

Every request carries a W3C traceparent header. If you don't supply one, Nexa mints one and returns it in the response. Include it in your client logs and in any support requests — it's the fastest way for support to find the corresponding event chain.

Tenant isolation

A token issued for urn:airline:latam cannot read a case owned by another airline. Cross-tenant reads return 403 Forbidden. Multi-tenant integrations (e.g., a corporate travel desk serving multiple airlines) hold one registration per airline.

OpenAPI

A live OpenAPI 3.1 specification for every surface is published at:

• Operator: https://na.api.nexastudio.io/openapi/operator/v1.json
• Passenger: https://na.api.nexastudio.io/openapi/passenger/v1.json
• Partner: https://na.api.nexastudio.io/openapi/partner/v1.json

See OpenAPI for SDK generation guides and the rendered explorer.

Where to next

• Authentication — token shapes, audiences, refresh, and revocation.
• Operator API — the operator console surface end-to-end.
• Passenger API — magic-link auth and the snapshot read path.
• Partner API — OAuth2 client-credentials, scopes, webhook-out.
• Webhooks — inbound vendor webhooks and outbound partner deliveries.