/Docs

Public API: OpenAPI Specification

AvsB publishes a live, machine-readable OpenAPI 3.1 specification of the public API. The spec is generated at build time from the same validation schemas the server uses to validate requests — so the documentation, your generated client, and the running API cannot drift.

Live endpoints

  • JSON: https://app.avsb.cloud/api/openapi.json
  • YAML: https://app.avsb.cloud/api/openapi.yaml

Both endpoints are unauthenticated and serve the current specification. They are cached for 5 minutes at the browser and 1 hour at the CDN, so a fresh deploy takes at most an hour to propagate.

Postman, Insomnia, Bruno

Import the spec into your favourite API client:

  • Postman: File → Import → Link → paste the JSON URL.
  • Insomnia: Application → Preferences → Data → Import Data → From URL.
  • Bruno: Collection → Import → OpenAPI → URL.

Once imported, set an environment variable for your service token and bind it to the Authorization header.

Generating a client SDK

AvsB does not bundle official SDKs for the public API. Any OpenAPI Generator can produce a client in the language of your choice. For example, to generate a TypeScript client:

bash
1npx @openapitools/openapi-generator-cli generate \
2  -i https://app.avsb.cloud/api/openapi.json \
3  -g typescript-fetch \
4  -o ./avsb-client

For Go:

bash
1openapi-generator-cli generate \
2  -i https://app.avsb.cloud/api/openapi.json \
3  -g go \
4  -o ./avsb-client-go

For Python:

bash
1openapi-generator-cli generate \
2  -i https://app.avsb.cloud/api/openapi.json \
3  -g python \
4  -o ./avsb-client-python

Shape of the document

Each registered endpoint becomes a paths entry with:

  • operationId — stable function name SDK generators key off.
  • summary + tags — human-readable grouping.
  • security — required scope list (a Bearer service token holding every listed scope, or admin:*, satisfies the requirement).
  • parameters — path params (e.g. orgId), plus limit + cursor for paginated lists, Idempotency-Key for idempotent writes, and If-Match for mutable resources.
  • requestBody — for endpoints with a body, the schema maps directly from the server-side Zod validator.
  • responses — the success shape under 200 or 201, plus the standard error responses (401, 403, 404, 429, 500).

Versioning the spec

The info.version field is the date the API surface last had a backwards-compatible change. The API itself uses date-based version pinning via the AvsB-API-Version request header; future breaking changes will branch behind newer dates without breaking clients that pin to the current version.