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.

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

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

Workspaces

Core workspace CRUD and lifecycle operations.

CRUD

Lifecycle

Registry

Workspace registration and heartbeat endpoints. Called by workspace runtimes, not by end users.

Discovery

Peer discovery and access control verification.

Communication

A2A Proxy

Delegation

Configuration

Secrets

Per-Workspace Secrets

Global Secrets

Legacy aliases GET/POST/DELETE /admin/secrets[/:key] also exist and behave identically.

Memory

Key-Value Memory

Agent Memories (HMA-scoped)

Semantic search (?q=)

When a platform-level embedding function is configured, passing ?q=<text> on GET /workspaces/:id/memories triggers vector similarity search instead of the default full-text / ILIKE path:

GET /workspaces/{id}/memories?q=authentication+flow&limit=10
Authorization: Bearer {token}

Matching entries are returned ordered by cosine similarity (most similar first). Each row includes an additional similarity_score field (0–1, higher is closer):

[
  {
    "id": "mem_abc123",
    "key": "auth-design",
    "value": "We use short-lived JWTs issued by the platform and refreshed via /auth/token.",
    "similarity_score": 0.91,
    "created_at": "2026-04-10T14:22:00Z"
  }
]

Graceful fallback: if no embedding function is configured, or if the embedding call fails for a given query, the platform falls back transparently to the text-search path. The similarity_score field is absent in fallback responses. You do not need to change client code to handle both modes.

Files

Workspace file management. Files are stored in the workspace's config directory.

Activity

Activity logging and search for A2A communications, task updates, and agent logs.

Audit Ledger

Tamper-evident audit trail for workspace events. Used by the Canvas Audit Trail panel.

Audit entry schema

Example response:

{
  "entries": [
    {
      "id": "aud_xyz789",
      "event_type": "delegation",
      "actor": "ws_abc123",
      "summary": "Delegated task 'fix CI' to Backend Engineer",
      "chain_valid": true,
      "created_at": "2026-04-17T14:05:00Z"
    }
  ],
  "cursor": "eyJpZCI6ImF1ZF94eXo3ODkifQ"
}

Session Search

Workflow Checkpoints

Step-level progress persistence for long-running Temporal workflows. Workspaces with runtime: langgraph (Temporal) automatically save a checkpoint after each of the three workflow stages (task_receive, llm_call, task_complete) and resume from the last completed stage on restart.

Step names and indices:

Schedules

Cron-based scheduled tasks per workspace.

Schedule source field: template for org/import-seeded schedules, runtime for Canvas/API-created. The last_status includes skipped when the scheduler concurrency-aware-skips a busy workspace.

Channels

Social channel integrations (Telegram, Slack, etc.) for workspace agents.

Per-Workspace Channels

Global Channel Endpoints

Plugins

Plugin registry and per-workspace plugin management.

Global Plugin Registry

Per-Workspace Plugins

Auth Tokens

Bearer token management for workspaces.

Test Token (Development Only)

Teams

Expand and collapse team views in the Canvas hierarchy.

Templates and Bundles

Templates

Org Templates

Bundles

Approvals

Human-in-the-loop approval system for agent actions.

Canvas

Canvas viewport persistence (cosmetic only).

Traces

LLM trace retrieval from Langfuse.

Audit Ledger

HMAC-SHA256-chained immutable agent event log for compliance record-keeping (EU AI Act Art. 12 / Art. 13). Each event is cryptographically chained to the previous one — tampering with any record breaks all subsequent HMACs.

Query

Query parameters:

Response shape:

{
  "events": [
    {
      "id": "uuid",
      "workspace_id": "uuid",
      "agent_id": "my-researcher",
      "session_id": "sess_abc123",
      "event_type": "tool_call",
      "payload": { "tool": "bash", "input": "ls /workspace" },
      "hmac": "sha256hex...",
      "prev_hmac": "sha256hex...",
      "created_at": "2026-04-17T12:00:00Z"
    }
  ],
  "chain_valid": true
}

chain_valid values:

• true — all HMACs verified; ledger is intact.
• false — at least one HMAC mismatch; possible tampering.
• null — AUDIT_LEDGER_SALT is absent from the platform env; verification skipped.

Workspace-side: recording events

In your workspace template, wire LedgerHooks into the agent pipeline:

from molecule_audit.hooks import LedgerHooks

hooks = LedgerHooks(agent_id="my-researcher", session_id=session_id)

async with hooks:
    # hooks.on_task_start / on_llm_call / on_tool_call / on_task_end
    # fire automatically at each pipeline stage
    result = await agent.run(task)

LedgerHooks is exception-safe — a failed ledger write never aborts the agent task.

CLI chain verification

# Verify the full chain for an agent; exit 0 = intact
python -m molecule_audit.verify --agent-id my-researcher

# Custom DB URL
python -m molecule_audit.verify --agent-id my-researcher --db postgresql://user:pass@host/db

Exit codes: 0 = chain valid · 1 = broken chain · 2 = AUDIT_LEDGER_SALT missing · 3 = DB error.

Events

Append-only event log for structure changes.

Terminal

WebSocket-based terminal access to workspace containers.

WebSocket

Real-time event streaming for Canvas clients.

Server-Sent Events (AG-UI)

Per-workspace SSE stream compatible with the AG-UI protocol. Use this endpoint to consume structured agent events from a web client or external tool without a WebSocket library.

Event envelope format

Each event is delivered as an SSE data: line containing a JSON object:

{
  "type": "AGENT_MESSAGE",
  "timestamp": 1713398400000,
  "data": { ... }
}

• type — event type string (e.g. AGENT_MESSAGE, A2A_RESPONSE, TASK_UPDATED)
• timestamp — Unix milliseconds at time of broadcast
• data — event-specific payload (same payload as the WebSocket hub delivers)

Event types streamed

All event types emitted by RecordAndBroadcast and BroadcastOnly reach the SSE stream. The BroadcastOnly path is important: events like AGENT_MESSAGE, A2A_RESPONSE, and TASK_UPDATED skip Redis and would be invisible to a Redis-only subscriber — the in-process SSE layer catches them.

Example: connect with curl

curl -N \
  -H "Authorization: Bearer <workspace-token>" \
  http://localhost:8080/workspaces/<id>/events/stream

: ping

data: {"type":"AGENT_MESSAGE","timestamp":1713398401234,"data":{"text":"Starting task..."}}

data: {"type":"TASK_UPDATED","timestamp":1713398405678,"data":{"status":"running"}}

Example: connect from JavaScript

const es = new EventSource(
  `/workspaces/${workspaceId}/events/stream`,
  { headers: { Authorization: `Bearer ${token}` } }
);

es.onmessage = (e) => {
  const event = JSON.parse(e.data);
  console.log(event.type, event.data);
};

Error Responses

All endpoints return standard HTTP status codes:

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.