Skip to Content
IntegrationOpenAPI spec

OpenAPI specification

The machine-readable specification for the complete REST surface. Consumers include Postman, Insomnia, and OpenAPI-aware client generators.

Specification URL

The specification is served alongside the API:

https://api.nebbos.ai/api/v1/openapi.json

The specification reflects the currently deployed version. Version bumps land at the moment the deploy pipeline promotes a build. The specification held by a consumer is never more than one deployment behind production.

The specification covers all 1,652 endpoints under the /api/v1 prefix. Each endpoint carries its full schema, per-tier authentication requirements, error shapes, and response examples derived from platform integration tests.

Postman and Insomnia

Both Postman and Insomnia import OpenAPI 3.x directly. Directing either client at the specification URL produces a request collection matching the current surface, organised by endpoint category.

Bearer tokens are configured at the collection-level authorisation. Tokens should not be pasted into individual requests. Collection-level configuration centralises token management and simplifies rotation.

Client generation

openapi-generator and openapi-typescript-codegen consume the specification and produce typed clients in the target language. This path is recommended for languages not covered by the official SDK programme. Generated clients remain in lockstep with the platform because they derive from the same specification.

openapi-generator-cli generate \ -i https://api.nebbos.ai/api/v1/openapi.json \ -g go \ -o ./nebbos-go

Stability contract

Specification additions (new endpoints, new optional fields) are permitted within a version prefix. Removals and shape changes are shipped as a new version prefix, with the previous version continuing to serve for a minimum of twelve months. Full contract details are in Versioning & changelog.