API documentation | LightSpot

Introduction

The LightSpot API is a REST interface that lets you launch audits and read results from your own code. Six endpoints, versioned under /v1/, authenticated via a Bearer token. Available on Business and Enterprise plans.

Base URL: https://lightspot.ai/v1

curl -X POST https://lightspot.ai/v1/audits \
  -H "Authorization: Bearer lspai_live_<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Authentication

Create and manage keys in Settings → Integrations. A key is shown in full only once at creation — save it in a secret manager.

Pass the key in the Authorization header on every request:

Authorization: Bearer lspai_live_<your-key>

Revoking a key invalidates it immediately. Rotating keys: create a new one, update your integration, then revoke the old one.

Rate limits

Each key has its own request budget, refreshing every minute:

Plan	Requests / min / key
Business	60
Enterprise	300

Exceeding the limit returns HTTP 429 with retryAfter (seconds) in the error payload. Audit quota is separate — shared with your dashboard, based on auditsPerMonth of your plan.

Errors

All errors share the same shape:

{ "error": { "code": "quota_exceeded", "message": "Monthly audit quota reached (50/50)." } }

Code	HTTP	Meaning
`unauthorized`	401	Missing, invalid, or revoked API key
`forbidden`	403	Authenticated but plan does not allow API
`not_found`	404	Resource does not exist or is not yours
`validation`	400	Body or query failed schema validation
`unreachable_url`	400	URL could not be reached for audit
`quota_exceeded`	429	Monthly audit quota exhausted
`rate_limit_exceeded`	429	Per-key requests-per-minute cap hit
`server_error`	500	Unhandled exception

Endpoints

POST/v1/audits

Launch an audit

Creates an audit and returns immediately with a QUEUED status. Poll the status endpoint or fetch the full audit later.

curl -X POST https://lightspot.ai/v1/audits \
  -H "Authorization: Bearer lspai_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","maxPages":10}'

{
  "id": "cmn_abc123",
  "shareToken": "xxxxxxxxxx",
  "status": "QUEUED",
  "maxPages": 10
}

GET/v1/audits/{id}

Full audit

curl https://lightspot.ai/v1/audits/cmn_abc123 \
  -H "Authorization: Bearer lspai_live_<key>"

{
  "id": "cmn_abc123",
  "status": "DONE",
  "url": "https://example.com",
  "score": { "global": 55, "seo": 64, "geo": 50, "grade": "C" },
  "issues": [ /* ... */ ],
  "topActions": [ /* top 3 */ ],
  "pages": [ /* ... */ ],
  "keywords": [ /* ... */ ]
}

GET/v1/audits/{id}/status

Polling status

Lightweight endpoint for polling. Returns the current status and a deterministic progress number between 0 and 1.

{ "id": "cmn_abc123", "status": "ANALYZING", "progress": 0.5 }

GET/v1/sites

List sites

Returns sites owned by the caller. Supports limit (max 100, default 50) and offset.

{
  "data": [
    {
      "id": "cmn_xyz",
      "name": "Acme",
      "url": "https://acme.com",
      "createdAt": "2026-04-01T00:00:00Z",
      "latestAuditId": "cmn_abc",
      "latestScore": 72
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

GET/v1/sites/{id}

Site detail

Site metadata plus the five most recent audits, any status.

{
  "id": "cmn_xyz",
  "name": "Acme",
  "url": "https://acme.com",
  "recentAudits": [ /* up to 5 compact audit summaries */ ]
}

GET/v1/sites/{id}/audits

Audit history for a site

Paginated list of audits for a site. Same limit / offset contract as /v1/sites.

Changelog

v1 · 2026-04-17 — Initial release. Six endpoints. Bearer auth. Per-key rate limits.