API Docs

docs.catquery.com

← Docs

API Information

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

Endpoints with a permission require authentication and that permission. Public endpoints require neither.

GET /admin/audit Auth Required Restricted
▼
Description
Returns the audit log.
Examples
Get recent audit events
GET /admin/audit?category=http Authorization: Bearer <your-api-token> 
{
  "generatedAt": "2026-08-18T12:00:00.000Z",
  "from": "2026-08-17T12:00:00.000Z",
  "to": "2026-08-18T12:00:00.000Z",
  "summary": {
    "totalEvents": 0,
    "requests": 0,
    "uniqueIps": 0,
    "clientErrors": 0,
    "serverErrors": 0,
    "rateLimited": 0,
    "bansIssued": 0,
    "firehoseOpened": 0,
    "firehoseRejected": 0
  },
  "breakdowns": {
    "services": [],
    "countries": [],
    "statuses": [],
    "reasons": [],
    "eventTypes": []
  },
  "events": [],
  "eventPage": {
    "nextCursor": null,
    "pageSize": 25
  }
}

Permission: system.view.audit

GET /admin/bans Auth Required Restricted
▼
Description
Lists Twitch bans successfully issued by the bot.
Examples
List recent bot bans
GET /admin/bans Authorization: Bearer <your-api-token> 
{
  "total": 1,
  "bans": [
    {
      "id": "42",
      "bannedAt": "2026-08-21T12:00:00.000Z",
      "channelUserId": "123",
      "channelName": "somechannel",
      "targetUserId": "456",
      "targetUsername": "badactor",
      "reason": "Spam",
      "durationSeconds": null,
      "source": "crossban"
    }
  ],
  "nextCursor": null,
  "pageSize": 50
}

Permission: admin.view.bans

POST /admin/channel/setting Auth Required Restricted
▼
Description
Sets a channel setting value for a user's channel.
Examples
Enable commands
POST /admin/channel/setting Authorization: Bearer <your-api-token> Content-Type: application/json { "userId": "123456789", "setting": "commands_allowed", "value": 1 } 
{
  "success": true,
  "userId": "123456789",
  "setting": "commands_allowed",
  "value": 1
}

Permission: admin.manage.channels

POST /admin/crossban Auth Required Restricted
▼
Description
Bans or unbans a user across every opted-in crossban channel.
Examples
Crossban a user
POST /admin/crossban Authorization: Bearer <your-api-token> Content-Type: application/json { "userId": "123456789", "reason": "chatter evasion" } 
{
  "success": true,
  "userId": "123456789",
  "action": "ban",
  "result": {
    "totalChannels": 50,
    "successCount": 47,
    "alreadyBannedCount": 2,
    "notBannedCount": 0,
    "errorCount": 1
  }
}
Remove a crossban from a user
POST /admin/crossban Authorization: Bearer <your-api-token> Content-Type: application/json { "userId": "123456789", "action": "unban" } 
{
  "success": true,
  "userId": "123456789",
  "action": "unban",
  "result": {
    "totalChannels": 50,
    "successCount": 47,
    "alreadyBannedCount": 0,
    "notBannedCount": 3,
    "errorCount": 0
  }
}

Permission: admin.manage.crossbans

DELETE /admin/ipBans Auth Required Restricted
▼
Description
Removes an IP ban.
Examples
Remove an IP ban
DELETE /admin/ipBans?ip=192.168.1.1 Authorization: Bearer <your-api-token> 
{
  "success": true,
  "ip": "192.168.1.1"
}

Permission: admin.manage.ip-bans

GET /admin/ipBans Auth Required Restricted
▼
Description
Lists banned IP addresses.
Examples
List IP bans
GET /admin/ipBans?search=192.168.1.1 Authorization: Bearer <your-api-token> 
{
  "total": 1,
  "bans": [
    {
      "ip": "192.168.1.1",
      "permanent": false,
      "iteration": 2,
      "bannedAt": "2026-08-20T12:00:00.000Z",
      "expiresAt": "2026-08-20T12:05:00.000Z"
    }
  ],
  "nextCursor": null,
  "pageSize": 100
}

Permission: admin.manage.ip-bans

PATCH /admin/ipBans Auth Required Restricted
▼
Description
Changes the expiry of an active temporary IP ban.
Examples
Extend a temporary ban to 30 minutes
PATCH /admin/ipBans Authorization: Bearer <your-api-token> Content-Type: application/json { "ip": "192.168.1.1", "durationMinutes": 30 } 
{
  "success": true,
  "ip": "192.168.1.1",
  "iteration": 2,
  "expiresAt": "2026-08-20T12:30:00.000Z"
}

Permission: admin.manage.ip-bans

POST /admin/ipBans Auth Required Restricted
▼
Description
Permanently bans an IP address.
Examples
Ban an IP address
POST /admin/ipBans Authorization: Bearer <your-api-token> Content-Type: application/json { "ip": "192.168.1.1" } 
{
  "success": true,
  "ip": "192.168.1.1",
  "created": true
}

Permission: admin.manage.ip-bans

GET /admin/live-chatter-candidates Auth Required Restricted
▼
Description
Finds unmonitored live users among a channel's recent chatters.
Examples
Review live chatters from a channel
GET /admin/live-chatter-candidates?channel=examplechannel Authorization: Bearer <your-api-token> 
{
  "channel": "examplechannel",
  "messagesScanned": 1000,
  "uniqueChatters": 250,
  "candidates": [
    {
      "userId": "123456789",
      "username": "livechatter",
      "channelUrl": "https://www.twitch.tv/livechatter"
    }
  ],
  "usernames": "livechatter"
}

Permission: admin.manage.monitoring

POST /admin/monitor Auth Required Restricted
▼
Description
Adds or removes a user from the monitored users table, optionally crossbanning them in the same call.
Examples
Monitor a user
POST /admin/monitor Authorization: Bearer <your-api-token> Content-Type: application/json { "userId": "123456789", "reason": "Discord Scammer Bot" } 
{
  "success": true,
  "userId": "123456789",
  "reason": "Discord Scammer Bot"
}
Monitor a user and crossban them
POST /admin/monitor Authorization: Bearer <your-api-token> Content-Type: application/json { "userId": "123456789", "reason": "Discord Scammer Bot", "crossban": true } 
{
  "success": true,
  "userId": "123456789",
  "reason": "Discord Scammer Bot",
  "crossban": {
    "totalChannels": 50,
    "successCount": 47,
    "alreadyBannedCount": 2,
    "notBannedCount": 0,
    "errorCount": 1
  }
}
Remove a user's monitored status
POST /admin/monitor Authorization: Bearer <your-api-token> Content-Type: application/json { "userId": "123456789", "action": "unmonitor" } 
{
  "success": true,
  "userId": "123456789",
  "action": "unmonitor"
}

Permission: admin.manage.monitoring

POST /admin/monitor/bulk Auth Required Restricted
▼
Description
Resolves Twitch usernames and adds them to the monitored users table in bulk.
Examples
Monitor Twitch users in bulk
POST /admin/monitor/bulk Authorization: Bearer <your-api-token> Content-Type: application/json { "usernames": "bot1,bot2,bot3", "reason": "Mass follow bot" } 
{
  "success": true,
  "requested": 3,
  "monitored": 3,
  "notFound": [],
  "lookupIncomplete": false
}

Permission: admin.manage.monitoring

DELETE /admin/rateLimits Auth Required Restricted
▼
Description
Removes a rate limit override for a user, API key, or session.
Examples
Remove a key override and restore account/default inheritance
DELETE /admin/rateLimits?apiKeyId=42 Authorization: Bearer <your-api-token> 
{
  "success": true,
  "apiKeyId": 42
}
Remove a session override
DELETE /admin/rateLimits?sessionId=9 Authorization: Bearer <your-api-token> 
{
  "success": true,
  "sessionId": 9
}
Remove a rate limit override
DELETE /admin/rateLimits?userId=123456789 Authorization: Bearer <your-api-token> 
{
  "success": true,
  "userId": "123456789"
}

Permission: admin.manage.rate-limits

POST /admin/rateLimits Auth Required Restricted
▼
Description
Sets a rate limit override for a user, API key, or session.
Examples
Override one API key's rate limit
POST /admin/rateLimits Authorization: Bearer <your-api-token> Content-Type: application/json {"apiKeyId":42,"maxRequests":60} 
{
  "success": true,
  "apiKeyId": 42,
  "maxRequests": 60
}
Override one active session's rate limit
POST /admin/rateLimits Authorization: Bearer <your-api-token> Content-Type: application/json {"sessionId":9,"maxRequests":null} 
{
  "success": true,
  "sessionId": 9,
  "maxRequests": null
}
Give a user a custom rate limit
POST /admin/rateLimits Authorization: Bearer <your-api-token> Content-Type: application/json { "userId": "123456789", "maxRequests": 500 } 
{
  "success": true,
  "userId": "123456789",
  "maxRequests": 500
}
Give a user an unlimited rate limit
POST /admin/rateLimits Authorization: Bearer <your-api-token> Content-Type: application/json { "userId": "123456789", "maxRequests": null } 
{
  "success": true,
  "userId": "123456789",
  "maxRequests": null
}

Permission: admin.manage.rate-limits

GET /admin/streams Auth Required Restricted
▼
Description
Lists configured streams with current Twitch live status.

Permission: admin.manage.streams

POST /admin/streams/action Auth Required Restricted
▼
Description
Starts, stops, restarts, or changes a configured stream.

Permission: admin.manage.streams

GET /admin/user Auth Required Restricted
▼
Description
Returns full detail for any user by ID.
Examples
Get user details
GET /admin/user?id=123456789 Authorization: Bearer <your-api-token> 
{
  "id": "123456789",
  "username": "someuser",
  "isSuperuser": false,
  "isBanned": false,
  "names": [],
  "channel": null,
  "monitored": null,
  "apiKeys": [],
  "sessions": [],
  "rateLimit": "default"
}

Permission: admin.view.users

POST /admin/user/ban Auth Required Restricted
▼
Description
Bans or unbans an account; superuser accounts are protected.
Examples
Ban or unban an account
POST /admin/user/ban Authorization: Bearer <your-api-token> Content-Type: application/json { "userId": "123456789", "isBanned": false } 
{
  "success": true,
  "userId": "123456789",
  "isBanned": false
}

Permission: admin.manage.users

POST /admin/user/permissions Auth Required Restricted
▼
Description
Replace a user's permission values; only differences from catalog defaults are stored.

Permission: admin.manage.permissions

GET /admin/users Auth Required Restricted
▼
Description
Lists users.
Examples
List users
GET /admin/users Authorization: Bearer <your-api-token> 
{
  "users": [
    {
      "id": "123456789",
      "username": "someuser",
      "isSuperuser": false,
      "isBanned": false,
      "nameCount": 3,
      "channelType": "permanent",
      "joinEnabled": true,
      "joinFailed": false,
      "monitored": false
    }
  ],
  "total": 1,
  "nextCursor": null,
  "pageSize": 50
}

Permission: admin.view.users

DELETE /apiKeys Auth Required
▼
Description
Revokes an API key by id.
Examples
Revoke your API key
DELETE /apiKeys?id=42 Authorization: Bearer <your-api-token> 
{
  "success": true,
  "revokedId": 42
}

Permission: api-keys.revoke

GET /apiKeys Auth Required
▼
Description
Lists API keys and rate limits.
Examples
List every user's API keys (requires admin.manage.api-keys)
GET /apiKeys?all=true Authorization: Bearer <your-api-token> 
{
  "apiKeys": []
}
List your API keys
GET /apiKeys Authorization: Bearer <your-api-token> 
{
  "apiKeys": [
    {
      "id": 42,
      "name": "My integration",
      "userId": "123456789",
      "username": "someuser",
      "level": 1,
      "rateLimit": 60,
      "rateLimitOverride": "default",
      "rateLimitSource": "user",
      "createdAt": "2026-09-08T12:00:00.000Z",
      "lastUsedAt": null
    }
  ]
}

Permission: api-keys.view

POST /apiKeys Auth Required
▼
Description
Creates a named API key.
Examples
Generate an API key
POST /apiKeys Authorization: Bearer <your-api-token> Content-Type: application/json {"name":"My integration"} 
{
  "id": 42,
  "name": "My integration",
  "apiKey": "3f1c...9e2a (64 hex characters)",
  "createdAt": "2026-09-08T12:00:00.000Z"
}

Permission: api-keys.create

GET /channel Auth Required
▼
Description
Returns the caller's own channel and its self-service settings.
Examples
Get your channel settings
GET /channel Authorization: Bearer <your-api-token> 
{
  "channel": {
    "settings": {
      "commands_allowed": true,
      "moderate": false,
      "crossban": false
    },
    "defaults": {
      "commands_allowed": true,
      "moderate": false,
      "crossban": false
    }
  }
}
No channel found for the caller
GET /channel Authorization: Bearer <your-api-token> 
{
  "channel": null
}

Permission: channel.settings.view

POST /channel/setting Auth Required
▼
Description
Sets a self-service setting value for the caller's own channel.
Examples
Enable commands on your own channel
POST /channel/setting Authorization: Bearer <your-api-token> Content-Type: application/json { "setting": "commands_allowed", "value": 1 } 
{
  "success": true,
  "setting": "commands_allowed",
  "value": 1
}

Permission: channel.settings.manage

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 health and runtime metrics.
Examples
All services and dependencies up (HTTP 200)
GET /health 
{
  "status": "healthy",
  "services": {
    "api": "healthy",
    "chat-processor": "healthy",
    "chat-coordinator": "healthy",
    "chat-workers": "healthy",
    "firehose": "healthy",
    "streams": "healthy",
    "redirects": "healthy",
    "proxy": "healthy"
  },
  "dependencies": {
    "database": "healthy",
    "nats": "healthy",
    "redis": "healthy"
  },
  "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": 42,
      "wantedChannels": 42,
      "desync": 0,
      "messageCount": 18500,
      "reconnectCount": 0,
      "failedJoinCount": 0
    }
  ],
  "workers": [
    {
      "workerId": "chat-worker-1",
      "uptimeMs": 9240000,
      "memoryMb": 156,
      "cpuPercent": 2.5,
      "assigned": 42,
      "joined": 42,
      "retrying": 0,
      "joinsFailed": 0,
      "reconnectCount": 0,
      "heartbeatStatus": "healthy",
      "shards": [
        {
          "shardIndex": 0,
          "joinedChannels": 42,
          "wantedChannels": 42,
          "desync": 0,
          "messageCount": 18500,
          "reconnectCount": 0,
          "failedJoinCount": 0
        }
      ]
    }
  ]
}
Chat processor down (HTTP 503)
GET /health 
{
  "status": "down",
  "services": {
    "api": "healthy",
    "chat-processor": "down",
    "chat-coordinator": "healthy",
    "chat-workers": "healthy",
    "firehose": "healthy",
    "streams": "healthy",
    "redirects": "healthy",
    "proxy": "healthy"
  },
  "dependencies": {
    "database": "healthy",
    "nats": "healthy",
    "redis": "healthy"
  },
  "uptime": "N/A",
  "memory": "N/A",
  "cpu": "N/A",
  "channelsJoined": 42,
  "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": [
    {
      "index": 0,
      "joinedChannels": 42,
      "wantedChannels": 42,
      "desync": 0,
      "messageCount": 18500,
      "reconnectCount": 0,
      "failedJoinCount": 0
    }
  ],
  "workers": [
    {
      "workerId": "chat-worker-1",
      "uptimeMs": 9240000,
      "memoryMb": 156,
      "cpuPercent": 2.5,
      "assigned": 42,
      "joined": 42,
      "retrying": 0,
      "joinsFailed": 0,
      "reconnectCount": 0,
      "heartbeatStatus": "healthy",
      "shards": [
        {
          "shardIndex": 0,
          "joinedChannels": 42,
          "wantedChannels": 42,
          "desync": 0,
          "messageCount": 18500,
          "reconnectCount": 0,
          "failedJoinCount": 0
        }
      ]
    }
  ]
}
GET /joinedChannels
▼
Description
Lists joined channels.
Examples
List joined channels
GET /joinedChannels?cursor=previous_channel 
{
  "channels": [
    "channel_one",
    "channel_two"
  ],
  "nextCursor": "channel_two",
  "pageSize": 5000
}
DELETE /proxy/urls Auth Required Restricted
▼
Description
Removes a whitelisted proxy origin.
Examples
Remove a whitelisted origin
DELETE /proxy/urls Authorization: Bearer <your-api-token> Content-Type: application/json { "url": "https://example.com" } 
{
  "success": true
}

Permission: proxy.manage.urls

GET /proxy/urls Auth Required Restricted
▼
Description
Lists whitelisted proxy origins.
Examples
List every user's whitelisted origins (requires admin.manage.proxy-urls)
GET /proxy/urls?all=true Authorization: Bearer <your-api-token> 
{
  "urls": []
}
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"
    }
  ],
  "nextCursor": null,
  "pageSize": 50
}

Permission: proxy.manage.urls

POST /proxy/urls Auth Required Restricted
▼
Description
Whitelists a proxy origin.
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"
  }
}

Permission: proxy.manage.urls

POST /reboot Auth Required Restricted
▼
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"
}

Permission: system.manage.services

DELETE /redirects Auth Required Restricted
▼
Description
Removes a redirect.
Examples
Remove one of your redirects
DELETE /redirects Authorization: Bearer <your-api-token> Content-Type: application/json { "slug": "my-link" } 
{
  "success": true
}

Permission: redirects.manage

GET /redirects Auth Required Restricted
▼
Description
Lists redirects.
Examples
List every user's redirects (requires admin.manage.redirects)
GET /redirects?all=true Authorization: Bearer <your-api-token> 
{
  "redirects": []
}
List your redirects
GET /redirects?cursor=my-link Authorization: Bearer <your-api-token> 
{
  "redirects": [
    {
      "slug": "my-link",
      "url": "https://r.example.com/my-link",
      "targetUrl": "https://example.com",
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "nextCursor": null,
  "pageSize": 50
}

Permission: redirects.manage

POST /redirects Auth Required Restricted
▼
Description
Creates a URL redirect.
Examples
Create a redirect with auto-generated slug
POST /redirects Authorization: Bearer <your-api-token> Content-Type: application/json { "url": "https://example.com" } 
{
  "redirect": {
    "slug": "a1b2c3d4",
    "url": "https://r.example.com/a1b2c3d4",
    "targetUrl": "https://example.com",
    "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": {
    "slug": "my-link",
    "url": "https://r.example.com/my-link",
    "targetUrl": "https://example.com",
    "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": {
    "slug": "a1b2c3d4",
    "url": "https://r.example.com/a1b2c3d4",
    "targetUrl": "https://example.com",
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
}

Permission: redirects.manage

POST /restart Auth Required Restricted
▼
Description
Restarts one or more services.
Examples
Restart the whole chat fleet with valid authentication
POST /restart Authorization: Bearer <your-api-token> 
{
  "status": "restarting",
  "message": "Chat fleet restart initiated"
}
Restart a single chat worker by its stable ID
POST /restart?service=chat-worker-3 Authorization: Bearer <your-api-token> 
{
  "status": "restarting",
  "message": "chat-worker-3 restart initiated"
}
Chat fleet unreachable over NATS
POST /restart Authorization: Bearer <your-api-token> 
{
  "error": "Chat fleet unreachable"
}

Permission: system.manage.services

DELETE /sessions Auth Required
▼
Description
Revokes a session by id.
Examples
Revoke your session
DELETE /sessions?id=42 Authorization: Bearer <your-api-token> 
{
  "success": true,
  "revokedId": 42
}

Permission: sessions.revoke

GET /sessions Auth Required
▼
Description
Lists dashboard login sessions and rate limits.
Examples
List every user's sessions (requires admin.manage.sessions)
GET /sessions?all=true Authorization: Bearer <your-api-token> 
{
  "sessions": []
}
List your sessions
GET /sessions Authorization: Bearer <your-api-token> 
{
  "sessions": [
    {
      "id": 42,
      "userId": "123456789",
      "username": "someuser",
      "level": 1,
      "rateLimit": 60,
      "rateLimitOverride": "default",
      "rateLimitSource": "user",
      "createdAt": "2026-09-08T12:00:00.000Z",
      "lastUsedAt": null,
      "expiresAt": "2026-09-15T12:00:00.000Z",
      "userAgent": "Mozilla/5.0",
      "createdIp": "203.0.113.1",
      "isCurrent": true
    }
  ]
}

Permission: sessions.view

GET /stream Auth Required
▼
Description
Returns the caller's own configured stream, or null if none exists.
Examples
No stream configured for the caller
GET /stream Authorization: Bearer <your-api-token> 
{
  "stream": null,
  "refreshedAt": "2026-01-01T00:00:00.000Z"
}

Permission: streams.view

POST /stream/action Auth Required
▼
Description
Starts, stops, restarts, or changes the caller's own stream.
Examples
Start your stream with a random video
POST /stream/action Authorization: Bearer <your-api-token> Content-Type: application/json { "action": "start" } 
{
  "success": true,
  "action": "start",
  "video": "myvideo-abc123"
}

Permission: streams.manage

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."
}

Permission: stream-keys.manage

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
}

Permission: stream-keys.manage

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> Content-Type: application/json { "streamKey": "live_xyz789..." } 
{
  "error": "No stream key found. Use POST to create one."
}

Permission: stream-keys.manage

GET /user
▼
Description
Returns Twitch user information.
Examples
Get user info by ID
GET /user?id=123456789 
{
  "id": "123456789",
  "login": "farty",
  "createdAt": "2011-03-16T17:06:00Z",
  "knownNameCount": 2
}
Get user info by username
GET /user?name=farty 
{
  "id": "123456789",
  "login": "farty",
  "createdAt": "2011-03-16T17:06:00Z",
  "knownNameCount": 0
}
Error when neither id nor name is provided
GET /user 
{
  "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 a user's missing Twitch event badges.
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 Twitch usernames.
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"
}
POST /users/live
▼
Description
Returns live stream details for up to 100 Twitch users.
Examples
Get live status for Twitch users in bulk
POST /users/live Content-Type: application/json { "ids": [ "123456789" ], "names": [ "catquery" ] } 
{
  "users": [
    {
      "id": "123456789",
      "login": "catquery",
      "live": false,
      "stream": null
    }
  ],
  "notFound": {
    "ids": [],
    "names": []
  }
}