Skip to content
Vaultbase

OpenAPI spec

An OpenAPI 3.1 description of your records API, generated from the live schema.

GET /api/v1/openapi.json

Vaultbase describes its client-facing API as OpenAPI 3.1, generated from your collections at request time, so it always matches the current schema. It covers:

  • records: list (with filter, sort, expand, search), get, create, update, delete and aggregate, with a typed schema per collection (Posts, PostsInput, …);
  • singleton collections: GET and PATCH on the collection path (/api/v1/<name>), with If-Match on the PATCH, and no list, create or delete;
  • auth collections: register, login, password reset, plus token refresh. Their users are created through register, so there’s no create operation on the collection path;
  • files: download (with thumbnail and format options) and upload.

Admin endpoints are not included.

Access

Section titled “Access”

By default the spec needs an admin token. In the admin, API preview → public spec (setting api.openapi_public) serves it to anyone. Collections whose list, view and create rules are all admin-only are then left out, so their names and fields stay private.

API preview → Export → OpenAPI spec downloads it. The same menu exports a Postman collection, an Insomnia export or a .http file; see The admin. The API preview’s endpoint list is built from this spec too.

Using it

Section titled “Using it”

The server URL in the spec is relative (/), so it resolves against whichever host served it. That works behind a proxy or on a custom domain.

  • Docs UI: load it in Swagger UI, Redoc, Scalar or Postman.
  • Client generation: openapi-generator, openapi-typescript, or any OpenAPI tool can generate a client in Dart, Swift, Kotlin, Python, Go and others.
Terminal window
curl -H "Authorization: Bearer $ADMIN_TOKEN" https://api.example.com/api/v1/openapi.json > openapi.json
npx openapi-typescript openapi.json -o vaultbase.d.ts

For TypeScript, the official SDK with vb-types gives a better typed client.