Navigation
Developer Docs
The Spotlight REST API provides programmatic access to experiences, embeds, and workspace configuration. All endpoints are relative to your Spotlight instance URL.
The public API authenticates via API keys. Create and manage keys in Settings → API Keys in the dashboard. Pass the key as part of the URL path.
curl https://spotlight.scaleflex.com/api/v1/picker/YOUR_API_KEY/experiences/api/v1/picker/:apiKey/experiencesReturns a paginated list of published experiences accessible by the given API key. Returns metadata only (no configs).
| Query Param | Type | Description |
|---|---|---|
| type | string | Comma-separated type filter: HOTSPOT, SPIN_360, BEFORE_AFTER, TOUR, THREE_D_VIEW |
| status | string | Status filter (default: PUBLISHED) |
| search | string | Case-insensitive name search |
| skip | number | Pagination offset (default: 0) |
| take | number | Page size (default: 50, max: 100) |
{ "data": [ { "id": "exp_abc123", "type": "HOTSPOT", "name": "Product Hotspot", "description": "Interactive product callouts", "status": "PUBLISHED", "thumbnail": "https://cdn.scaleflex.it/...", "tags": ["product", "interactive"], "updatedAt": "2025-01-20T14:00:00Z" } ], "total": 42, "skip": 0, "take": 50, "countsByType": { "HOTSPOT": 20, "SPIN_360": 12, "BEFORE_AFTER": 10 }, "totalAll": 42}All error responses follow a consistent format:
{ "error": { "code": "NOT_FOUND", "message": "Experience not found" }}| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Request body failed validation |
| 401 | UNAUTHORIZED | Missing or invalid session / API key |
| 403 | FORBIDDEN | Insufficient permissions |
| 404 | NOT_FOUND | Resource not found |
| 429 | RATE_LIMITED | Too many requests |
API requests are rate-limited per workspace. Current limits:
| Endpoint | Limit |
|---|---|
| Picker API (public) | 60 req/min per API key |
| Embed rendering | No limit (CDN-cached) |
Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.