Lynup Integration API v1

The read-only Integration API lets broadcast tools observe a creator's current session and public queue without exposing viewer emails, payment details, private notes, or account data.

Base URL
Production requests use https://lynup.xyz/api/v1.

Quick start

1. Open Dashboard → Settings → Broadcast → Developer Integrations.
2. Name the integration and create a token.
3. Copy the token immediately. Lynup only displays the full value once.
4. Send it as a Bearer token with every API request.

Authorization: Bearer lynup_your_token

Tokens begin with lynup_, are stored as hashes, and can be revoked individually. Keep them out of public URLs, screenshots, source control, and shared OBS scene collections.

Authentication

Every endpoint requires an Authorization header. Tokens currently include the read-only session:read and queue:read scopes.

curl -H "Authorization: Bearer $LYNUP_TOKEN" \
  https://lynup.xyz/api/v1/live

Authentication errors

• 401 Unauthorized — the header is missing, malformed, revoked, or contains an unknown token.
• 403 Forbidden — the token does not include a required scope.
• 429 Too Many Requests — the client exceeded the endpoint rate limit.

Get live state

GET /api/v1/live returns a snapshot of the creator's active session and public queue fields. Use this endpoint when starting a client, recovering state, or building a status display.

{
  "apiVersion": "1",
  "generatedAt": "2026-08-10T20:14:03.000Z",
  "live": true,
  "creator": {
    "name": "Example Creator",
    "username": "example"
  },
  "session": {
    "id": 42,
    "title": "Music Review",
    "status": "live",
    "startedAt": "2026-08-10T20:00:00.000Z",
    "endedAt": null
  },
  "submissions": [{
    "id": 519,
    "artistName": "Example Artist",
    "trackTitle": "Example Track",
    "chapterName": "Example Track — Example Artist",
    "tier": "free",
    "status": "playing",
    "position": 1,
    "createdAt": "2026-08-10T20:05:00.000Z"
  }]
}

When no session is active, live is false, session is null, and submissions is an empty array.

Listen for events

GET /api/v1/events is a Server-Sent Events stream. It sends discrete persisted events instead of repeatedly sending the entire queue. Events are retained for seven days.

id: 184
event: lynup.submission.playing
data: {"apiVersion":"1","id":184,"type":"lynup.submission.playing","createdAt":"2026-08-10T20:14:03.000Z","data":{"sessionId":42,"submissionId":519,"artistName":"Example Artist","trackTitle":"Example Track","chapterName":"Example Track — Example Artist","status":"playing","position":1}}

Reconnect safely

Save the last event ID after successfully handling an event. Reconnect using the Last-Event-ID header. Clients that cannot set that header may use ?after=184.

• A new connection without a cursor begins with new events.
• Use ?after=0 only when intentionally reading retained history.
• Delivery is at-least-once. Remember processed IDs and ignore duplicates.

Event catalog

Session events

• lynup.session.created
• lynup.session.started
• lynup.session.paused
• lynup.session.resumed
• lynup.session.ended

Submission events

• lynup.submission.received
• lynup.submission.queued
• lynup.submission.playing
• lynup.submission.completed
• lynup.submission.skipped

Clients should ignore event types they do not recognize. Lynup may add new events within v1.

OBS chapter markers

For Hybrid MP4 chapter markers, listen for lynup.submission.playing. Verify that OBS is recording, then pass data.chapterName to OBS WebSocket's CreateRecordChapter request.

1. Receive the playing event.
2. Check whether its event ID was already processed.
3. Read data.chapterName.
4. Run the OBS CreateRecordChapter action.
5. Store the event ID only after the OBS action succeeds.

The Lynup API supplies the event and chapter name. Your Streamer.bot action, browser bridge, or OBS script must make the local OBS WebSocket request.

Browser clients and CORS

The API supports CORS for Bearer-token clients, including local-file OBS Browser Sources. Use streaming fetch() for the event endpoint because the browser's native EventSource interface cannot attach an Authorization header.

Versioning and compatibility

Fields and event types may be added within v1. Existing fields and event meanings will not be removed or changed without a new API version. Clients should ignore unknown JSON fields and unknown event names.

---

Current API status: Version 1 is read-only. It can observe sessions and queues but cannot reorder submissions, change playback state, or control a live session.