Endpoints - Builder Studio Docs

This is the reference for the HTTP routes BuilderStudio actually serves. They split into the MCP gateway, the direct programmatic API, the MCP tool-backing routes (which the gateway calls and you can also call directly), and the webhook endpoints. Every route below takes an Authorization: Bearer builder_… key unless noted otherwise.

Hosts

The MCP gateway and billing routes are served from the BuilderStudio app origin. The other routes are Convex HTTP-action routes served from your deployment's <deployment>.convex.site host. Paths are stable; the host depends on your deployment.

MCP gateway

Method & path	Description
`POST /api/mcp`	JSON-RPC Model Context Protocol endpoint. Carries `tools/list`, `tools/call`, and the rest of the MCP protocol.
`GET /api/mcp`, `DELETE /api/mcp`	MCP streamable-HTTP session transport methods.
`OPTIONS /api/mcp`	CORS preflight.

Accepts a builder_ key or an OAuth 2.1 bearer token. Browser-originated requests must come from an allowed BuilderStudio origin. See Builder MCP & CLI for client setup.

Direct programmatic API

Method & path	Description	Scope
`POST /api/run`	Trigger a workflow run on a canvas. Body: `canvasId`, `triggerNodeId`, optional `inputs`, `sync`, `timeoutSeconds`, `callbackUrl`, `idempotencyKey`.	`run:workflows`
`GET /api/canvases`	List canvases in the key's workspace (id, name, workspaceId, updatedAt).	`read:canvases`
`GET /api/executions?executionId=…`	Read one execution's status snapshot.	`run:workflows`
`GET /api/verify-key`	Return the key's resolved `workspaceId` and `scopes`.	workspace-scoped key

Run a workflow

1curl -X POST https://<deployment>.convex.site/api/run \2  -H "Authorization: Bearer builder_..." \3  -H "Content-Type: application/json" \4  -d '{ "canvasId": "<id>", "triggerNodeId": "<nodeClientId>", "inputs": {}, "sync": true }'5 6# 202 (async)  -> { "ok": true, "executionId": "exec_...", "message": "Execution triggered" }7# 200 (sync)   -> terminal execution snapshot8# poll status  -> GET /api/executions?executionId=exec_...

The triggerNodeId must reference a trigger-capable node on the canvas (a prompt or webhook-trigger node); other node types are rejected with 400.

MCP tool-backing routes (`/api/mcp/*`)

These Convex HTTP routes implement the BuilderStudio tools. The MCP gateway calls them, and you can call them directly with a builder_ key. Each enforces a specific scope. The list below is grouped by area; all are workspace-scoped.

Canvas authoring

1GET   /api/mcp/canvas/state            read:canvases   canvas + nodes + edges2GET   /api/mcp/canvas/assets           read:canvases   list canvas assets3GET   /api/mcp/canvas/executions       read:canvases   recent runs for a canvas4GET   /api/mcp/canvas/ports/manifest   read:canvases   node port manifest5POST  /api/mcp/canvas/create           write:canvas6POST  /api/mcp/canvas/rename           write:canvas7POST  /api/mcp/canvas/archive          write:canvas8POST  /api/mcp/canvas/restore          write:canvas9POST  /api/mcp/canvas/delete           delete:canvas10POST  /api/mcp/canvas/patch            write:canvas    bulk node/edge ops11POST  /api/mcp/canvas/fit-viewport     write:canvas12POST  /api/mcp/canvas/ports/validate   read:canvases13POST  /api/mcp/canvas/node/add         write:canvas14POST  /api/mcp/canvas/node/update      write:canvas15POST  /api/mcp/canvas/node/document-write  write:canvas16POST  /api/mcp/canvas/node/move        write:canvas17POST  /api/mcp/canvas/node/resize      write:canvas18POST  /api/mcp/canvas/node/delete      write:canvas19POST  /api/mcp/canvas/edge/add         write:canvas20POST  /api/mcp/canvas/edge/delete      delete:canvas21POST  /api/mcp/canvas/r2-upload/reserve|verify|finalize|promote-library|cancel  write:canvas (asset upload lifecycle)

Executions

1GET   /api/mcp/executions/timeline     run:workflows2GET   /api/mcp/executions/outputs      run:workflows   step outputs for a run3POST  /api/mcp/executions/cancel       run:workflows4POST  /api/mcp/executions/replay       run:workflows5POST  /api/mcp/executions/redrive      run:workflows

Workspace & assets

1GET   /api/mcp/workspace/info          read:canvases2GET   /api/mcp/workspace/members       read:canvases3POST  /api/mcp/workspace/rename        manage:integrations4POST  /api/mcp/workspace/invite        manage:integrations5POST  /api/mcp/workspace/invite/revoke manage:integrations6POST  /api/mcp/workspace/remove-member manage:integrations7 8# Workspace asset routes accept either-of two scopes:9#   read  = read:assets  OR read:canvases10#   write = write:assets OR write:canvas11#   delete = delete:assets OR write:canvas12GET   /api/mcp/workspace/assets        read (either-of)13GET   /api/mcp/workspace/assets/detail read (either-of)14GET   /api/mcp/workspace/assets/usages read (either-of)15POST  /api/mcp/workspace/assets/upload/reserve|finalize|cancel  write (either-of)16POST  /api/mcp/workspace/assets/rename|move|tags                write (either-of)17POST  /api/mcp/workspace/assets/place                           write:canvas18POST  /api/mcp/workspace/assets/restore                         write (either-of)19POST  /api/mcp/workspace/assets/trash|purge                     delete (either-of)

API keys, templates, integrations

1GET   /api/mcp/api-keys/list           manage:integrations2POST  /api/mcp/api-keys/create         manage:integrations3POST  /api/mcp/api-keys/revoke         manage:integrations4 5GET   /api/mcp/templates/list          read:canvases6GET   /api/mcp/templates/snapshot      read:canvases7POST  /api/mcp/templates/use           write:canvas8POST  /api/mcp/templates/publish       write:canvas9POST  /api/mcp/templates/delete        write:canvas10 11GET   /api/integrations/service-status12GET   /api/integrations/connections         manage:integrations13POST  /api/integrations/connections         manage:integrations  (upsert BYO credential)14POST  /api/integrations/connections/revoke  manage:integrations15GET   /api/integrations/providers16GET|POST /api/integrations/policies         manage:integrations17 18GET   /api/mcp/github/installations|repositories|repository|files/search  read:canvases19GET   /api/mcp/github/repositories/sync-target            manage:integrations20POST  /api/mcp/github/repositories/sync                   manage:integrations21POST  /api/mcp/github/source-links/attach                 write:canvas22POST  /api/mcp/github/exports/draft-pr/prepare|result     manage:integrations23GET   /api/mcp/google-workspace/connection                manage:integrations

Billing

1GET   /api/mcp/credits/balance         read:billing2GET   /api/mcp/credits/transactions    read:billing3GET   /api/mcp/billing/summary         read:billing4GET   /api/billing/focus-export        read:billing   FOCUS JSONL/CSV5GET   /api/billing/focus-metadata      read:billing   FOCUS dataset metadata

See Billing & Usage Export for details.

Webhooks

Method & path	Description
`GET\|POST\|PUT\|PATCH\|DELETE /webhook/trigger`	Inbound webhook that fires a webhook-trigger node. Authenticated by the per-trigger secret as a bearer token.
`POST /api/mcp/webhooks/register`	Create or retrieve the webhook URL + secret for a webhook-trigger node (scope `write:canvas`).

OAuth 2.1 discovery is published at /.well-known/oauth-authorization-server and /.well-known/openid-configuration for MCP clients that authenticate via OAuth. Full webhook flow is in Webhooks.

Was this page helpful?