Skip to main content
Get started
DocumentationAPI Overview
API reference

API Overview

This page has been cleared and is ready for updated Builder Studio documentation.

BuilderStudio is automated primarily through its MCP gateway — a single Model Context Protocol endpoint that exposes your workspace as tools for Claude Code, Cursor, Codex, and other MCP clients. Alongside the gateway, a small set of plain HTTP endpoints lets you trigger and read workflow executions, inspect canvases, verify keys, and export billing data without an MCP client.

There is no general-purpose REST CRUD API
BuilderStudio does not ship a broad public REST API that mirrors every dashboard action. The supported programmatic surface is the MCP gateway plus the handful of HTTP endpoints documented in this section. If a capability is not listed in Endpoints, drive it through MCP tools instead.

The three surfaces

  • MCP gateway — POST /api/mcp on the BuilderStudio app. A JSON-RPC Model Context Protocol endpoint. Authenticate with a workspace builder_ API key (or an OAuth 2.1 bearer token) and call the BuilderStudio tool surface: list canvases, author workflows, trigger runs, manage assets, manage keys, and read billing. This is the surface MCP clients connect to.
  • Direct HTTP endpoints — a focused set of routes (/api/run, /api/canvases, /api/executions, /api/verify-key, /api/billing/*, and the MCP tool-backing /api/mcp/* routes) you can call directly with the same builder_ key when you do not want to run an MCP client.
  • Execution & webhooks — workflows are triggered programmatically via /api/run or by inbound webhook triggers, and they can push results back out via callback URLs. See Webhooks.

How requests are authenticated

Every programmatic surface uses bearer authentication with a workspace-scoped builder_ key. The key both identifies the workspace and carries the scopes that gate what each call can do. Read Authentication for the key families and the full scope list.

Authenticated requestbash
curl -H "Authorization: Bearer builder_..." \  https://<your-convex-deployment>.convex.site/api/canvases

MCP gateway at a glance

MCP gatewaytext
Endpoint:  POST /api/mcp        (BuilderStudio app origin)Protocol:  JSON-RPC over HTTP (Model Context Protocol)Auth:      Authorization: Bearer builder_...   (or OAuth 2.1 bearer)Methods:   POST (RPC), GET / DELETE (session transport), OPTIONS (CORS)Scopes:    read:canvases, read:assets, run:workflows, write:canvas,           write:assets, delete:canvas, delete:assets,           manage:integrations, read:billing

For client setup snippets (Claude Code, Cursor, Codex) see Builder MCP & CLI. For published third-party MCP servers and workspace installs, see the Marketplace.

Where to go next

Was this page helpful?