Skip to main content

OpenAPI Specification

Every Nexa API surface publishes a live OpenAPI 3.1 specification. Use it to generate SDKs, drive contract tests, and explore endpoints interactively.

Live specs​

SurfaceSpec URL
Operator APIhttps://na.api.nexastudio.io/openapi/operator/v1.json
Passenger APIhttps://na.api.nexastudio.io/openapi/passenger/v1.json
Partner APIhttps://na.api.nexastudio.io/openapi/partner/v1.json

Specs are generated from the Nexa source code on every deploy and stamped with the build hash. The version-pinned URL form is …/openapi/<surface>/<version>.json (e.g., …/openapi/partner/v1.json is always the latest stable v1).

The interactive explorer (Swagger UI / Stoplight Elements) embedded into this docs site is on the roadmap and will render directly in this section once the specs are pinned to a stable build. Until then, paste the spec URL into your tool of choice (Postman, Insomnia, Stoplight Studio, Bruno) for an immediate explorer.

Generating SDKs​

We recommend openapi-generator or openapi-typescript for client generation. Example for TypeScript:

npx openapi-typescript \
  https://na.api.nexastudio.io/openapi/partner/v1.json \
  -o nexa-partner-api.d.ts

For a fully-typed client with runtime fetch wrappers:

npx openapi-fetch-codegen \
  https://na.api.nexastudio.io/openapi/partner/v1.json \
  --out src/nexa-client/

Other languages:

# Python
openapi-generator-cli generate \
  -i https://na.api.nexastudio.io/openapi/partner/v1.json \
  -g python \
  -o ./nexa-partner-python

# Go
openapi-generator-cli generate \
  -i https://na.api.nexastudio.io/openapi/partner/v1.json \
  -g go \
  -o ./nexa-partner-go

# Java
openapi-generator-cli generate \
  -i https://na.api.nexastudio.io/openapi/partner/v1.json \
  -g java \
  -o ./nexa-partner-java

Contract testing​

Treat the OpenAPI spec as the source of truth for your integration's expectations. Wire it into CI to catch breaking changes early:

  • Schemathesis — property-based contract testing against a running endpoint.
  • Dredd — endpoint-by-endpoint contract validation.
  • Pact — consumer-driven contract testing if you want bidirectional verification.

Nexa publishes a deprecation feed at …/openapi/changelog.json that includes every endpoint addition, removal, and breaking change for the last 12 months. Subscribe to it from your CI to be alerted before a deprecated endpoint sunsets.

Versioning policy​

  • URL-prefix versioning: /v1/*, /v2/*. Breaking changes always bump the version.
  • New optional fields, new endpoints, new event types are non-breaking and added to /v1.
  • Deprecation: 6 months notice with Deprecation and Sunset HTTP headers on every deprecated endpoint's response. The OpenAPI spec marks the endpoint with deprecated: true and a description pointing at the replacement.
  • Removal: 12 months after deprecation. The endpoint returns 410 Gone with a body pointing at the replacement.

Spec extensions​

Nexa's OpenAPI specs use a small set of vendor-specific extensions to communicate platform conventions:

  • x-nexa-scope on each operation — the OAuth scope required (Partner API only).
  • x-nexa-role on each operation — the minimum operator role (Operator API only).
  • x-nexa-rate-limit on each operation — the rate-limit class (read, write, expensive).
  • x-nexa-idempotent on writes — true if the endpoint accepts an Idempotency-Key header.
  • x-nexa-tenant-scope on each operation — tenant (most), cross-tenant (rare; admin-only), passenger-session (passenger surface).

SDK generators that don't understand these extensions safely ignore them. Nexa-aware generators can use them to scaffold rate-limiter middleware, scope enforcement, and idempotency-key plumbing.

Where to next​

Was this helpful?