CI / API integration

Launch product validation panels from GitHub Actions, Jenkins, or any HTTP client using API keys. No browser session required.

Requirements

• Pro+ plan with an API key (Dashboard → API keys)
• LITMUSRUN_API_KEY stored as a CI secret
• LITMUSRUN_URL: your app origin (e.g. https://litmusrun.com)

POST /api/hooks/validate

Launch a product validation panel.

Headers: x-api-key, Content-Type: application/json

{
  "targetUrl": "https://staging.example.com",
  "missionGoal": "Complete signup without help",
  "agentCount": 5,
  "pipelineId": "optional-template-id",
  "callbackUrl": "https://your-ci.example.com/webhook/litmusrun",
  "projectName": "PR #42",
  "icpBrief": "Optional ICP for composePanel",
  "viewportMode": "desktop",
  "explorationDepth": "standard"
}

Response: { "auditId": "...", "status": "PENDING" }

GET /api/hooks/runs/:auditId

Poll run status with the same API key. Optional query: ?include=findings.

Returns status, score, top findings, panelUrl, pipelineId, and actual failedReason on failure.

Webhooks

When callbackUrl is set, LitmusRun POSTs the status payload on completion or failure. Callbacks include X-LitmusRun-Signature: sha256=... when HOOKS_CALLBACK_SECRET is configured server-side.

Deploy presets

Save configs in Deploy → Save preset, or manage them under Deploy presets. Copy the preset ID and pass pipelineId in the launch request.

GitHub Actions example

name: LitmusRun smoke test
on: [pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - env:
          LITMUSRUN_URL: ${{ secrets.LITMUSRUN_URL }}
          LITMUSRUN_API_KEY: ${{ secrets.LITMUSRUN_API_KEY }}
          TARGET_URL: ${{ vars.PREVIEW_URL }}
        run: |
          LAUNCH=$(curl -sf -X POST "$LITMUSRUN_URL/api/hooks/validate" \
            -H "x-api-key: $LITMUSRUN_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"targetUrl":"'"$TARGET_URL"'","missionGoal":"Smoke test","agentCount":3}')
          AUDIT_ID=$(echo "$LAUNCH" | jq -r .auditId)
          # poll GET /api/hooks/runs/$AUDIT_ID until COMPLETED or FAILED

Rate limits

Per API key: 30 launches/hour and 120 status polls/hour. Shared IP limit also applies (200 req/min).