API Documentation

GET /auth

▼

Description

Redirect to Twitch OAuth authorization

DELETE /connections/trakt Auth Required

▼

Description

Removes the authenticated user's linked Trakt account.

Examples

Delete the linked Trakt account

DELETE /connections/trakt
Authorization: Bearer <your-api-token>

{
  "success": true
}

No Trakt connection to delete

DELETE /connections/trakt
Authorization: Bearer <your-api-token>

{
  "error": "No Trakt connection found."
}

GET /connections/trakt Auth Required

▼

Description

Returns the authenticated user's linked Trakt account information.

Examples

Get the linked Trakt account

GET /connections/trakt
Authorization: Bearer <your-api-token>

{
  "connection": {
    "platformUsername": "my-trakt-username",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  }
}

No Trakt account linked

GET /connections/trakt
Authorization: Bearer <your-api-token>

{
  "connection": null
}

POST /connections/trakt Auth Required

▼

Description

Links a Trakt account to the authenticated user. `platformUsername` must be the user's Trakt slug (e.g. `my-trakt-username`), which can be found on their Trakt profile URL.

Examples

Link a Trakt account

POST /connections/trakt
Authorization: Bearer <your-api-token>
Content-Type: application/json

{
  "platformUsername": "my-trakt-username"
}

{
  "connection": {
    "platformUsername": "my-trakt-username",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-01-01T00:00:00.000Z"
  }
}

PUT /connections/trakt Auth Required

▼

Description

Updates the authenticated user's linked Trakt account. `platformUsername` must be the user's Trakt slug (e.g. `my-trakt-username`), which can be found on their Trakt profile URL.

Examples

Update a linked Trakt account

PUT /connections/trakt
Authorization: Bearer <your-api-token>
Content-Type: application/json

{
  "platformUsername": "my-new-trakt-username"
}

{
  "connection": {
    "platformUsername": "my-new-trakt-username",
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-06-01T00:00:00.000Z"
  }
}

No Trakt connection to update

PUT /connections/trakt
Authorization: Bearer <your-api-token>

{
  "error": "No Trakt connection found. Use POST to create one."
}

GET /eventBadges

▼

Description

Returns all current and upcoming Twitch event badges

Examples

Get event badges

GET /eventBadges

{
  "badges": [
    {
      "id": "ditto",
      "name": "Ditto",
      "streamdatabaseUrl": "https://www.streamdatabase.com/twitch/global-badges/ditto/1",
      "imageUrl": "https://static-cdn.jtvnw.net/badges/v1/abc123/3",
      "startAt": "2026-01-01T00:00:00.000Z",
      "endAt": "2026-12-31T23:59:59.000Z",
      "free": true
    }
  ]
}

GET /health

▼

Description

Returns service and dependency health plus runtime metrics. Responds 200 when every probe is up and 503 when any probe is down.

Examples

All services and dependencies up (HTTP 200)

GET /health

{
  "status": "ok",
  "services": {
    "api": "up",
    "chat": "up",
    "firehose": "up",
    "streams": "up",
    "redirects": "up",
    "proxy": "up"
  },
  "dependencies": {
    "database": "up",
    "nats": "up"
  },
  "uptime": "2h 34m",
  "memory": "156 MB",
  "cpu": "2.5%",
  "channelsJoined": 42,
  "firehoseClients": 3,
  "activeStreams": 2,
  "proxiedRequests": 1042,
  "msgsPerMin": 1234,
  "sessionMessages": 50000,
  "commandsExecuted": 312,
  "bansIssued": 7,
  "totalUsers": 280000,
  "permanentChannels": 280000,
  "temporaryChannels": 0,
  "monitoredUsers": 12,
  "liveChannels": 12,
  "shards": [
    {
      "index": 0,
      "joinedChannels": 2800,
      "wantedChannels": 2800,
      "desync": 0,
      "messageCount": 18500,
      "reconnectCount": 0,
      "failedJoinCount": 0
    }
  ]
}

Chat service down (HTTP 503)

GET /health

{
  "status": "degraded",
  "services": {
    "api": "up",
    "chat": "down",
    "firehose": "up",
    "streams": "up",
    "redirects": "up",
    "proxy": "up"
  },
  "dependencies": {
    "database": "up",
    "nats": "up"
  },
  "uptime": "N/A",
  "memory": "N/A",
  "cpu": "N/A",
  "channelsJoined": 0,
  "firehoseClients": 3,
  "activeStreams": 2,
  "proxiedRequests": 1042,
  "msgsPerMin": 0,
  "sessionMessages": 0,
  "commandsExecuted": 0,
  "bansIssued": 0,
  "totalUsers": 280000,
  "permanentChannels": 280000,
  "temporaryChannels": 0,
  "monitoredUsers": 12,
  "liveChannels": 12,
  "shards": []
}

DELETE /proxy/urls Auth Required Moderator

▼

Description

Removes one of the authenticated user's whitelisted proxy origins. The url is normalized to its origin before matching.

Examples

Remove a whitelisted origin

DELETE /proxy/urls
Authorization: Bearer <your-api-token>
Content-Type: application/json

{
  "url": "https://example.com"
}

{
  "success": true
}

GET /proxy/urls Auth Required

▼

Description

Lists the proxy origins whitelisted by the authenticated user.

Examples

List your whitelisted proxy origins

GET /proxy/urls
Authorization: Bearer <your-api-token>

{
  "urls": [
    {
      "origin": "https://example.com",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

POST /proxy/urls Auth Required Moderator

▼

Description

Whitelists a URL's origin (scheme + host + port) for the proxy service. Any path under a whitelisted origin becomes proxyable via the proxy server's ?url= parameter. The entry is stored against the authenticated user.

Examples

Whitelist an origin for proxying

POST /proxy/urls
Authorization: Bearer <your-api-token>
Content-Type: application/json

{
  "url": "https://example.com/some/page"
}

{
  "proxyUrl": {
    "origin": "https://example.com",
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
}

POST /reboot Auth Required Admin

▼

Description

Reboots the VM.

Examples

Reboot the VM with valid authentication

POST /reboot
Authorization: Bearer <your-api-token>

{
  "status": "rebooting",
  "message": "VM reboot initiated"
}

Unauthorized request without valid token

POST /reboot

{
  "error": "Unauthorized"
}

POST /redirects Auth Required Admin

▼

Description

Creates a new URL redirect entry. Admins and above can access this endpoint. An optional custom slug can be provided; if omitted, one is auto-generated. If a redirect for the given URL already exists, it is returned.

Examples

Create a redirect with auto-generated slug

POST /redirects
Authorization: Bearer <your-api-token>
Content-Type: application/json

{
  "url": "https://example.com"
}

{
  "redirect": {
    "url": "https://r.example.com/a1b2c3d4",
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}

Create a redirect with a custom slug

POST /redirects
Authorization: Bearer <your-api-token>
Content-Type: application/json

{
  "url": "https://example.com",
  "slug": "my-link"
}

{
  "redirect": {
    "url": "https://r.example.com/my-link",
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}

Returns existing redirect when URL already has one

POST /redirects
Authorization: Bearer <your-api-token>
Content-Type: application/json

{
  "url": "https://example.com"
}

{
  "redirect": {
    "url": "https://r.example.com/a1b2c3d4",
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}

POST /restart Auth Required Admin

▼

Description

Restarts the chat service (the Twitch bot) by asking it to exit over NATS; its supervisor starts it again.

Examples

Restart the bot with valid authentication

POST /restart
Authorization: Bearer <your-api-token>

{
  "status": "restarting",
  "message": "Chat service restart initiated"
}

Chat service unreachable over NATS

POST /restart
Authorization: Bearer <your-api-token>

{
  "error": "Chat service unreachable"
}

DELETE /streamKey Auth Required

▼

Description

Removes the stream key for the authenticated user.

Examples

Delete the stream key

DELETE /streamKey
Authorization: Bearer <your-api-token>

{
  "success": true
}

No stream key to delete

DELETE /streamKey
Authorization: Bearer <your-api-token>

{
  "error": "No stream key found."
}

POST /streamKey Auth Required

▼

Description

Stores a stream key for the authenticated user.

Examples

Store a stream key

POST /streamKey
Authorization: Bearer <your-api-token>
Content-Type: application/json

{
  "streamKey": "live_abc123..."
}

{
  "success": true
}

PUT /streamKey Auth Required

▼

Description

Updates the stream key for the authenticated user.

Examples

Update a stream key

PUT /streamKey
Authorization: Bearer <your-api-token>
Content-Type: application/json

{
  "streamKey": "live_xyz789..."
}

{
  "success": true
}

No stream key to update

PUT /streamKey
Authorization: Bearer <your-api-token>

{
  "error": "No stream key found. Use POST to create one."
}

GET /user

▼

Description

Returns information about a Twitch user. Accepts id or name query parameter.

Examples

Get user info by ID

GET /user?id=123456789

{
  "id": "123456789",
  "login": "farty",
  "createdAt": "2011-03-16T17:06:00Z",
  "level": {
    "name": "Moderator",
    "level": 2
  },
  "knownNameCount": 2
}

Get user info by username

GET /user?name=farty

{
  "id": "123456789",
  "login": "farty",
  "createdAt": "2011-03-16T17:06:00Z",
  "level": {
    "name": "User",
    "level": 1
  },
  "knownNameCount": 0
}

Error when neither id nor name is provided

GET /user

{
  "error": "id or name parameter is required"
}

GET /user/lastWatched

▼

Description

Returns the last watched movie or TV episode for a specific Twitch user via their linked Trakt account. Accepts id or name query parameter.

Examples

Last watched episode for a user by ID

GET /user/lastWatched?id=123456789

{
  "type": "episode",
  "watched_at": "2025-11-22T10:00:00Z",
  "show": {
    "title": "Breaking Bad",
    "year": 2008
  },
  "episode": {
    "season": 3,
    "number": 7,
    "title": "One Minute"
  },
  "movie": null
}

Last watched movie for a user by username

GET /user/lastWatched?name=farty

{
  "type": "movie",
  "watched_at": "2025-10-15T08:30:00Z",
  "movie": {
    "title": "Inception",
    "year": 2010
  },
  "show": null,
  "episode": null
}

Error when neither id nor name is provided

GET /user/lastWatched

{
  "error": "id or name parameter is required"
}

GET /user/live

▼

Description

Returns whether a Twitch user is currently live.

Examples

Get live status by user ID

GET /user/live?id=123456789

{
  "live": true
}

Get live status by username

GET /user/live?name=testuser

{
  "live": false
}

Error when neither id nor name is provided

GET /user/live

{
  "error": "id or name parameter is required"
}

GET /user/missingEventBadges

▼

Description

Returns Twitch event badges that a specific user does not currently have. Accepts id or name query parameter.

Examples

Get missing event badges by username

GET /user/missingEventBadges?name=farty

{
  "badges": [
    {
      "id": "ditto",
      "name": "Ditto",
      "streamdatabaseUrl": "https://www.streamdatabase.com/twitch/global-badges/ditto/1",
      "imageUrl": "https://static-cdn.jtvnw.net/badges/v1/abc123/3",
      "startAt": "2026-01-01T00:00:00.000Z",
      "endAt": "2026-12-31T23:59:59.000Z",
      "free": true
    }
  ]
}

GET /user/monitored

▼

Description

Returns whether a Twitch user is currently monitored.

Examples

Get monitored status by user ID

GET /user/monitored?id=123456789

{
  "monitored": true,
  "reason": "Discord Scammer Bot"
}

Get monitored status by username

GET /user/monitored?name=testuser

{
  "monitored": false,
  "reason": null
}

Error when neither id nor name is provided

GET /user/monitored

{
  "error": "id or name parameter is required"
}

GET /user/names

▼

Description

Returns known usernames for a Twitch user. Accepts id or name query parameter.

Examples

Get name changes by user ID

GET /user/names?id=123456789

{
  "names": [
    {
      "id": "1",
      "user_id": "123456789",
      "name": "oldusername",
      "first_timestamp": "2024-01-01T00:00:00.000Z",
      "last_timestamp": "2025-11-22T10:00:00.000Z"
    }
  ]
}

Get name changes by username

GET /user/names?name=farty

{
  "names": []
}

Error when neither id nor name is provided

GET /user/names

{
  "error": "id or name parameter is required"
}

API Docs

API Information