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>. API tokens are enabled on the hosted service — create one from Settings → API tokens in the dashboard.

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

Publishing in progress. @cmulation/cli is not on npm yet — the commands below are how it will work once published. Check back shortly.

Install the CLI, set CMULATION_API_TOKEN, then submit and poll:

npm install -g @cmulation/cli
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)
cmulation run verilog --file design.v --name ci-smoke

# ZIP bundle
cmulation run verilog --archive rtl.zip --top-module tb_top

# Or submit / wait separately
cmulation submit verilog --file design.v
cmulation wait SIM_ID

GitHub Action

Publishing in progress. The public cmulation-action is not released yet — the snippet below is the intended usage once it ships.

Add the CMULATION_API_TOKEN secret to your repo, then reference the action:

- uses: <org>/cmulation-action@v1
  with:
    token: ${{ secrets.CMULATION_API_TOKEN }}
    engine: verilog
    file: rtl/tb_top.v
    # archive: rtl/project.zip
    # top-module: tb_top
    timeout-seconds: '900'

Full inputs and a copy-paste workflow are in the action repository's README.

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. The CLI ships as @cmulation/cli on npm and the GitHub Action as a versioned public action — contact us for enterprise integration reviews.