Spotlit API documentation.

Overview

The Spotlit API is read-only. It exposes the brands on your account and the visibility scores Spotlit has already computed for them. Everything else — adding brands, running checks, editing white-label settings — happens in the dashboard.

• Base URL: https://swiftapplab.com/api/spotlit/v1
• Methods: GET only. Any other verb returns 405.
• Format: JSON responses, UTF-8.
• Plans: Included on Agency and Agency Plus. Free, Starter, and Pro do not have API access.

Authentication

Generate a key from Settings in your Spotlit dashboard while on an Agency or Agency Plus plan. Keys look like spk_live_….

The plaintext key is shown once at creation — only a hash is stored, so we cannot recover it later. Save it to your secret manager immediately. Generating a new key replaces the old one; you can also revoke a key at any time from the same screen.

Pass the key either as a bearer token or in the x-api-key header:

# Bearer token
curl https://swiftapplab.com/api/spotlit/v1/brands \
  -H "Authorization: Bearer spk_live_YOUR_KEY"

# or x-api-key
curl https://swiftapplab.com/api/spotlit/v1/brands \
  -H "x-api-key: spk_live_YOUR_KEY"

List brands

Returns every brand on your account with its most recent visibility score.

curl https://swiftapplab.com/api/spotlit/v1/brands \
  -H "Authorization: Bearer spk_live_YOUR_KEY"

{
  "brands": [
    {
      "id": "b_9fce21a4",
      "domain": "acmeplumbing.com",
      "name": "Acme Plumbing",
      "latest_score": 62,
      "latest_checked_at": "2026-07-27T06:12:04.118Z",
      "latest_report_url": "https://swiftapplab.com/ai-search-visibility-checker/report/r_71ba0c"
    }
  ],
  "plan": "Agency"
}

Get one brand

Returns one brand with its score breakdown and 30-day history. The brand must be on your account — otherwise you get a 404.

curl https://swiftapplab.com/api/spotlit/v1/brands/b_9fce21a4 \
  -H "Authorization: Bearer spk_live_YOUR_KEY"

{
  "id": "b_9fce21a4",
  "domain": "acmeplumbing.com",
  "name": "Acme Plumbing",
  "latest_score": 62,
  "latest_checked_at": "2026-07-27T06:12:04.118Z",
  "breakdown": { "mentions": 70, "position": 55, "sentiment": 80, "shareOfVoice": 44 },
  "history": [
    { "date": "2026-06-28", "score": 51 },
    { "date": "2026-07-27", "score": 62 }
  ]
}

breakdown holds the four components behind the score — see how the score is calculated. history covers the last 30 days of completed checks, oldest first, and is empty for a brand that has never been checked.

Errors

Errors return the matching HTTP status and a JSON body with an error string.

{ "error": "Invalid or missing API key. Pass it as 'Authorization: Bearer <key>' or 'x-api-key'." }

Limits & notes

• Data freshness. The API reflects completed checks only. Agency and Agency Plus run daily, so scores typically change once per day — polling more often than that returns the same values.
• Brand limits. The API returns up to your plan's brand limit: 10 on Agency, 25 on Agency Plus.
• Rate limits. Agency Plus has higher API rate limits than Agency. Both are set for reporting-style usage; if you're building something that needs sustained high-volume polling, email us first.
• Versioning. The /v1 prefix is stable. Breaking changes would ship under a new version, not silently.
• Legacy alias. /api/chatrank/v1/* still resolves for accounts created before the Spotlit rename. Use /api/spotlit/v1/* in new code.