API Reference

Trigger audits programmatically using the Xcelera API.

Authentication

All API requests require a Bearer token in the Authorization header.

Generate tokens in Settings → API Tokens. You can have up to 5 active tokens. Tokens cannot be retrieved after creation — store them securely.

Authorization: Bearer <token>

POST /api/v1/audit

Trigger a Lighthouse audit for a page definition.

Request body

{
  "ref": "homepage",
  "options": {
    "device": "mobile",
    "location": "us-east-1"
  },
  "context": {
    "service": "GitHub Actions",
    "buildNumber": "42",
    "buildUrl": "https://github.com/org/repo/actions/runs/123",
    "prNumber": 7,
    "git": {
      "owner": "org",
      "repo": "repo",
      "branch": "feature/faster-lcp",
      "commit": {
        "hash": "abc1234",
        "message": "Optimize hero image loading",
        "date": "2025-01-15T10:30:00Z",
        "author": "[email protected]"
      }
    }
  }
}

Field	Required	Description
`ref`	Yes	Page definition ref (the slug shown on your dashboard)
`options.device`	No	`"mobile"` or `"desktop"`
`options.location`	No	Audit region
`context`	No	CI/CD metadata attached to the build
`context.git.commit.hash`	If `git` provided	7–64 character hex string
`context.git.commit.message`	If `git` provided	Commit message
`context.git.commit.date`	If `git` provided	ISO 8601 date
`auth.cookies`	No	Array of cookie objects for authenticated pages
`auth.headers`	No	Key-value headers for authenticated pages

Response

{
  "success": true,
  "data": {
    "auditId": "clx1abc23def",
    "url": "https://example.com",
    "status": "scheduled",
    "pageDefinition": {
      "id": "clx...",
      "name": "Homepage",
      "ref": "homepage"
    }
  }
}

Error responses

Status	Meaning
`400`	Invalid request body or missing required auth for authenticated pages
`401`	Missing or invalid API token
`404`	Page ref not found for your account
`429`	Credit limit exceeded
`500`	Internal error starting the audit

All errors return:

{
  "success": false,
  "error": {
    "message": "Description of what went wrong",
    "details": "Additional context"
  }
}

Example: curl

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

Example: GitHub Actions

- 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 }}"
            }
          }
        }
      }'

Store your API token as a GitHub Actions secret. Never commit tokens to your repository.