Cmulation API

Cmulation exposes a REST JSON API under /api. Browser apps use session JWTs; automation uses tenant-scoped API tokens (recommended for CI and GitHub Actions).

• GET /health — liveness (no auth)
• POST /simulations/verilog — submit digital run (multipart)
• POST /simulations/spice — submit analog run (multipart)
• GET /simulations/:id/status — poll until complete
• GET /simulations/:id/vcd — Verilog waveform (when available)

Authentication

Send credentials on every request except GET /health.

# Automation (recommended)
Authorization: Bearer cmuat_<prefix>_<secret>

# Browser / short-lived scripts (JWT from sign-in)
Authorization: Bearer <accessToken>

Sign in via the dashboard or POST /auth/local-login to obtain a JWT for interactive tools. Use API tokens for long-running CI.

Workspace owners and admins create tokens from the dashboard (or via JWT-authenticated API). The secret is shown once at creation — store it in your CI secret manager.

• GET /api-tokens — list (hints only, no secrets)
• POST /api-tokens — create { "name": "GitHub CI", "scopes": ["simulations:write"] }
• DELETE /api-tokens/:id — revoke

Token management requires a browser JWT — tokens cannot create other tokens. Format: cmuat_<prefix>_<secret>. In production, tokens are gated by API_TOKENS_ENABLED (off until founder enablement).

Submit a single Verilog file, then poll status until the run completes or fails.

export CMULATION_API="https://cmulation.com/api"
export CMULATION_TOKEN="cmuat_xxxxxxxx_your_secret"

# Submit
curl -sS -X POST "$CMULATION_API/simulations/verilog" \
  -H "Authorization: Bearer $CMULATION_TOKEN" \
  -F "file=@design.v;type=text/plain" \
  -F "name=ci-smoke"

# Poll (replace SIM_ID from response)
curl -sS "$CMULATION_API/simulations/SIM_ID/status" \
  -H "Authorization: Bearer $CMULATION_TOKEN"

For multi-file designs, upload a ZIP archive with archive + topModule (Verilog) or topCell (SPICE). See user docs for upload rules.

CLI (v0.1)

Install from the repo at packages/cli, set CMULATION_API_TOKEN, then submit and poll:

cd packages/cli && npm ci && npm run build
export CMULATION_API_TOKEN="cmuat_xxxxxxxx_your_secret"
export CMULATION_API_URL="https://cmulation.com/api"

# Submit + wait until completed (exit 0) or failed (exit 1)
node dist/index.js run verilog --file design.v --name ci-smoke

# ZIP bundle
node dist/index.js run verilog --archive rtl.zip --top-module tb_top

# Or submit / wait separately
node dist/index.js submit verilog --file design.v
node dist/index.js wait SIM_ID

GitHub Action (v0.1)

Composite action at .github/actions/cmulation-sim. Add secret CMULATION_API_TOKEN to your repo, then:

- uses: ./.github/actions/cmulation-sim
  with:
    token: ${{ secrets.CMULATION_API_TOKEN }}
    engine: verilog
    file: rtl/tb_top.v
    # archive: rtl/project.zip
    # top-module: tb_top
    timeout-seconds: '900'

See .github/workflows/cmulation-ci-sample.yml in the repository for a copy-paste workflow.

Errors & limits

• 401 — missing or invalid token
• 403 — insufficient scope or role
• 402 — insufficient Sim-Credits (INSUFFICIENT_SIM_CREDITS)
• 413 — upload exceeds plan limit

Usage and quotas: GET /tenants/usage

Stability & updates

We ship additive API changes in small releases. Breaking changes are announced in advance. OpenAPI specification is on the roadmap. CLI and GitHub Action templates ship from packages/cli and .github/actions/cmulation-sim — contact us for enterprise integration reviews.