Skip to main content
The OpenTogetherTube API provides both REST and WebSocket interfaces for managing rooms, users, and video synchronization.

​
Base URLs

OpenTogetherTube is available at the following base URLs:
  • Production: https://opentogethertube.com/
  • Staging: https://staging.opentogethertube.com/
  • Development: http://localhost:8080/

​
API Structure

The API is organized into the following sections:

​
REST API

  • Rooms - Create, manage, and interact with watch rooms
  • Users - User registration, login, and profile management
  • Data - Metadata endpoints for permissions and video previews
  • Status - Server health and metrics

​
WebSocket API

  • Connection - Real-time bidirectional communication
  • Events - Room state synchronization and user actions

​
Versioning

API Version: 0.2.0
All endpoints are subject to change spontaneously and without warning as new features are added or bugs are fixed.

​
Response Format

All REST API responses follow this structure: 
{
  "success": true,
  "data": { /* response data */ }
}
Error responses: 
{
  "success": false,
  "error": {
    "name": "ErrorName",
    "message": "Error description"
  }
}

​
Common Data Types

​
VideoId

{
  service: string  // e.g., "youtube"
  id: string       // e.g., "dQw4w9WgXcQ"
}

​
Visibility

Values: "public", "unlisted", "private"

​
QueueMode

Values: "manual", "vote", "loop", "dj"
  • manual - Videos play in order
  • vote - Videos are sorted by votes
  • loop - Current video repeats
  • dj - Current video restarts instead of advancing

​
Rate Limiting

The API implements rate limiting to prevent abuse. Rate limits vary by endpoint:
  • Room creation: 50-200 points depending on room type
  • Adding videos: 3-5 points per video
  • Preview requests: 5-75 points depending on search complexity
When rate limited, you’ll receive a 429 Too Many Requests response.

​
Next Steps

Authentication

Learn how to authenticate API requests

Room Endpoints

Manage watch rooms

WebSocket Events

Real-time synchronization

User Endpoints

User management

Build docs developers (and LLMs) love

Get started for freeTalk to us