API Docs

8f623f8b4ee4e7e1c12e6698a

← Docs

📡 API Information

Base URL: https://api.catquery.com

GET /auth
▼
Description
Redirect to Twitch OAuth authorization
GET /auth/callback
▼
Description
Handle OAuth callback from Twitch
GET /chatSearchBlob
▼
Description
Retrieves a chat search filter blob by its SHA-256-derived ID.
Examples
Get a filter blob by ID
GET /chatSearchBlob?id=3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c 
{
  "blob": "from:user1 in:channel1"
}
ID not found
GET /chatSearchBlob?id=0000000000000000000000000000000000000000000000000000000000000000 
{
  "error": "Not found"
}
Missing id parameter
GET /chatSearchBlob 
{
  "error": "id parameter is required"
}
POST /chatSearchBlob
▼
Description
Saves a chat search filter blob and returns a stable SHA-256-derived ID. Identical blobs always return the same ID.
Examples
Save a filter blob
POST /chatSearchBlob Content-Type: application/json { "blob": "from:user1 in:channel1" } 
{
  "id": "3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c"
}
Missing blob field
POST /chatSearchBlob Content-Type: application/json {} 
{
  "error": "blob is required"
}
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": "myTraktSlug",
    "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": "myTraktSlug" } 
{
  "connection": {
    "platformUsername": "myTraktSlug",
    "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": "myNewTraktSlug" } 
{
  "connection": {
    "platformUsername": "myNewTraktSlug",
    "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."
}
DELETE /connections/trakt 🔒 Auth Required
▼
Description
Removes the authenticated user's linked Trakt account.
Examples
Delete the linked Trakt account
DELETE /connections/trakt Authorization: ****** 
{
  "success": true
}
No Trakt connection to delete
DELETE /connections/trakt Authorization: ****** 
{
  "error": "No Trakt connection found."
}
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"
    }
  ]
}
GET /health
▼
Description
Returns the health status and metrics of the bot including uptime, memory, CPU usage, channel counts, WebSocket connections, and messages per minute.
Examples
Get health metrics without dependencies (basic status)
GET /health 
{
  "status": "ok",
  "uptime": "N/A",
  "memory": "N/A",
  "cpu": "N/A",
  "channelsJoined": 0,
  "totalChannels": 0,
  "ws": 0,
  "msgsPerMin": 0
}
Get health metrics with full bot status
GET /health 
{
  "status": "ok",
  "uptime": "2h 34m",
  "memory": "156.3 MB",
  "cpu": "2.5%",
  "channelsJoined": 42,
  "totalChannels": 50,
  "ws": 3,
  "msgsPerMin": 1234
}
GET /lastWatched
▼
Description
Returns the last watched movie or TV episode for a specific Twitch user via their linked Trakt account. Requires userId query parameter.
Examples
Last watched episode for a user
GET /lastWatched?userId=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
GET /lastWatched?userId=123456789 
{
  "type": "movie",
  "watched_at": "2025-10-15T08:30:00Z",
  "movie": {
    "title": "Inception",
    "year": 2010
  },
  "show": null,
  "episode": null
}
Error when userId parameter is missing
GET /lastWatched 
{
  "error": "userId parameter is required"
}
GET /nameChanges
▼
Description
Returns the username change history for a specific Twitch user. Requires userId query parameter.
Examples
Get username change history for a user
GET /nameChanges?userId=123456789 
{
  "nameChanges": [
    {
      "id": 1,
      "user_id": "123456789",
      "old_username": "oldusername",
      "new_username": "newusername",
      "changed_at": "2025-11-22T10:00:00Z"
    },
    {
      "id": 2,
      "user_id": "123456789",
      "old_username": "previousname",
      "new_username": "oldusername",
      "changed_at": "2025-10-15T08:30:00Z"
    }
  ]
}
Error when userId parameter is missing
GET /nameChanges 
{
  "error": "userId parameter is required"
}
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 bot gracefully.
Examples
Restart the bot with valid authentication
POST /restart Authorization: Bearer <your-api-token> 
{
  "status": "restarting",
  "message": "Bot restart initiated"
}
Unauthorized request without valid token
POST /restart 
{
  "error": "Unauthorized"
}
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."
}
DELETE /streamKey 🔒 Auth Required
▼
Description
Removes the stream key for the authenticated user.
Examples
Delete the stream key
DELETE /streamKey Authorization: ****** 
{
  "success": true
}
No stream key to delete
DELETE /streamKey Authorization: ****** 
{
  "error": "No stream key found."
}