buildBuildable developer documentation
Buildable projects can be reached from your own tools. A script, a build pipeline or an AI assistant signs in with a personal token and works inside your account, under permissions you set and a run budget you choose.
Two ways in, one token for both. The HTTP API is the same interface Studio itself uses. The MCP server exposes that interface to AI clients such as Claude Code over the Model Context Protocol, the open standard those clients use to reach an external service.
Design teams use this to keep a concept in the tools they already work in: read a project's revisions from a script, start a deterministic check from a pipeline, or let an assistant look at a revision and propose a bounded change while your team decides what to adopt.
Quick start
You need a Buildable account. Sign in with Google, or read about Buildable CAD Pro if you are evaluating this for a practice. Tokens act as you, so they reach only what your own account reaches. A guest trial session cannot create tokens.
1. Create a token. In Studio, open the workspace menu, choose Plans & generations, then API & MCP access. Name the token for the place it will live, pick the permissions it needs, set an expiry and a run budget, and copy the secret. It is shown once, in the form bsk_ followed by 64 characters.
2. Connect an assistant. The token screen offers Copy message for Claude: paste that message into Claude Code or the Claude desktop app and Claude runs the setup, then checks the connection. To do it yourself, in Claude Code:
claude mcp add --transport http buildable https://app.buildable.sh/mcp --header "Authorization: Bearer bsk_your_token_here"
Other MCP clients ask for the same three things: HTTP transport, the URL, and an Authorization header carrying Bearer and your token.
3. Or call the API directly.
curl -H "Authorization: Bearer bsk_your_token_here" https://app.buildable.sh/api/projects
Authentication and permissions
Send the token as a bearer credential on every request: Authorization: Bearer bsk_…. There is no OAuth flow, so a client that only supports browser-based authorization cannot connect. When a bearer token is present, browser cookies are ignored, so a token never inherits a signed-in session's wider rights.
Each token carries permissions chosen when it is created, and they cannot be widened afterwards:
| Permission | What it allows | Applies to |
|---|---|---|
| read | List and open projects, revisions, jobs, artifacts, reviews, documents and usage | GET requests |
| write | Create and archive projects, cancel a job | Other writes |
| run | Start a check or a generation | POST /api/jobs and POST /api/renders |
A token also carries a run budget: a lifetime ceiling on how many runs it may start. When it is used up the token still reads and writes, but cannot start further runs. This is what stops a misbehaving script from consuming an account's generation allowance. A start the API rejects does not count against it.
Your account's own limits still apply on top: generation allowances, active and daily job caps, and storage quotas are unchanged by which token was used.
Token management, company administration and invitations are deliberately unreachable with a token. Those stay in Studio, where a person does them. A token can hold at most 90 days by default and 365 at most, up to 20 active tokens per account.
HTTP API reference
Base URL https://app.buildable.sh. Requests and responses are JSON.
| Endpoint | Method | Permission | Returns |
|---|---|---|---|
/api/session |
GET | read | The identity the token acts for, plus the token's own permissions and run count |
/api/projects |
GET | read | Your projects, newest first. ?archived=1 includes archived ones |
/api/projects |
POST | write | Creates a project and its first revision from a name, brief and parameters |
/api/projects/{id} |
GET | read | A project with its immutable revisions and their inputs |
/api/projects/{id}/snapshot |
GET | read | The portable snapshot synced from Studio, including annotations |
/api/projects/{id}/archive, /restore |
POST | write | Archives or restores a project |
/api/jobs |
POST | run | Starts a job. kind is check or generate; send an idempotencyKey so a retry is safe |
/api/jobs?projectId=… |
GET | read | Recent jobs for a project |
/api/jobs/{id} |
GET | read | Job status, artifacts once it succeeds, or the recorded failure reason |
/api/jobs/{id}/events |
GET | read | Progress events as a finite server-sent-event batch |
/api/jobs/{id}/cancel |
POST | write | Cancels a queued or running job |
/api/artifacts/{id} |
GET | read | A succeeded job's JSON artifact |
/api/usage, /api/generations |
GET | read | Usage counters, storage, and the current generation allowance |
/api/documents |
GET | read | Ready private documents, name and size only |
/api/reviews, /api/reviews/{id} |
GET | read | Reviews you own or were invited to, with comments and decisions |
MCP reference
Endpoint https://app.buildable.sh/mcp. The transport is stateless Streamable HTTP: one JSON-RPC message or batch per POST, a JSON reply, 202 for notifications. There is no server-initiated stream and no session identifier, so nothing needs to be kept open between calls. Protocol versions 2025-06-18, 2025-11-25 and 2025-03-26 are accepted; anything else is answered with 2025-06-18. The server advertises tools only.
curl -X POST https://app.buildable.sh/mcp \
-H "Authorization: Bearer bsk_your_token_here" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
| Tool | Permission | What it does |
|---|---|---|
whoami |
— | The identity the token acts for, its permissions and remaining run budget |
preview_frame |
— | Builds the concept frame for given parameters and returns a member summary, ridge height and cut list. Saves nothing |
list_projects |
read | Your projects |
get_project |
read | A project with its revisions and the inputs behind each one |
get_project_snapshot |
read | The portable snapshot synced from Studio |
create_project |
write | Creates a project and its first revision |
archive_project |
write | Archives or restores a project |
start_job |
run | Starts a check or a generation, generating an idempotency key if you omit one |
list_jobs |
read | Recent jobs for a project |
get_job |
read | Status, artifacts or failure reason |
get_job_events |
read | Progress events parsed into JSON |
cancel_job |
write | Cancels a job |
get_job_artifact |
read | A succeeded job's checks, quantities or proposal |
get_usage |
read | Usage counters and generation allowance |
list_documents |
read | Ready private documents |
list_reviews, get_review |
read | Reviews, with comments and decisions |
Two limits are deliberate. An assistant proposes a supported change as typed data, and our own deterministic code builds the geometry; an assistant never executes geometry code of its own. And nothing an assistant reaches is engineered, code-checked or ready for fabrication. Concepts stay concepts.
Errors
A refusal from Buildable always arrives as JSON with an explanation.
| Status | Meaning |
|---|---|
| 401 | The token is missing, malformed, expired or revoked |
| 402 | No generation allowance remains on the account |
| 403 | The token lacks the permission this request needs, or the route is Studio-only |
| 404 | Not found, or not yours |
| 409 | An idempotency key was reused for different inputs, or a project changed elsewhere |
| 429 | The token's run budget is spent, or an account job cap was reached |
Over MCP, a refusal comes back as a tool result marked as an error carrying the same status and message, so an assistant can read it and react. Malformed arguments and unknown tool names are JSON-RPC errors instead.
A 403 with error code: 1010 in the body did not reach Buildable. Our edge protection turned it away first, usually because the client sent no User-Agent or a default one such as Python-urllib/3. Set a User-Agent naming your tool and the request goes through. Command-line curl, Node's fetch and the common MCP clients are unaffected.
Keeping tokens safe
Treat a token like a password: it acts as you. Give each tool its own token, so one can be revoked without disturbing the others. Prefer a short expiry for a laptop and a small run budget for anything experimental. Revoke a token the moment a machine is lost or a contract ends; revocation takes effect immediately.
Buildable stores only a hash of the secret, never the secret itself. A token's permissions, expiry and budget are fixed when it is created.
Not available yet
Uploading and downloading documents, writing review comments and decisions, renders, and company administration cannot be reached with a token. There is no browser-based authorization flow, no webhooks, no per-token rate limit beyond the run budget, and no audit log beyond each token's last-used time.
Explore Buildable ↗