Task Guides

A task-oriented cookbook for the Management API. Each task gives the exact HTTP request (host, method, path, headers, body) plus the CLI and MCP equivalents where they exist.

Conventions used below:

• $ORG_SLUG / $ORG_ID — your org's slug and id.
• $TENANT — your tenant host, $ORG_SLUG.moleculesai.app.
• $MOLECULE_ORG_TOKEN — an Org API Key.
• $CP_ADMIN_TOKEN — the CP admin bearer (operators only).

Provision a workspace

There are two ways to create a workspace, on two different hosts:

A. Tenant-side create (the common path)

Creates and provisions a workspace within your org. Org API Key works.

POST https://$TENANT/workspaces
Authorization: Bearer $MOLECULE_ORG_TOKEN
X-Molecule-Org-Id: $ORG_ID
Content-Type: application/json

{
  "name": "researcher",
  "role": "Research agent",
  "model": "claude-sonnet-4",
  "runtime": "claude-code"
}

Field constraints (enforced server-side): name ≤ 255 chars, role ≤ 1000, model/runtime ≤ 100; name and role reject newlines and YAML-special chars ({}[]|>*&!). See Platform API breaking changes.

• CLI: molecule workspace create --name researcher --role "Research agent" --model claude-sonnet-4 --runtime claude-code
• MCP: provision_workspace (planned management MCP) — today, workspace create is available in the single-tenant workspace-ops MCP.

B. Control-plane provision (EC2-side)

The low-level provisioning entrypoint, gated by the provision shared-secret. Build against the stable /api/v1/workspaces/* surface (the /cp/workspaces/* prefix is the older, identical alias). Returns 422 RUNTIME_PIN_MISSING if no runtime image is pinned. Normally driven by the platform server-to-server, not by integrations.

POST https://api.moleculesai.app/api/v1/workspaces/provision
Authorization: Bearer <PROVISION_SHARED_SECRET>
Content-Type: application/json

{ ... }

Deprovision additionally requires the per-tenant admin token in the X-Molecule-Admin-Token header (so a leaked shared secret can't terminate other tenants' workspaces — controlplane #118):

DELETE https://api.moleculesai.app/api/v1/workspaces/:id?prune=<bool>
Authorization: Bearer <PROVISION_SHARED_SECRET>
X-Molecule-Admin-Token: <per-tenant admin token>

• Status: GET https://api.moleculesai.app/api/v1/workspaces/:id/status?instance_id=<id>

Set a workspace or org secret

Workspace environment variables are secrets — there is no separate /env route on the tenant. Setting a secret auto-restarts the workspace.

Per-workspace secret

POST https://$TENANT/workspaces/:id/secrets
Authorization: Bearer $MOLECULE_ORG_TOKEN
X-Molecule-Org-Id: $ORG_ID
Content-Type: application/json

{ "key": "MY_API_KEY", "value": "..." }

(PUT is also accepted for upsert.) The value is encrypted AES-256-GCM into workspace_secrets, emits a secret.set audit event, and the workspace restarts automatically.

Org-wide secret

POST https://$TENANT/settings/secrets
Authorization: Bearer $MOLECULE_ORG_TOKEN
X-Molecule-Org-Id: $ORG_ID
Content-Type: application/json

{ "key": "...", "value": "..." }

• CLI: molecule secret ws set --workspace <id> MY_API_KEY=... / molecule secret org set KEY=...
• MCP: set_workspace_secret / set_org_secret (planned management MCP).

Mint and revoke an Org API Key

Minting and revoking happen on the tenant host (/org/tokens). See the full Org-Scoped API Keys walkthrough for audit fields.

Mint

POST https://$TENANT/org/tokens
Authorization: Bearer $MOLECULE_ORG_TOKEN
X-Molecule-Org-Id: $ORG_ID
Content-Type: application/json

{ "name": "ci-bot" }

Returns the plaintext auth_token (alongside id and prefix) once — it is never returned again. An existing Org API Key, the tenant ADMIN_TOKEN, or a CP session can mint.

List

GET https://$TENANT/org/tokens
Authorization: Bearer $MOLECULE_ORG_TOKEN
X-Molecule-Org-Id: $ORG_ID

Returns metadata only — the plaintext is never returned after creation.

Revoke

DELETE https://$TENANT/org/tokens/:id
Authorization: Bearer $MOLECULE_ORG_TOKEN
X-Molecule-Org-Id: $ORG_ID

Revocation is instantaneous — the next request with the revoked key fails.

• CLI: molecule org token create --name ci-bot / molecule org token list / molecule org token revoke <id>
• MCP: mint_org_token / list_org_tokens / revoke_org_token (planned management MCP).

Create an org from a template

Two distinct operations live under "templates": creating workspaces from an org template inside an existing org (tenant /org/import), and creating a brand-new org (CP /api/v1/orgs, session-tier).

Populate an existing org from an org template

Imports a YAML org template — provisions every workspace, wires parent/child relationships, seeds schedules, installs plugins. See Org Templates.

POST https://$TENANT/org/import
Authorization: Bearer $MOLECULE_ORG_TOKEN
X-Molecule-Org-Id: $ORG_ID
Content-Type: application/json

{ ...org template YAML/JSON... }   # verify body shape against handler / OpenAPI

List the available org templates with GET https://$TENANT/org/templates.

• CLI: molecule org create --template <name>
• MCP: create_org_from_template → POST /org/import (planned).

Create a brand-new org (CP, session-tier)

Creating the organization itself is a control-plane, session-authed operation — an Org API Key cannot do this.

POST https://api.moleculesai.app/api/v1/orgs
<WorkOS session cookie> + X-Molecule-Org-Slug
Content-Type: application/json

{ ...org create body... }

Errors: 412 (no ToS accepted), 402 (quota), 409 (slug taken). A dry-run exists for the admin variant only: POST /api/v1/admin/orgs?dry_run=true.

Set billing-mode or budget

LLM billing-mode

Billing-mode governs whether vendor-LLM secrets are honored (see secret-stripping above). It is a tenant route, keyed by workspace id and authorized by an Org API Key (plus the X-Molecule-Org-Id routing header) — not a control-plane operation:

GET  https://$TENANT/admin/workspaces/:id/llm-billing-mode
PUT  https://$TENANT/admin/workspaces/:id/llm-billing-mode
Authorization: Bearer $MOLECULE_ORG_TOKEN
X-Molecule-Org-Id: $ORG_ID
Content-Type: application/json

{ "mode": "platform_managed" }   # or "byok" or "disabled"

The mode field enum is platform_managed, byok, or disabled. {"mode":null} clears the per-workspace override (falling back to the org / default mode); an empty body {} is a 400 — the caller must be explicit.

• CLI: molecule workspace billing-mode <mode> (verify against CLI source).
• MCP: set_llm_billing_mode (planned management MCP).

Workspace budget

The per-workspace LLM budget cap is read and written on the tenant host, keyed by workspace id and authorized by an Org API Key (PATCH is tenant-admin):

GET   https://$TENANT/workspaces/:id/budget
PATCH https://$TENANT/workspaces/:id/budget
Authorization: Bearer $MOLECULE_ORG_TOKEN
X-Molecule-Org-Id: $ORG_ID
Content-Type: application/json

{ "budget_limits": { "hourly": 100, "daily": null, "weekly": 500, "monthly": 2000 } }

The canonical body is the multi-period budget_limits map (per-period USD cents; null clears that period). The legacy single-monthly shape { "budget_limit": 2000 } / { "budget_limit": null } is still accepted for back-compat. Sending neither budget_limits nor budget_limit is a 400.

• CLI: molecule workspace budget (verify against CLI source).
• MCP: set_workspace_budget (planned management MCP).

Other common tasks (quick reference)

For the authoritative per-endpoint contract, see Reference & OpenAPI.