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
| From | URL |
|---|---|
| The docs site (BuildBase's cloud) | https://docs.buildbase.app/openapi/public-v1.json |
| Any BuildBase server | GET <base URL>/api/v1/openapi.json |
curl -s "https://api.console.buildbase.app/api/v1/openapi.json" -o buildbase-public-v1.jsonA 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 adefaultanswer; 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"to1and cleans strings before validation.
The x- fields
Every operation carries fields that OpenAPI itself has no name for:
| Field | Example | Means |
|---|---|---|
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
| Tool | How |
|---|---|
| Postman, Insomnia, Bruno | Import 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 assistant | See Use the API with AI |
npx @openapitools/openapi-generator-cli generate \
-i https://docs.buildbase.app/openapi/public-v1.json \
-g python -o ./buildbase-clientGenerated clients are yours to keep: BuildBase's supported client is the TypeScript SDK.
Next steps
- Use the API with AI - the spec in GPT Actions, tool use and MCP.
- Versioning and changes - what can change in the spec.
- Authenticate API requests - the credential behind each
x-auth.