Skip to content
BuildBase
HTTP API menu

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...UseWhy
Building a JavaScript or TypeScript appThe SDKHooks, 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 PostmanThe HTTP API, with the OpenAPI fileImport the spec and pick an operation
Using an AI assistant to manage your organizationThe console MCP serverThe agent signs in as you and calls BuildBase for you
Changing settings by handThe console, https://console.buildbase.appNo code at all

The two API families

FamilyPathsWho calls itSigned in as
App API/api/v1/public/*, /api/v1/auth/*, /.well-known/*Your app, for one of its signed-in usersAn 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 jobAn 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

GuideAnswers
Make your first API callGet a key in the console, call the API with curl, Postman and the SDK
Authenticate API requestsSessions, OAuth 2.0, organization API keys, lifetimes and revoking
Base URLs, environments and CORSWhich address to call, for the cloud, a self-hosted server and each environment
HTTP API errorsResponse bodies, statuses, the code field, and when a retry is safe
Pagination and filteringpage, limit and the filters a list takes
Rate limitsHow many requests, the headers that say so, what to do on a 429
Idempotent requestsWhich writes take an Idempotency-Key, and retrying them safely
Versioning and changesWhat BuildBase promises not to break, and where changes are announced
The OpenAPI specDownload the spec and read its x-* fields
Use the API with AIMCP 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