Skip to main content
Rooms are the core concept in OpenTogetherTube - they represent a shared space where users watch videos together.

​
List Rooms

​
GET /api/room/list

List all open public rooms, sorted by number of users (descending), then by room name. Headers
​
apikey
string
Admin API key to list all rooms including private/unlisted (optional)
curl https://opentogethertube.com/api/room/list
Response Returns an array of room objects:
​
name
string
Room identifier
​
title
string
Display title
​
description
string
Room description
​
isTemporary
boolean
Whether the room is temporary
​
visibility
string
Visibility level: public, unlisted, or private
​
queueMode
string
Queue mode: manual, vote, loop, or dj
​
currentSource
object
Currently playing video (if any)
​
users
number
Number of users in the room
[
  {
    "name": "popular-room",
    "title": "Popular Room",
    "description": "The most popular room",
    "isTemporary": false,
    "visibility": "public",
    "queueMode": "manual",
    "currentSource": {
      "service": "youtube",
      "id": "dQw4w9WgXcQ",
      "title": "Video Title",
      "length": 213
    },
    "users": 42
  }
]

​
Generate Temporary Room

​
POST /api/room/generate

Generate a temporary room with a random UUID name. Authentication: Required 
curl -X POST https://opentogethertube.com/api/room/generate \
  -H "Authorization: Bearer YOUR_TOKEN"
Response
​
success
boolean
Operation status
​
room
string
The generated room name (UUID)
{
  "success": true,
  "room": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
Rate limit: 50 points per request

​
Create Room

​
POST /api/room/create

Create a new room with a custom name. Authentication: Required Request Body
​
name
string
required
Room identifier (must be unique)
​
title
string
required
Display title
​
description
string
required
Room description
​
visibility
string
required
Visibility: public, unlisted, or private
​
queueMode
string
required
Queue mode: manual, vote, loop, or dj
​
temporary
boolean
required
Whether the room is temporary
curl -X POST https://opentogethertube.com/api/room/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-room",
    "title": "My Watch Room",
    "description": "A room for watching videos with friends",
    "visibility": "public",
    "queueMode": "manual",
    "temporary": false
  }'
Response 
{
  "success": true
}
Rate limit: 50 points for temporary rooms, 200 points for permanent rooms

​
Get Room Details

​
GET /api/room/

Get detailed information about a specific room. Authentication: Not required (but recommended for private rooms) 
curl https://opentogethertube.com/api/room/my-room
Response
​
name
string
Room identifier
​
title
string
Display title
​
description
string
Room description
​
isTemporary
boolean
Whether the room is temporary
​
visibility
string
Visibility level
​
queueMode
string
Queue mode
​
queue
array
Array of queued videos
​
users
array
Array of users currently in the room
​
grants
array
Permission grants for each role
​
hasOwner
boolean
Whether the room has an owner
​
autoSkipSegmentCategories
array
SponsorBlock categories to auto-skip
{
  "name": "my-room",
  "title": "My Watch Room",
  "description": "A room for watching videos",
  "isTemporary": false,
  "visibility": "public",
  "queueMode": "manual",
  "queue": [
    {
      "service": "youtube",
      "id": "dQw4w9WgXcQ",
      "title": "Video Title",
      "length": 213
    }
  ],
  "users": [
    {
      "id": "client-123",
      "name": "Username",
      "isLoggedIn": true,
      "status": "ready",
      "role": 2
    }
  ],
  "grants": [[0, 255], [1, 511]],
  "hasOwner": true,
  "autoSkipSegmentCategories": ["sponsor", "intro"]
}

​
Update Room Settings

​
PATCH /api/room/

Update room settings or claim ownership. Authentication: Required Request Body (Settings)
​
title
string
New room title
​
description
string
New room description
​
visibility
string
New visibility setting
​
queueMode
string
New queue mode
​
grants
array
Permission grants array
​
autoSkipSegmentCategories
array
SponsorBlock categories to auto-skip
curl -X PATCH https://opentogethertube.com/api/room/my-room \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "queueMode": "vote"
  }'
Request Body (Claim Ownership)
​
claim
boolean
Set to true to claim room ownership
curl -X PATCH https://opentogethertube.com/api/room/my-room \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"claim": true}'
Response 
{
  "success": true
}

​
Delete/Unload Room

​
DELETE /api/room/

Unload a room from memory or permanently delete it. Query Parameters
​
permanent
boolean
Set to true to permanently delete the room (requires ownership)
Unload (Admin Only) 
curl -X DELETE https://opentogethertube.com/api/room/my-room \
  -H "apikey: YOUR_API_KEY"
Permanent Delete (Owner Only) 
curl -X DELETE "https://opentogethertube.com/api/room/my-room?permanent=true" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response 
{
  "success": true
}

​
Add to Queue

​
POST /api/room//queue

Add one or more videos to the room’s queue. Authentication: Required Request Body (Single Video by ID)
​
service
string
required
Video service (e.g., youtube)
​
id
string
required
Video ID
curl -X POST https://opentogethertube.com/api/room/my-room/queue \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "youtube",
    "id": "dQw4w9WgXcQ"
  }'
Request Body (Single Video by URL)
​
url
string
required
Video URL
curl -X POST https://opentogethertube.com/api/room/my-room/queue \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }'
Request Body (Multiple Videos)
​
videos
array
required
Array of VideoId objects
curl -X POST https://opentogethertube.com/api/room/my-room/queue \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "videos": [
      {"service": "youtube", "id": "dQw4w9WgXcQ"},
      {"service": "youtube", "id": "jNQXAC9IVRw"}
    ]
  }'
Response 
{
  "success": true
}
Rate limit: 5 points for single video, 3 points per video for multiple videos

​
Remove from Queue

​
DELETE /api/room//queue

Remove a video from the room’s queue. Authentication: Required Request Body
​
service
string
required
Video service
​
id
string
required
Video ID
curl -X DELETE https://opentogethertube.com/api/room/my-room/queue \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "youtube",
    "id": "dQw4w9WgXcQ"
  }'
Response 
{
  "success": true
}
Rate limit: 5 points per request

​
Vote for Video

​
POST /api/room//vote

Add a vote for a video in the queue. Authentication: Required Request Body
​
service
string
required
Video service
​
id
string
required
Video ID
curl -X POST https://opentogethertube.com/api/room/my-room/vote \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "youtube",
    "id": "dQw4w9WgXcQ"
  }'

​
DELETE /api/room//vote

Remove a vote for a video. 
curl -X DELETE https://opentogethertube.com/api/room/my-room/vote \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "youtube",
    "id": "dQw4w9WgXcQ"
  }'
Response 
{
  "success": true
}

Build docs developers (and LLMs) love

Get started for freeTalk to us