Skip to content
BuildBase
HTTP API menu

The OpenAPI spec

Download the BuildBase OpenAPI 3.1 document from the docs or your own server, and read its x-auth, x-permission, x-rateLimit and x-source fields.

In short

The OpenAPI spec is one file that describes every operation of the API: its address, what it needs and what can go wrong. Tools read it, so you do not have to type requests by hand. Postman turns it into a collection, code generators turn it into a client library in your language, and AI assistants turn it into actions they can take.

Download it

FromURL
The docs site (BuildBase's cloud)https://docs.buildbase.app/openapi/public-v1.json
Any BuildBase serverGET <base URL>/api/v1/openapi.json
curl -s "https://api.console.buildbase.app/api/v1/openapi.json" -o buildbase-public-v1.json

A self-hosted server serves its own copy with its own URL as the first entry in servers, so a client generated from it calls that server. The document is OpenAPI 3.1 and covers the app API: /api/v1/public, /api/v1/auth, beta sign-up, the monday.com integration and the OAuth discovery documents. The organization API's document follows with its reference.

The API reference is generated from this same document: one page per operation, with its sign-in, fields, answers, errors and samples in cURL, TypeScript and Python.

How it is made

The spec is generated from the running router, not written by hand: every method and path the server answers, the request schemas it validates, and the credential, permission and rate-limit checks in front of each route. A route that changes without its spec fails CI. Two things to know:

  • Response bodies are not described yet. Each operation lists the refusals its checks send (400, 401, 404, 429) and a default answer; the success body is on its way. Until then, the guides and the SDK reference show the shapes.
  • Types are a little narrower than what is accepted. The server converts "1" to 1 and cleans strings before validation.

The x- fields

Every operation carries fields that OpenAPI itself has no name for:

FieldExampleMeans
x-auth"session"The credential the route takes: session, sign-in-context, login-token or none-at-router here; org-credential, org-token and company-key on the organization API. See Authenticate API requests
x-permission{ "resources": ["access_controls"], "action": "read" }The grant the caller's role needs. On the organization API; a role without it is refused
x-rateLimit[{ "prefix": "global", "windowMs": 3000, "max": 500, "per": "ip" }]Every limiter in front of the route, outermost first. See Rate limits
x-source"server/src/routes/v1/public/session.ts"The file in the BuildBase source that serves it, for support and self-hosters

An operation as the spec holds it:

{
  "operationId": "session.list",
  "tags": ["Session"],
  "security": [{ "sessionId": [] }],
  "x-auth": "session",
  "x-rateLimit": [
    { "prefix": "global", "windowMs": 3000, "max": 500, "per": "ip" },
    {
      "prefix": "apikey",
      "windowMs": 60000,
      "max": 1000,
      "per": "key",
      "counts": "some"
    }
  ],
  "x-source": "server/src/routes/v1/public/session.ts"
}

operationId is built from the path and the method (workspaces.list, token.exchange.create) and does not change once published, so a generated client's method names stay put. components.securitySchemes names each credential: sessionId is the x-session-id header, orgToken the Bearer <orgId>:<secret> key.

Find the API from its domain

GET <base URL>/.well-known/api-catalog answers an API catalog (RFC 9727): a list of links that points a tool from the server's domain to its OpenAPI document and its documentation, with no address typed by hand.

curl -s "https://api.console.buildbase.app/.well-known/api-catalog"

Use it in tools

ToolHow
Postman, Insomnia, BrunoImport the URL. See Make your first API call
A client in Python, Go, Java, C#...Feed the file to a generator such as openapi-generator
An AI assistantSee Use the API with AI
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.buildbase.app/openapi/public-v1.json \
  -g python -o ./buildbase-client

Generated clients are yours to keep: BuildBase's supported client is the TypeScript SDK.

Next steps