SpotiQueue Public API (v1)

Run your own guest page and call SpotiQueue from your backend. Everything the built-in guest queue and bigscreen do is available: search, queue, undo, voting, now playing with lyrics, album art, and hosted guest sign-in.

The API is included with Pro. Each account can create up to ten secret keys, each with its own queue permissions, managed in Account → Developer API (https://dash.spotiqueue.com/account?p=developer-api).

• Base URL: https://spotiqueue.com/api/v1
• Content type: application/json
• Versioning: /api/v1 is stable. Breaking changes ship as /api/v2.
• This page, always current: https://spotiqueue.com/docs/public-api

Server-side only. The key is a bearer secret. Put it on your backend and have your frontend talk to your backend. Never ship the key to a browser or a mobile app bundle.

---

1. Authentication

Send the key on every request:

Authorization: Bearer sq_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Pick the queue with the slug in the path:

POST https://spotiqueue.com/api/v1/my-party/queue/search

A request is accepted when all four hold:

1. The key is valid and not revoked.
2. The account has active Pro.
3. The slug resolves to a queue that account owns.
4. That queue is ticked for this key in Account → Developer API → Queue permissions.

If a key has no queues ticked, it cannot reach any queue. This is deliberate: a leaked key cannot touch a queue you did not explicitly enable for that key.

Identifying guests

Every per-guest call carries two headers. The fingerprint id names the device; the device token proves your backend registered that device with this API key.

X-Guest-Fingerprint: 9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f
X-Guest-Device-Token: a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456

Get both from POST /api/v1/{slug}/fingerprint/generate (first visit) or from POST /api/platform/public-api/guest-auth/exchange after hosted OAuth. Store them against that visitor in your own session and replay them on later guest-scoped calls. The fingerprint must be 16 to 64 hex characters. The device token is 64 hex characters (32 random bytes). Treat the token like a password: never expose it in the browser or in client-side JavaScript.

A device token is bound to the API key that minted it. Another key on the same account cannot act as that guest, even if it knows the fingerprint id.

Cooldowns, undo eligibility, "my songs", and vote state are all keyed to the fingerprint id, so reusing one id for every visitor makes them share one cooldown budget.

---

2. Endpoints

All paths below are relative to https://spotiqueue.com/api/v1/{slug}.

Not on the API: instance admin, owner Spotify OAuth, platform routes, and the provider /login and /unlink routes. Anything else under /api/v1 returns 404 endpoint_not_available.

Examples

Read queue settings so your UI knows which controls to render:

curl https://spotiqueue.com/api/v1/my-party/config/public \
  -H "Authorization: Bearer $SPOTIQUEUE_API_KEY"

{
  "queueing_enabled": true,
  "search_ui_enabled": true,
  "url_input_enabled": true,
  "voting_enabled": true,
  "voting_downvote_enabled": true,
  "prequeue_enabled": false,
  "aura_enabled": false,
  "lyrics_delay_seconds": 0,
  "instance_slug": "my-party",
  "instance_name": "Friday Rooftop",
  "theme": {
    "enabled": true,
    "colors": {
      "light": {
        "background": "#f6f8f7",
        "foreground": "#0c120f",
        "card": "#ffffff",
        "primary": "#1db954",
        "border": "#d8dfdb",
        "muted": "#5e6e66",
        "accent": "#e2e9e6"
      },
      "dark": {
        "background": "#0a100d",
        "foreground": "#f4f6f5",
        "card": "#0f1512",
        "primary": "#1db954",
        "border": "#242e29",
        "muted": "#96a69e",
        "accent": "#1f2924"
      }
    }
  }
}

theme.colors is null unless the host has an active custom theme (Pro only). When present, each mode (light, dark) holds hex colour values and either mode may be absent; apply the matching mode to your own UI or ignore the field. Treat any field here as additive: ignore fields you do not know.

Register a new visitor:

curl -X POST https://spotiqueue.com/api/v1/my-party/fingerprint/generate \
  -H "Authorization: Bearer $SPOTIQUEUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"Ada"}'

{
  "ready": true,
  "fingerprint_id": "9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f",
  "guest_device_token": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
  "username": "Ada",
  "requires_username": false,
  "requires_google_auth": false,
  "requires_github_auth": false,
  "requires_discord_auth": false,
  "guest_authenticated": true
}

To update an existing visitor (for example to set their name later), replay their X-Guest-Fingerprint and X-Guest-Device-Token on the same call. guest_device_token is only returned again when a new token is minted (first register or OAuth exchange).

Search and queue:

curl -X POST https://spotiqueue.com/api/v1/my-party/queue/search \
  -H "Authorization: Bearer $SPOTIQUEUE_API_KEY" \
  -H "X-Guest-Fingerprint: 9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f" \
  -H "X-Guest-Device-Token: $GUEST_DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"blue monday"}'

curl -X POST https://spotiqueue.com/api/v1/my-party/queue/add \
  -H "Authorization: Bearer $SPOTIQUEUE_API_KEY" \
  -H "X-Guest-Fingerprint: 9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f" \
  -H "X-Guest-Device-Token: $GUEST_DEVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"track_id":"3AhXZa8sUQht0UEdBJgpGc"}'

queue/add returns { "success": true, "queue_item_id": "…", "track": { … } }. Keep the queue_item_id: it is what queue/undo and queue/vote take.

POST /queue/vote returns { "userVote": 1 | -1 | null, "votes": <net for this item>, "queue_item_id": "…", "votesByQueueItem": { "<queue_item_id>": <net>, … } }. The votesByQueueItem map lists net scores for every queued item on the instance so your UI can refresh all counters from one response. Guests cannot vote on a row they queued themselves (400 with { "error": "You cannot vote on your own song." }).

Building a bigscreen

GET /now-playing returns the current track and, when we have them, synced lyrics:

{
  "track": {
    "id": "3AhXZa8sUQht0UEdBJgpGc",
    "name": "Blue Monday",
    "artists": "New Order",
    "album_art": "https://i.scdn.co/image/…",
    "duration_ms": 448000,
    "progress_ms": 61200,
    "is_playing": true,
    "lyrics": { "synced": true, "lines": [{ "time": 12.4, "text": "…" }] }
  }
}

Apply lyrics_delay_seconds from /config/public as an offset when highlighting the current line. Load album art through /album-art?url=… if you sample its colours; Spotify's CDN does not send CORS headers.

---

3. Hosted guest sign-in

When the host requires guest Google, GitHub, or Discord sign-in, that sign-in must happen on SpotiQueue: each provider allows one fixed callback URL, and the guest's proof lives in cookies on our origin. Your page hands the guest over and gets them back with a code.

1. Your backend calls guest-auth/start with the queue slug and your return URL, and gets back an auth_url on spotiqueue.com.
2. You redirect the guest to auth_url.
3. The guest picks a username and signs in with the providers the host requires.
4. We redirect the guest to return_to?code=…&state=….
5. Your backend calls guest-auth/exchange with that code and the same API key that called guest-auth/start. The response includes fingerprint_id, guest_device_token, and linked provider names.

Before you start: save your return URL in Account → Developer API → Guest sign-in redirect URLs (HTTPS, or http://localhost / http://127.0.0.1 for local dev; up to 15). return_to must match a saved URL on origin and path; query strings are ignored when matching.

Start

POST https://spotiqueue.com/api/platform/public-api/guest-auth/start
Authorization: Bearer sq_live_…

{
  "instance_slug": "my-party",
  "return_to": "https://your-site.example/party/callback",
  "state": "your-own-session-token"
}

{
  "auth_url": "https://spotiqueue.com/my-party/guest-auth?session=…",
  "expires_in": 900
}

Send the guest to auth_url. The page collects a username and any required provider sign-in, then redirects to return_to?code=…&state=…. state is echoed back exactly as you sent it; use it to tie the callback to your own session.

Exchange

POST https://spotiqueue.com/api/platform/public-api/guest-auth/exchange
Authorization: Bearer sq_live_…

{ "code": "…" }

{
  "instance_slug": "my-party",
  "fingerprint_id": "9f1c2d3e4a5b6c7d8e9f0a1b2c3d4e5f",
  "guest_device_token": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
  "guest": {
    "google": { "username": "[email protected]", "avatar": "https://…" },
    "github": null,
    "discord": null
  }
}

Codes are single use and expire after 5 minutes. Store fingerprint_id and guest_device_token against your session and send both headers on guest-scoped calls.

When you need it

Read /config/public and /fingerprint/generate first. If a response has requires_google_auth, requires_github_auth, or requires_discord_auth set, or a write returns 401, run the hosted flow. If none are set, fingerprint/generate alone is enough.

---

4. Rate limits

Budgets are per account, not per IP, so all your guests share them. Every response carries standard RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers.

Over budget returns 429 with { "error": "…", "code": "rate_limited" }.

Practical guidance for a party-sized crowd:

• Poll queue/current and now-playing from your server on a shared timer (about every 2 to 3 seconds each) and fan the result out to your visitors. Do not let each browser poll SpotiQueue through your proxy.
• Debounce search to roughly one request per 400 ms per visitor.
• Instance-level cooldowns still apply on top of these limits: queue/add can return 429 with cooldown_remaining because of the host's cooldown settings, which is a different condition from hitting the API budget.

---

5. Errors

Errors are JSON: { "error": "human readable", "code": "machine_readable" }. code is absent on some validation errors inherited from the guest routes.

Guest-facing conditions come back with the same shape the built-in UI sees:

Surface these to your visitors rather than retrying: most are decisions the host made.

---

6. Versioning and breaking changes

/api/v1 is stable. Additive changes (new fields, new endpoints) ship without a version bump, so ignore unknown fields rather than failing on them.

Anything that could break an existing integration is announced ahead of the change:

• The release note is flagged as a breaking Public API change.
• Your release notes webhook payload carries "apiBreaking": true and publicApiDocUrl.
• Signed-in key holders see a callout in the release notes dialog on the dashboard.
• Operators may optionally email accounts with a live API key when publishing (off by default).

Removing or changing the meaning of an existing field means a new version, /api/v2, with /api/v1 kept alive during the migration window.

---

7. Checklist

1. Turn on Pro, then open Account → Developer API.
2. Create one or more keys and store each secret on your server.
3. Tick which queues each key may reach in the permission matrix.
4. Save your guest sign-in redirect URLs if the host requires provider sign-in.
5. Call /config/public to shape your UI.
6. Call /fingerprint/generate per visitor (or run hosted auth). Store fingerprint_id and guest_device_token, then replay both as X-Guest-Fingerprint and X-Guest-Device-Token.
7. Poll reads on a shared server-side timer and fan out to your visitors.
8. Subscribe a release notes webhook so breaking changes reach your team.