Skip to main content

OpenAPI Specification

Nexus publishes a public OpenAPI 3.1 specification documenting core API capabilities. The spec is partial (read-first) and explicitly marked as Public Spec (Partial).

Download​

What's included​

The public specification documents:

  • Authentication scheme (bearer JWT)
  • Core read endpoints for Contacts, Orders, Inventory, Messages, Shipping, and Analytics
  • Selected write endpoints that are stable and safe to publish
  • Request and response schemas with synthetic examples
  • Error response formats

What's excluded​

For security reasons, the public spec does not include:

  • Webhook receiver endpoints (these have their own authentication mechanisms)
  • Internal/debug endpoints
  • Service-role-only endpoints
  • Platform admin endpoints
  • Specific Supabase project URLs or keys

Validation​

The OpenAPI spec is validated in CI using Redocly CLI:

npm run openapi:validate

Using the spec​

Import into API clients​

The OpenAPI spec can be imported into tools like:

  • Postman — File → Import → paste the YAML URL
  • Insomnia — Design → Import → OpenAPI
  • curl generator — use openapi-generator to generate curl commands

Generate client SDKs​

Use the OpenAPI Generator to create typed client libraries:

npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./generated-client

Interactive documentation​

When using Docusaurus with the OpenAPI plugin (or Redoc), the spec renders as interactive API documentation with try-it-out capability.