Rails Media API — Rails Cloud

← All APIs · Auth Pay Vault Messaging Location

Base URL

            https://media.railscloud.co/api/v1
        

Authentication

All requests require your API key in the Authorization header. Public endpoints (feeds, trending) work without a session token. Write operations require a session token from the Rails Auth API.

# API key authentication (all requests)
Authorization: Bearer dk_live_your_api_key

# User session (uploads, interactions, user feeds)
X-Session-Token: usr_session_token_here

How Media Upload Works

Rails Media handles the full lifecycle: upload, transcode, stream, and discover. Files upload directly to storage via pre-signed URLs for maximum performance.

1 Request a pre-signed upload URL with POST /videos/upload-url

2 Upload the file directly to the returned URL (PUT request)

3 Create the video record with POST /videos/ — transcoding starts automatically

4 Fetch quality variants for playback or browse content feeds

Quick Start

# Step 1: Get a pre-signed upload URL
curl -X POST https://media.railscloud.co/api/v1/videos/upload-url \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename": "demo.mp4", "content_type": "video/mp4"}'

# Response: {"data": {"upload_url": "https://...", "upload_key": "upl_abc123", "expires_at": "..."}}

# Step 2: Upload the file directly
curl -X PUT "UPLOAD_URL_FROM_STEP_1" \
  -H "Content-Type: video/mp4" \
  --data-binary @demo.mp4

# Step 3: Create the video record (triggers transcoding)
curl -X POST https://media.railscloud.co/api/v1/videos/ \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My Video", "upload_key": "upl_abc123", "visibility": "public"}'

# Response: {"data": {"id": "vid_xyz", "title": "My Video", "status": "processing", ...}}

Endpoints

Video Upload & Management

POST /videos/upload-url Get pre-signed upload URL

POST /videos/ Create video record (starts transcoding)

GET /videos/{id} Get video metadata

PUT /videos/{id} Update video metadata

DELETE /videos/{id} Delete video and all variants

GET /me/videos/ List my uploaded videos

Transcoding & Streaming

POST /videos/{id}/transcode Manually trigger transcoding

GET /videos/{id}/transcode/status Check transcoding progress

GET /videos/{id}/variants Get streaming URLs by quality

GET /videos/{id}/download Download original file

Feed & Discovery

GET /feed/for-you Personalized recommendations

GET /feed/following Videos from followed creators

GET /feed/trending Trending videos

GET /feed/hashtag/{hashtag} Videos by hashtag

GET /search/videos Search videos by keyword

GET /search/creators Search creators by name

GET /discover/trending-hashtags Trending hashtags

Video Interactions

POST /videos/{id}/view Record a video view

POST /videos/{id}/like Like a video

DELETE /videos/{id}/like Unlike a video

POST /videos/{id}/save Save to collection

DELETE /videos/{id}/save Remove from collection

POST /videos/{id}/share Record a share event

Comments

GET /videos/{videoId}/comments List comments on a video

POST /videos/{videoId}/comments Post a comment

GET /comments/{commentId}/replies Get replies to a comment

DELETE /comments/{commentId} Delete a comment

Audio & Music

GET /audios/{id} Get audio track metadata

GET /audios/search Search audio library

GET /audios/trending Trending audio tracks

POST /audios/original Upload an original sound

Social

POST /users/{userId}/follow Follow a creator

DELETE /users/{userId}/follow Unfollow a creator

GET /users/{userId}/followers List followers

GET /users/{userId}/following List following

GET /creators/{id} Get creator profile

GET /users/{username}/videos List user's public videos

Live Streaming

POST /live/start Start a live stream

GET /live/ List active live streams

GET /live/{streamId}/ Get stream details

POST /live/{streamId}/join Join as viewer

POST /live/{streamId}/token Get WebRTC token (LiveKit)

POST /live/{streamId}/end End the live stream

GET /live/{streamId}/viewers Get viewer count

Example: Check Transcoding & Stream

# Poll transcoding status
curl https://media.railscloud.co/api/v1/videos/vid_xyz/transcode/status \
  -H "Authorization: Bearer dk_live_your_key"

# Response: {"data": {"status": "completed", "progress": 100, "variants_ready": ["360p","480p","720p","1080p"]}}

# Get streaming URLs
curl https://media.railscloud.co/api/v1/videos/vid_xyz/variants \
  -H "Authorization: Bearer dk_live_your_key"

# Response: {"data": [{"quality":"1080p","url":"https://...","width":1920,"height":1080}, ...]}

Multiple quality variants (360p, 480p, 720p, 1080p) are generated automatically. Use the variant URLs for adaptive streaming.

Example: Browse & Search

# Get trending videos (no session token needed)
curl https://media.railscloud.co/api/v1/feed/trending \
  -H "Authorization: Bearer dk_live_your_key"

# Search for videos
curl "https://media.railscloud.co/api/v1/search/videos?q=cooking&page=1" \
  -H "Authorization: Bearer dk_live_your_key"

Rate Limits

Upload operations Based on your tier (300-2,500 req/min)

Feed & search queries Based on your tier (300-2,500 req/min)

Live streaming operations Based on your tier (300-2,500 req/min)

Error Responses

All errors follow a standard format.

{
  "error": "video_not_found",
  "message": "Video does not exist or has been deleted"
}

401 Invalid or missing API key / session token

404 Video or resource not found

410 Upload URL expired

413 File exceeds maximum upload size for your tier

422 Transcoding failed (unsupported format)

429 Rate limit exceeded

Get Started with Rails Media