Spotlight

Appearance

OpenAPI / Swagger ​

The Spotlight API publishes an OpenAPI 3.1 document covering every endpoint a customer integration would ever call. The full operator-dashboard + super-admin surface is excluded from this document — it's not something an integrator needs and we don't want it visible to anyone scanning for endpoints.

What's included ​

  • /v1/sdk/** — every SDK-edge endpoint (/sdk/config, /sdk/content, /sdk/events, /sdk/help/** except attachment streams, FAQ articles).
  • /v1/sdk/help/articles — public FAQ list.
  • Public invite-accept flow.
  • Health probes for deploy readiness.

What's excluded ​

  • /v1/admin/** — operator dashboard endpoints.
  • /v1/platform/** — Spotlight super-admin surface.
  • /v1/inbound/** — webhook receivers (gated by shared secret; documenting them just invites probing).
  • /v1/sdk/help/attachments/{id} — per-thread signed-URL streams, not something to drop in Postman.
  • The internal Swagger UI at /docs and the raw /openapi.json.

Where to fetch it ​

bash
curl https://spotlight.<your-domain>/api/v1/openapi.json

Drop the URL into:

  • Postman → File → Import → URL
  • Insomnia → Application → Preferences → Data → Import
  • SwaggerHub → New API → Import from URL
  • Stoplight → Import from URL

Or render it inline below — pick your client.

Versioning ​

The OpenAPI version field tracks spotlight.__version__ so a doc fetched today matches the SDK + API that shipped together. We bump the minor version when adding endpoints; major version on a breaking change. See SDK Versioning for the full contract.

Authentication ​

Every endpoint listed in the doc accepts one of:

  • X-API-Key: <tenant-or-project-key> — the standard SDK path.
  • Authorization: Bearer <jwt> — when the host page is forwarding an end-user JWT (used by the help thread auth + identity claims).

See Authentication for the full key / JWT mechanics, scopes, and how to mint per-project keys from the dashboard.

Spotlight