REST API Reference

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

Authentication

Most endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <your-token>

Tokens are obtained via OAuth (Discord/Patreon) or minted via the /rooms/:room/tokens endpoint.

Rooms

Create Room

Creates a new chat room. Optional Bearer token claims ownership.

{
  "name": "My Stream Chat",
  "allowed_providers": ["discord", "guest"],
  "max_viewers": 100
}

Response:

{
  "room": "abc123xyz",
  "name": "My Stream Chat",
  "owner": "discord:123456789",
  "api_key": "sk_live_..."
}

List Owned Rooms

Returns all rooms owned by the authenticated user. Requires Bearer token.

Get Room (Public)

Returns public metadata for a room. No authentication required.

{
  "room": "abc123xyz",
  "name": "My Stream Chat",
  "allowed_providers": ["discord", "guest"],
  "badges": ["verified"],
  "online": true
}

Update Room

Updates room settings. Requires owner token.

{
  "name": "Updated Name",
  "allowed_providers": ["discord"],
  "moderators": ["discord:987654321"],
  "max_viewers": 500
}

Tokens

Mint Token

Mints a JWT token for room access. Requires API key or owner token.

{
  "user_id": "custom:user123",
  "display_name": "ChatBot",
  "roles": ["bot"],
  "ttl": 3600
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Moderation

Moderate User

Ban, mute, or unban a user. Requires moderator or owner token.

Field	Type	Description
action	string	ban, mute, unban, unmute, stealth
target	string	User ID (e.g., discord:123456)
duration	number	Optional. Seconds for temporary action.
reason	string	Optional. Reason for moderation action.

{
  "action": "mute",
  "target": "discord:123456789",
  "duration": 600,
  "reason": "Spam"
}

Webhook Ingress

Send Message

Push a message into the room from an external source. Requires API key or HMAC signature.

{
  "type": "chat",
  "user": {
    "id": "bot:donations",
    "name": "DonationBot",
    "avatar": "https://example.com/bot.png"
  },
  "content": "Thank you for the $5 donation!"
}

Error Codes

Code	Meaning
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Room doesn't exist
429	Rate Limited - Too many requests
500	Server Error

Rate Limits

• API calls: 60 requests per minute per IP
• WebSocket messages: 20 per 10 seconds per user
• Ingress: 10 messages per second per room