Reference & OpenAPI Contract
The machine-readable OpenAPI contract for the Molecule Management API, and a per-surface endpoint summary that derives from it.
Reference & OpenAPI Contract
This guide's prose is the human layer. The contract — exact paths, request bodies, response schemas, status codes — is the OpenAPI spec. This page points you at it and gives a navigational summary by surface. It does not re-author endpoint definitions, to avoid a second source of truth.
Machine-readable contract (OpenAPI)
The Management API contract is authored as an OpenAPI 3 document at
workspace-server/docs/openapi/management.yaml in the molecule-core
repository (branch feat/openapi-management-spec, in review as of 2026-06).
This document is the single source of truth for endpoint shapes. The prose
guides in this section derive from it; when they disagree, the spec wins.
The pre-existing swaggo-generated workspace-server/docs/openapi/swagger.yaml
is a /schedules-only stub and is not the management contract — do not
generate clients from it. Use management.yaml once it lands.
When the spec is published to the docs site, this page will embed the rendered schema. Until then, read the YAML directly from the source repo.
Endpoint summary by surface
The tables below are a navigational index, not the contract. Auth tiers are
per the auth model. For request and
response shapes, consult management.yaml.
Control plane — api.moleculesai.app
Build against the stable /api/v1/* prefix; /cp/* is identical but
sunset-headed.
| Method · Path | Purpose | Tier |
|---|---|---|
/auth/{signup,login,callback,signout,me,...} | AuthKit session lifecycle | — |
POST /api/v1/orgs | Create org (412/402/409) | WorkOS session |
GET /api/v1/orgs · GET/DELETE /api/v1/orgs/:slug | List / get / delete (owner GDPR purge, 204) | WorkOS session (+ownership) |
GET /api/v1/orgs/:slug/{export,provision-status} | Export, provision status | WorkOS session |
GET /api/v1/orgs/:slug/instance | Routing lookup | public |
…/orgs/:slug/members[...], invitations | Member management | WorkOS session |
/billing/{invoices,checkout,portal,topup,auto-credits} | Billing | WorkOS session |
POST /webhooks/stripe | Stripe webhook | signature |
GET /templates[/:slug] | List templates | WorkOS session |
POST/DELETE /api/v1/admin/templates[/:slug] | Manage templates | CP admin bearer |
GET/POST /api/v1/admin/orgs (?dry_run=true) | Admin org ops | CP admin bearer |
GET /api/v1/admin/orgs/:slug/admin-token | Read tenant-admin-token | CP admin bearer |
GET /api/v1/admin/orgs/:slug/workspaces | List org workspaces | CP admin bearer |
DELETE /api/v1/admin/tenants/:slug (body {"confirm":"<slug>"}) | Tenant teardown | CP admin bearer |
/api/v1/admin/tenants/:slug/{redeploy,reboot,diagnostics,console-output,boot-events,scrub-artifacts} | Tenant fleet ops | CP admin bearer |
POST /api/v1/admin/tenants/redeploy-fleet | Fleet rollout | CP admin bearer |
POST /api/v1/admin/workspaces/:id/env | Force-set workspace env (SSM + restart) | CP admin bearer |
/api/v1/admin/tenants/:slug/migrate-data-volume | Data-volume migration | CP admin bearer |
/api/v1/admin/{thin-ami,runtime-image}/{promote,list,rollback} | Image/AMI pins | CP admin bearer |
POST /api/v1/workspaces/provision (422 RUNTIME_PIN_MISSING) | Provision workspace | provision-secret |
DELETE /api/v1/workspaces/:id?prune= | Deprovision | provision-secret + X-Molecule-Admin-Token |
GET /api/v1/workspaces/:id/status?instance_id= | Provision status | provision-secret |
Tenant workspace server — <org-slug>.moleculesai.app
| Method · Path | Purpose | Tier |
|---|---|---|
GET/POST/DELETE /workspaces[/:id] | Workspace lifecycle | AdminAuth (Org API Key / ADMIN_TOKEN) |
PATCH /workspaces/:id · /restart|/pause|/resume|/hibernate | Update / lifecycle | WorkspaceAuth |
GET/PUT /admin/workspaces/:id/llm-billing-mode {mode} | Read/set billing-mode (platform_managed|byok|disabled; null clears) | AdminAuth (Org API Key) |
GET/PATCH /workspaces/:id/budget | Read/set budget (budget_limits period map) | AdminAuth (Org API Key) |
POST/PUT /workspaces/:id/secrets {key,value} | Set workspace secret (auto-restart) | WorkspaceAuth |
POST /settings/secrets | Set org-wide secret | AdminAuth |
POST /org/import · GET /org/templates | Create workspaces from org template · list | AdminAuth |
GET/POST/DELETE /org/tokens[/:id] | Mint / list / revoke Org API Keys | AdminAuth |
GET/PUT /orgs/:id/plugins/allowlist | Plugin allowlist | AdminAuth |
GET /templates · POST /templates/import | Templates | AdminAuth |
GET /bundles/export/:id · POST /bundles/import | Bundles | AdminAuth |
GET/POST /workspaces/:id/tokens | Per-workspace tokens (self-service) | WorkspaceAuth |
POST /admin/workspaces/:id/tokens | Mint a per-workspace token (admin tier; used by the management MCP/CLI) | AdminAuth (Org API Key / ADMIN_TOKEN) |
| a2a, delegations, registry, activity, schedules, memory, approvals, traces, channels, files, mcp-bridge | Agent/runtime surface | per route |
For deeper tenant route tables see Platform API (Go Backend) and the API Reference.
Tooling that consumes this contract
- CLI — the
moleculeCLI (Go/cobra). Today it is primarily a runtime-bridge; management verbs are being extended and itsrunHTTPpath does not yet attachAuthorization(verify against source). See per-task CLI lines in the task guides. - MCP — MCP Server Setup. Today's MCP server is single-tenant workspace-ops; a dedicated org-key-authed management MCP (org/secret/template/token tools) is planned and will be generated from this same OpenAPI contract.
- Dashboard — the canonical management surface (AuthKit session +
X-Molecule-Org-Slug), org ops via the/cp/*proxy, tenant ops direct.
Generate clients and MCP tools from management.yaml, not from the
/schedules-only swaggo stub. The MCP, CLI, and these docs all derive from the
one OpenAPI contract — keeping them downstream of a single SSOT is what prevents
drift.
Task Guides
Cookbook for the Molecule Management API — provision a workspace, set a secret, mint/revoke an Org API Key, create an org from a template, and set billing-mode/budget. Each with the exact HTTP request plus CLI and MCP equivalents.
MCP Server
Manage Molecule AI workspaces from any MCP-compatible AI agent using 87 tools.