Public API: OpenAPI Specification

AvsB publishes a live, machine-readable OpenAPI 3.1 specification of the public API. The server builds it from the same validation rules it uses to check requests. So the spec, your generated client, and the running API can never drift apart.

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 this public REST API. The published @avsbhq/* packages are a separate thing: they read experiment and flag settings in your app, they do not call these management endpoints. Any OpenAPI Generator can produce a client in your language, straight from the live JSON URL:

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

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

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

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: the required scopes (named permissions on your token that control what it may read or change). A Bearer service token holding every listed scope, or admin:*, satisfies the requirement.
• parameters: path params the public API actually uses, like projectId or metricId. Your org never appears in the path: it always comes from your token. Also lists limit + cursor for paginated lists, Idempotency-Key for idempotent writes, and both conditional-write headers (X-Avsb-If-Match, the recommended one, 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 every error status that operation can actually return. Every operation can answer 400, 401, 403, 404, 429, 500, and 503. A write can also answer 409 or 422. An operation supporting conditional writes can also answer 412.

Versioning the spec

The API is versioned in the URL path (/api/v1), and v1 is the only live version today. The info.version field simply says "v1" too: it is not a release date, because nothing in AvsB tracks when the surface last changed.

Every response, success or error, carries an AvsB-API-Version header stamped with the version that served it (v1 today). You can always tell which contract answered your call this way. Sending that same header on your request is accepted but does nothing: it does not change the response, and its value is never echoed back. A future breaking change would ship under a new path prefix (/api/v2) with a new stamped value, not by reading a version number you send.