# 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](https://docs.buildbase.app)`/openapi/public-v1.json` |
| Any BuildBase server              | `GET <base URL>/api/v1/openapi.json`                                                                                               |

```bash
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](/http-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](/reference/api-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:

| 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](/http-api/authentication#which-credential-each-route-takes) |
| `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](/http-api/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:

```json
{
  "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.

```bash
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](/http-api/first-call#4-or-call-it-with-postman) |
| 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](/http-api/use-with-ai)                                               |

```bash
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](/quick-start/installation).

## Next steps

- [Use the API with AI](/http-api/use-with-ai) - the spec in GPT Actions, tool use and MCP.
- [Versioning and changes](/http-api/versioning-and-changes) - what can change in the spec.
- [Authenticate API requests](/http-api/authentication) - the credential behind each `x-auth`.
