API Reference

The Molecule AI Platform exposes a REST API (default port 8080) for workspace management, agent registry, communication, and administration. All endpoints return JSON unless otherwise noted.

Breaking changes — PR #701 (2026-04-17)

PATCH /workspaces/:id now requires authentication. Previously, requests without a bearer token could update cosmetic fields (name, x/y position). All PATCH calls now require Authorization: Bearer <workspace-token> or receive 401 Unauthorized.
GET /templates and GET /org/templates now require AdminAuth. Unauthenticated callers receive 401 Unauthorized.
All /workspaces/:id endpoints validate the :id path parameter as a UUID. Non-UUID values return 400 Bad Request before any database interaction.

Migration: add Authorization: Bearer <workspace-token> to all PATCH /workspaces/:id calls. Use an admin bearer token for GET /templates and GET /org/templates. Ensure :id values in automation scripts are valid UUIDs.

Base URL: http://localhost:8080 (self-hosted) or https://api.moleculesai.app (SaaS)

Endpoint reference

The full endpoint reference is grouped into these pages:

Workspaces — workspace CRUD & lifecycle, budget, configuration, files, activity, session search.
Communication — registry, discovery, A2A proxy & delegation.
Memory & Secrets — key-value & HMA-scoped memory, secrets, workflow checkpoints.
Integrations — schedules, channels, plugins, auth tokens, templates & bundles, approvals.
Real-time & Observability — canvas, traces, audit ledger, events, terminal, WebSocket, SSE.

Authentication Model

The platform uses three authentication middleware variants depending on the sensitivity of the route.

AdminAuth

Strict bearer-token authentication. Required for any route where a forged request could leak prompts/memory, create/mutate workspaces, or leak operational data.

Authorization: Bearer <token>

Fail-open behavior: When no live tokens exist globally (fresh install), AdminAuth passes all requests through. Once the first token is created, all AdminAuth routes require a valid bearer.

WorkspaceAuth

Per-workspace bearer token binding. Workspace A's token cannot access workspace B's sub-routes. Used for the entire /workspaces/:id/* group (except the A2A proxy, which uses CanCommunicate).

Authorization: Bearer <workspace-token>

CanvasOrBearer

Accepts either a valid bearer token OR a request whose Origin header matches CORS_ORIGINS. Used only for cosmetic-only routes where a forged request has zero data/security impact.

Currently applies only to PUT /canvas/viewport. Do not extend to data-sensitive routes.

Health and Monitoring

Method	Path	Auth	Description
GET	`/health`	None	Returns `200 OK` if the platform is running. Use for load balancer health checks.
GET	`/metrics`	None	Prometheus text format (v0.0.4) metrics. Scrape-safe, no auth required.
GET	`/admin/liveness`	AdminAuth	Per-subsystem `supervised.Snapshot()` ages. Check before debugging stuck scheduler/heartbeat goroutines.

Error Responses

All endpoints return standard HTTP status codes:

Status	Meaning
200	Success
201	Created
400	Bad request (malformed body, missing required fields)
401	Unauthorized (missing or invalid bearer token)
403	Forbidden (valid token but insufficient access)
404	Not found (workspace, schedule, channel, etc. does not exist)
409	Conflict (idempotency key collision on delegation)
429	Rate limited (exceeds `RATE_LIMIT` requests/min)
500	Internal server error

Error response body format:

{
  "error": "human-readable error message"
}

Rate Limiting

All endpoints are subject to a global rate limit of RATE_LIMIT requests per minute (default: 600). When exceeded, the platform returns 429 Too Many Requests with a Retry-After header.

CORS

The platform sets CORS headers based on the CORS_ORIGINS environment variable (comma-separated list, default: http://localhost:3000,http://localhost:3001). Preflight (OPTIONS) requests are handled automatically by the Gin CORS middleware.

API Reference

On this page