Molar API

Molar platform API — orgs, scenarios, runs, tokens, OAuth, and how the dashboard connects.

Molar API

Note:

Self-hosted / operator reference. SaaS customers use app.molar.it and api.molar.it — you do not deploy the Molar API yourself unless you run Molar on-prem.

The Molar API is Molar's platform API and orchestration layer. It stores org data, scenarios, run metadata, OAuth clients, billing hooks, and proxies to product services.

Production API: https://api.molar.it

Local dev default: http://127.0.0.1:3100

What it does

ResponsibilityDetails
Org & membershipUsers, roles, entitlements
Scenario registryUploaded .molar.md, compile metadata, schedules
Run orchestrationQueue runs, stream status, artifact URLs
AuthBetter Auth sessions + OAuth 2.1 AS (/api/oauth/*)
TokensPAT/SVC issuance and revocation
Billing hooksUsage events → Lago → payment processors
Live dataRedis Streams for run progress
Blob storageTraces, screenshots, HAR (SeaweedFS on-prem; cloud equivalent in hosted)

The all-in-one dashboard dashboard API proxies authenticated requests to the Molar API when PLUMBING_CONTROL_PLANE_URL is set.

Architecture (hosted)

  • Postgres 17 with row-level security per org
  • PgBouncer transaction pooling in production
  • BullMQ for async jobs
  • Atlas for production schema migrations

Key API surfaces

All routes require authentication unless noted. Prefix may be /api/v1/ depending on deployment.

AreaExamples
IdentityGET /api/v1/me, GET /api/v1/orgs
EntitlementsGET /api/v1/entitlements
ScenariosGET /api/v1/scenarios, upload/sync
RunsGET /api/v1/runs/:id, POST .../ingest, SSE logs
TokensPOST /api/v1/tokens, revoke
OAuth/api/oauth/* — authorize, token, register, revoke
Agent signupPOST /api/v1/agent-signup, POST .../verify, GET .../status (gated by AGENT_SIGNUP_ENABLED in prod)
BillingUsage summary in dashboard
HealthGET /healthz, GET /v1/ready

The dashboard also serves several routes locally (scenarios list, token CRUD, trace ingest proxy) for standalone mode — see dashboard architecture docs.

Scenario compiler integration

  1. CLI or MCP uploads / syncs .molar.md
  2. Molar API stores canonical content + content hash
  3. Compile may run client-side (molar scenarios compile) or server-side on demand
  4. Guard worker pulls compiled spec + clone config for execution

Deterministic compilation means the same scenario hash always produces the same Playwright output.

Run lifecycle

  1. Queued — run record created, BullMQ job enqueued
  2. Running — Guard/Cartographer worker executes; Redis Streams emit progress
  3. Passed / Failed / Errored — artifacts uploaded; Trace ingest triggered on failure
  4. Mender — optional auto-fix pipeline on confirmed Guard failures

Subscribe to live updates via dashboard Live runs or MCP resource molar://runs/{id}.

OAuth mount point

OAuth routes live under /api/oauth/* on the Molar API host — not /oauth/* at the domain root. MCP clients discover metadata via:

  • https://api.molar.it/.well-known/oauth-authorization-server
  • https://mcp.molar.cloud/.well-known/oauth-protected-resource

Local development

cd molar-platform
pnpm install
pnpm --filter @molar/control-plane dev   # :3100

Supporting services:

cd molar-platform/apps/control-plane
docker compose up -d              # Postgres + Redis
docker compose --profile billing up -d   # + Lago (optional)
pnpm drizzle:migrate

Pair with the dashboard:

pnpm --filter @molar/dashboard dev   # :3200, expects Molar API at :3100

Standalone dashboard mode

Unset PLUMBING_CONTROL_PLANE_URL to run the dashboard without a Molar API. Local /api/v1/* routes still work; other paths return 503 unavailable.