API Reference Paid

Full specification for the xcelera API. For a guide on getting started with the API, see API & CLI.

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]"
			}
		}
	},
	"auth": {
		"cookies": [
			{
				"name": "session",
				"value": "abc123",
				"domain": "example.com"
			}
		],
		"headers": {
			"X-Custom-Auth": "token123"
		}
	}
}

Fields

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 audit
`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"
	}
}