Introduction

The LightSpot API is a REST interface that lets you launch audits and read results and manage editorial planning from your own code. Nine endpoints, versioned under /v1/, authenticated via a Bearer token. Available on the Eclat and Zenith plans; the competitor analysis endpoint requires Zenith.

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 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.

Connect LightSpot to Claude

Our remote MCP server lets you use LightSpot from Claude on the web, Claude Desktop, the Claude mobile apps and Claude Code. MCP (Model Context Protocol) is the open standard Claude uses to connect to outside tools. You sign in with your LightSpot account, so there is no API key to create or paste. Server URL: https://mcp.lightspot.ai/mcp

1. 1. Add the connector in Claude

   In Claude, open Customize → Connectors, click + Add, then Add custom connector. Name it LightSpot, enter https://mcp.lightspot.ai/mcp as the server URL and click Continue. Keep the sign-in settings Claude detects and leave request headers empty: LightSpot uses OAuth, so there is no API key to enter. Click Add, then sign in when Claude prompts you. A connector added on the web or in Claude Desktop also appears in the Claude mobile apps.

   On a Claude Team or Enterprise plan, an Owner first adds the connector under Organization settings → Connectors. Each member then clicks Connect next to LightSpot in Customize → Connectors.

2. 2. Or add it to Claude Code

   Run the command below in a terminal. Then type /mcp in Claude Code, select lightspot and follow the authentication prompt: your browser opens the LightSpot sign-in page. To make LightSpot available in all your projects, place --scope user before the server name: claude mcp add --transport http --scope user lightspot https://mcp.lightspot.ai/mcp

   claude mcp add --transport http lightspot https://mcp.lightspot.ai/mcp

3. 3. Sign in and choose a workspace

   Sign in to LightSpot, or create an account, with a magic link sent by email or with your Google account. If you belong to several workspaces, choose the one Claude should work in: its plan and quotas apply to everything Claude does there. The consent screen lists what Claude will be able to do: view your sites, audits, scores and our AI experts' findings, run audits, and create or update editorial calendars. It also states what Claude cannot do: delete data, publish to your site or see your billing. Click Allow to finish.

   To move Claude to another workspace later, revoke the connection in LightSpot, then connect again and choose the other workspace.

4. 4. Ask Claude

   Ask in plain language, for example: "Audit https://example.com and tell me what to fix first so AI assistants can cite it." Claude picks the LightSpot tools it needs and answers in the language you write in.

Available tools

Plans

The connector is included in the Eclat and Zenith plans, including during the free trial. Competitor analysis (get_competitors) requires Zenith. Any LightSpot account can connect, but without an active Eclat or Zenith plan the tools reply with a message and a link to subscribe to Eclat. Audits launched from Claude count toward your plan's monthly audit quota and follow its page limit per audit. When an audit is attached to one of your sites, the rule of one audit per site per day also applies.

Revoke access

In LightSpot, open Integrations → Connected apps and click Revoke next to Claude. If your plan is inactive, the same list is available at lightspot.ai/connected-apps. Access stops immediately, and Claude will have to ask for your authorization again before it can use LightSpot. Each workspace you connected appears separately and can be revoked on its own. You can also remove the connector in Claude, but revoking it in LightSpot is what cancels the authorization on our side.

Using an API key instead

If your MCP client only supports local servers, or if you prefer to authenticate with an API key, the @lightspot/mcp npm package provides the same 11 tools over stdio. Create a key in Integrations → API keys, then add the server to your client's configuration. The same plans apply.

{
  "mcpServers": {
    "lightspot": {
      "command": "npx",
      "args": ["-y", "@lightspot/mcp"],
      "env": { "LIGHTSPOT_API_KEY": "lspai_live_<your-key>" }
    }
  }
}

Rate limits

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

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)." } }

Endpoints

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
}

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": [ /* ... */ ]
}

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

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

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

curl "https://lightspot.ai/v1/sites/cmn_xyz/experts?expert=seo-schema" \
  -H "Authorization: Bearer lspai_live_<key>"

curl "https://lightspot.ai/v1/sites/cmn_xyz/editorial-calendar?from=2026-08-01T00%3A00%3A00%2B02%3A00&to=2026-09-01T00%3A00%3A00%2B02%3A00" \
  -H "Authorization: Bearer lspai_live_<key>"

curl -X POST https://lightspot.ai/v1/sites/cmn_xyz/editorial-calendar \
  -H "Authorization: Bearer lspai_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "externalId": "linkedin-2026-w32-01",
      "kind": "SOCIAL",
      "topic": "Why AI assistants overlook otherwise useful pages",
      "platforms": ["LINKEDIN", "X"],
      "format": "post",
      "notes": "Educational angle, finish with an audit CTA",
      "plannedFor": "2026-08-10T09:00:00+02:00"
    }]
  }'

{
  "created": 1,
  "updated": 0,
  "items": [ /* imported slots */ ],
  "calendarPath": "/sites/cmn_xyz/calendar"
}

Changelog

• v1 · 2026-08-03 — Editorial calendar read and idempotent slot import endpoints. MCP tools added.
• v1 · 2026-04-17 — Initial release. Six endpoints. Bearer auth. Per-key rate limits.