Co-Stream API

Live streaming rooms, participant management, recordings, and real-time metrics. Build video conferencing, live events, webinars, or watch parties into your application.

← All APIs · VPS Launchpad · Auth Pay Media Vault

Base URL

https://api.railscloud.co/v1

Authentication

Include your API key or JWT token in the Authorization header. All Co-Stream endpoints require authentication and project membership.

# API key (programmatic access)
Authorization: Bearer dk_live_your_api_key

# JWT token (dashboard sessions)
Authorization: Bearer <jwt_token>

How It Works

Co-Stream provisions a LiveKit-based streaming server. You create rooms, generate participant tokens, and we handle the WebRTC infrastructure for low-latency video and audio.

1 Provision a Co-Stream server with POST /projects/{slug}/costream
2 Create a room via POST /costream/{id}/rooms
3 Generate participant tokens with POST /costream/{id}/tokens
4 Participants join using a LiveKit client SDK with the token — video flows instantly

Quick Start

# Create a Co-Stream server
curl -X POST https://api.railscloud.co/v1/projects/my-project/costream \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "live-events", "size": "costream-sm"}'

# Create a room
curl -X POST https://api.railscloud.co/v1/costream/SERVER_ID/rooms \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "keynote-2026"}'

# Generate a participant token
curl -X POST https://api.railscloud.co/v1/costream/SERVER_ID/tokens \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "room_name": "keynote-2026",
    "participant_name": "speaker-jane"
  }'

# Response: {"data": {"token": "eyJ...", "room_name": "keynote-2026", ...}}

Endpoints

Server Management

POST /projects/{slug}/costream Create a Co-Stream server
GET /projects/{slug}/costream List all Co-Stream servers in a project
GET /costream/{id} Get server details
POST /costream/{id}/start Start a stopped server
POST /costream/{id}/stop Stop a running server
DELETE /costream/{id} Permanently delete a server

Rooms

POST /costream/{id}/rooms Create a streaming room
GET /costream/{id}/rooms List all rooms
DELETE /costream/{id}/rooms/{name} Close a room

Participants

POST /costream/{id}/tokens Generate a participant token

Recordings

POST /costream/{id}/rooms/{name}/recording/start Start recording a room
POST /costream/{id}/rooms/{name}/recording/stop Stop recording
GET /costream/{id}/recordings List all recordings

Metrics & Usage

GET /costream/{id}/metrics Server performance metrics
GET /costream/{id}/usage Streaming minutes, bandwidth, and storage

Example: Host a Live Event

# Step 1: Create a room for the event
curl -X POST https://api.railscloud.co/v1/costream/SERVER_ID/rooms \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "product-launch"}'

# Step 2: Start recording
curl -X POST https://api.railscloud.co/v1/costream/SERVER_ID/rooms/product-launch/recording/start \
  -H "Authorization: Bearer dk_live_your_key"

# Step 3: Generate tokens for each speaker
curl -X POST https://api.railscloud.co/v1/costream/SERVER_ID/tokens \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"room_name": "product-launch", "participant_name": "ceo-john"}'

# Response: {"data": {"token": "eyJ...", "room_name": "product-launch"}}
# Give this token to your LiveKit client SDK to join

Example: Stop Recording & List

# Stop the recording
curl -X POST https://api.railscloud.co/v1/costream/SERVER_ID/rooms/product-launch/recording/stop \
  -H "Authorization: Bearer dk_live_your_key"

# List all recordings
curl https://api.railscloud.co/v1/costream/SERVER_ID/recordings \
  -H "Authorization: Bearer dk_live_your_key"

# Response: {"data": [{"id": "...", "room": "product-launch", "duration_sec": 3600, "size_bytes": ...}]}

Rate Limits

Room creation 30 per minute
Token generation 100 per minute
Recording operations 10 per minute
Read operations 120 per minute

Error Responses

All errors follow a standard format.

{
  "error": "room_not_found",
  "message": "The room 'keynote-2026' does not exist on this server"
}
400 Invalid request body or parameters
401 Invalid or missing authentication
403 Insufficient permissions for this project
404 Server, room, or recording not found
409 Server not running or room already exists
422 Validation error (missing room_name, duplicate name)
429 Rate limit exceeded
Start Streaming with Co-Stream