BuildBase HTTP API
What the BuildBase HTTP API is, who it is for, how it compares with the SDK, MCP and the console, and where every guide and reference page is.
In short
The BuildBase HTTP API is how a program talks to BuildBase over the web. Your code sends a request to an address such as https://api.console.buildbase.app/api/v1/public/workspaces and BuildBase answers with data in JSON. Everything the SDK and the console do goes through it, so anything you can do there, a program in any language can do too.
You do not need to know how to code to read these guides: each one starts with a plain summary, then gives the technical detail.
Which should I use?
| You are... | Use | Why |
|---|---|---|
| Building a JavaScript or TypeScript app | The SDK | Hooks, components and typed clients that call this API for you |
| Building in another language (Python, Go, PHP, Ruby...) | The HTTP API (these guides) | Plain HTTPS and JSON, from anything that can send a request |
| Wiring BuildBase into Zapier, Make, n8n or Postman | The HTTP API, with the OpenAPI file | Import the spec and pick an operation |
| Using an AI assistant to manage your organization | The console MCP server | The agent signs in as you and calls BuildBase for you |
| Changing settings by hand | The console, https://console.buildbase.app | No code at all |
The two API families
| Family | Paths | Who calls it | Signed in as |
|---|---|---|---|
| App API | /api/v1/public/*, /api/v1/auth/*, /.well-known/* | Your app, for one of its signed-in users | An end user's session (x-session-id), or an agent or third-party app through OAuth 2.0 |
| Organization API | /api/* (blogs, users, emails...), /api/v1/server/* | Your own server, a build step, a CI job | An organization API key, Authorization: Bearer <orgId>:<secret> |
Every app API operation is described in the OpenAPI document, generated from the server's own routes. The organization API's reference arrives later; until then, the admin API lists the routes a key calls most.
A first look
curl -s "https://api.console.buildbase.app/api/v1/public/workspaces" \
-H "x-session-id: $BUILDBASE_SESSION_ID"[
{
"_id": "665f1c2e9b1d4a0012ab34cd",
"name": "Acme"
}
]The answer is the user's workspaces, shown here with two of their fields. Make your first API call walks through getting BUILDBASE_SESSION_ID from the console, step by step.
The guides
| Guide | Answers |
|---|---|
| Make your first API call | Get a key in the console, call the API with curl, Postman and the SDK |
| Authenticate API requests | Sessions, OAuth 2.0, organization API keys, lifetimes and revoking |
| Base URLs, environments and CORS | Which address to call, for the cloud, a self-hosted server and each environment |
| HTTP API errors | Response bodies, statuses, the code field, and when a retry is safe |
| Pagination and filtering | page, limit and the filters a list takes |
| Rate limits | How many requests, the headers that say so, what to do on a 429 |
| Idempotent requests | Which writes take an Idempotency-Key, and retrying them safely |
| Versioning and changes | What BuildBase promises not to break, and where changes are announced |
| The OpenAPI spec | Download the spec and read its x-* fields |
| Use the API with AI | MCP tools, llms.txt, Markdown pages and AI tool imports |
Every operation also has its own reference page in the API reference, generated from the same OpenAPI document: method, path, how it authenticates, its rate limits and the parameters it accepts.
Next steps
- Make your first API call - from nothing to a working request in a few minutes.
- Authenticate API requests - pick the right credential.
- Error codes - every
codethe API and the SDK return.