REST API - Builder Studio Docs

BuilderStudio exposes a small, purpose-built set of HTTP endpoints rather than a full resource-CRUD REST API. The richest programmatic surface is the MCP gateway; the direct HTTP routes on this page exist for the cases where running an MCP client is overkill — triggering a workflow from a script, polling a run, or pulling billing data.

Set expectations: this is not a generic REST API

There are no POST /api/canvases, PATCH /api/nodes/:id, or similar generic CRUD routes. Canvas authoring, asset management, and workspace administration are done through MCP tools. The HTTP endpoints below are the complete, exhaustive direct surface.

Conventions

Auth: Authorization: Bearer builder_… on every request. See Authentication.
Bodies: JSON in, JSON out. Send Content-Type: application/json on requests with a body.
Host: /api/run, /api/canvases, /api/executions, and /api/verify-keyare served from your deployment's Convex HTTP-actions host (<deployment>.convex.site). The MCP gateway (/api/mcp) and the billing routes (/api/billing/*) are served from the BuilderStudio app origin.
Errors: non-2xx responses carry a JSON { "error": "…" } body. 401 = bad/missing key, 403 = missing scope or workspace, 404 = not found, 409 = idempotency conflict, 429 = rate limited (with Retry-After).

The direct endpoints

Method & path	Purpose	Scope
`POST /api/run`	Trigger a workflow run on a canvas; optionally wait for it (`sync`).	`run:workflows`
`GET /api/canvases`	List the workspace's canvases.	`read:canvases`
`GET /api/executions?executionId=…`	Read the status snapshot of one execution.	`run:workflows`
`GET /api/verify-key`	Confirm a key and return its workspace and scopes.	any (workspace-scoped key required)
`GET /api/billing/focus-export`	Export credit usage as FOCUS JSONL/CSV.	`read:billing`
`GET /api/billing/focus-metadata`	FOCUS dataset metadata for a date range.	`read:billing`

The complete route reference — including the MCP tool-backing /api/mcp/* HTTP routes — lives in Endpoints.

Example: run a workflow

1curl -X POST https://<your-convex-deployment>.convex.site/api/run \2  -H "Authorization: Bearer builder_..." \3  -H "Content-Type: application/json" \4  -d '{5    "canvasId": "<canvasId>",6    "triggerNodeId": "<webhook-or-prompt-trigger-node-clientId>",7    "inputs": { "topic": "launch announcement" },8    "sync": true,9    "timeoutSeconds": 3010  }'

Without sync, the call returns 202 with an executionId you poll via GET /api/executions?executionId=…. With sync: true, it waits up to timeoutSeconds (1–55s) for the run to finish and returns the terminal snapshot, or a pending payload if it is still running.

Idempotency

POST /api/run honors an Idempotency-Key header (or an idempotencyKey body field). Replaying the same key with the same body returns the original result with an X-Idempotent-Replay: true header; reusing a key with a different body returns 409. If you omit a key, BuilderStudio derives a deterministic one from the canvas, trigger node, inputs, and callback URL.

Need more than this?

For canvas authoring, asset uploads, integration credentials, templates, and workspace administration, use the MCP tools through the gateway. The Builder MCP & CLI section covers connecting a client.

Was this page helpful?