Guides

API & CLI Paid

Trigger audits programmatically from your CI/CD pipeline, scripts, or the command line. This is the best way to integrate xcelera into your deployment workflow.

When to use the API

  • CI/CD pipelines — audit on every deploy or pull request
  • Custom scheduling — trigger audits at specific times using your own scheduler (cron, GitHub Actions schedules, etc.)
  • Automation — integrate xcelera into your monitoring or deployment tooling

Creating an API token

  1. Go to Settings → API Tokens
  2. Click Generate Token
  3. Copy the token immediately — it cannot be retrieved later

You can have up to 5 active tokens per organization. Tokens can be deactivated from the same settings page.

Store your API token securely. Never commit tokens to your repository or share them in plain text. Use environment variables or your CI provider's secret management.

Triggering an audit

Send a POST request to /api/v1/audit with your page ref:

curl -X POST https://xcelera.dev/api/v1/audit \
  -H "Authorization: Bearer $XCELERA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ref": "homepage"}'

For the full request schema including device, location, auth, and git context options, see the API Reference.

Adding Git context

Pass git information to link audits to commits and enable GitHub check runs:

curl -X POST https://xcelera.dev/api/v1/audit \
  -H "Authorization: Bearer $XCELERA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "homepage",
    "context": {
      "git": {
        "owner": "my-org",
        "repo": "my-repo",
        "branch": "main",
        "commit": {
          "hash": "abc1234",
          "message": "Deploy v2.1",
          "date": "2025-01-15T10:30:00Z"
        }
      }
    }
  }'

GitHub Actions example

- name: Run xcelera Audit
  run: |
    curl -X POST https://xcelera.dev/api/v1/audit \
      -H "Authorization: Bearer ${{ secrets.XCELERA_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d '{
        "ref": "homepage",
        "context": {
          "service": "GitHub Actions",
          "buildNumber": "${{ github.run_number }}",
          "buildUrl": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}",
          "prNumber": ${{ github.event.pull_request.number || 0 }},
          "git": {
            "owner": "${{ github.repository_owner }}",
            "repo": "${{ github.event.repository.name }}",
            "branch": "${{ github.head_ref }}",
            "commit": {
              "hash": "${{ github.event.pull_request.head.sha }}",
              "message": "${{ github.event.pull_request.title }}",
              "date": "${{ github.event.pull_request.updated_at }}"
            }
          }
        }
      }'

Add XCELERA_TOKEN as a GitHub Actions secret in your repository settings. With git context included, you'll get GitHub check runs on your PRs automatically.

CLI

The xcelera CLI provides a convenient way to trigger audits from the command line:

xcelera audit https://example.com --token $XCELERA_TOKEN

The CLI automatically detects Git context from your local repository, so you don't need to pass branch and commit information manually.

The CLI uses the same API under the hood. Anything you can do with the CLI can also be done with direct API calls.

Help