DocsAPI Reference

API Reference

StreamVault REST API — all resources over HTTPS with Bearer token authentication.

Authentication

All protected endpoints require a Bearer token in the Authorization header. Obtain a token via POST /api/auth/login.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens expire after 7 days. Include a refresh token flow for long-lived sessions. Admin-only endpoints additionally require role=admin on the user record.

Base URLhttps://yourdomain.com

Authentication

POST/api/auth/login

Authenticate a user and receive a Bearer token.

Request Body

Parameter	Type	Required	Description
`email`	string	Yes	User email address
`password`	string	Yes	Account password

Example Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "u1",
    "name": "Sarah Mitchell",
    "email": "[email protected]",
    "role": "user",
    "plan": "Professional"
  }
}

POST/api/auth/register

Create a new user account. Returns a Bearer token on success.

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Full display name
`email`	string	Yes	Email address (must be unique)
`password`	string	Yes	Password (min 8 characters)

Example Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": { "id": "u13", "name": "New User", "email": "[email protected]" }
}

Movies

GET/api/movies

Retrieve a paginated list of movies. Supports filtering and sorting.

Query Parameters

Parameter	Type	Required	Description
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page (default: 20, max: 100)
`genre`	string	No	Filter by genre slug
`sort`	string	No	Sort by: newest, top_rated, most_viewed
`year`	number	No	Filter by release year

Example Response

{
  "data": [
    {
      "id": "1",
      "title": "Crimson Horizon",
      "slug": "crimson-horizon",
      "year": 2024,
      "genre": "Action",
      "imdbRating": 8.4,
      "duration": 142,
      "quality": "4K",
      "isPremium": true
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 145, "pages": 8 }
}

GET/api/movies/[id]

Retrieve a single movie by ID with full metadata, cast, and stream sources.

Example Response

{
  "id": "1",
  "title": "Crimson Horizon",
  "slug": "crimson-horizon",
  "description": "A retired special forces operative...",
  "year": 2024,
  "rating": "PG-13",
  "imdbRating": 8.4,
  "duration": 142,
  "quality": "4K",
  "genre": "Action",
  "cast": [{ "id": "c1", "name": "Alexandra Stone", "role": "Lead" }],
  "streamUrl": "https://cdn.example.com/movies/1/hls/index.m3u8"
}

TV Shows

GET/api/tv-shows

List all TV shows with optional filtering.

Query Parameters

Parameter	Type	Required	Description
`genre`	string	No	Filter by genre slug
`status`	string	No	ongoing \| ended \| canceled
`page`	number	No	Page number (default: 1)

Example Response

{
  "data": [
    {
      "id": "t1",
      "title": "The Cipher",
      "seasons": 3,
      "status": "ongoing",
      "imdbRating": 9.2
    }
  ],
  "pagination": { "page": 1, "total": 32, "pages": 2 }
}

GET/api/tv-shows/[id]

Get full TV show details including all seasons and episodes.

Example Response

{
  "id": "t1",
  "title": "The Cipher",
  "seasons": [
    {
      "number": 1,
      "episodes": [
        { "id": "e1", "title": "Pilot", "duration": 52, "airDate": "2024-01-08" }
      ]
    }
  ]
}

Plans

GET/api/plans

Retrieve all available subscription plans.

Example Response

{
  "data": [
    {
      "id": "p1",
      "name": "Free",
      "price": 0,
      "interval": "monthly",
      "features": ["SD Quality", "1 Profile", "Ad-supported"]
    },
    {
      "id": "p3",
      "name": "Professional",
      "price": 79,
      "interval": "monthly",
      "features": ["Full HD", "4 Profiles", "No Ads", "Downloads"]
    }
  ]
}

Users

GET/api/users

Admin only. List all users with pagination and filtering.

Query Parameters

Parameter	Type	Required	Description
`role`	string	No	Filter by role: user \| admin \| moderator
`status`	string	No	Filter by status: active \| suspended \| banned
`search`	string	No	Search by name or email

Example Response

{
  "data": [
    {
      "id": "u1",
      "name": "Sarah Mitchell",
      "email": "[email protected]",
      "role": "user",
      "plan": "Professional",
      "status": "active"
    }
  ],
  "pagination": { "page": 1, "total": 12847, "pages": 643 }
}

PATCH/api/users/[id]

Update a user record. Admins can change role and status; users can update their own profile.

Request Body

Parameter	Type	Required	Description
`name`	string	No	Display name
`role`	string	No	Admin only: user \| admin \| moderator
`status`	string	No	Admin only: active \| suspended \| banned

Example Response

{ "id": "u1", "name": "Sarah Mitchell", "role": "user", "status": "active" }

Subscriptions

GET/api/subscriptions

Get the current user's active subscription.

Example Response

{
  "id": "sub_1",
  "plan": "Professional",
  "status": "active",
  "currentPeriodEnd": "2026-05-18T00:00:00Z",
  "cancelAtPeriodEnd": false
}

POST/api/subscriptions

Create a new subscription for the authenticated user.

Request Body

Parameter	Type	Required	Description
`planId`	string	Yes	ID of the plan to subscribe to
`paymentMethod`	string	Yes	Stripe payment method ID
`couponCode`	string	No	Optional promo/coupon code

Example Response

{
  "subscriptionId": "sub_2",
  "clientSecret": "pi_3abc_secret_xyz",
  "status": "incomplete"
}

Search

GET/api/search

Full-text search across movies, TV shows, cast, and genres.

Query Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query string
`type`	string	No	Filter type: movie \| tvshow \| channel \| cast
`page`	number	No	Page number (default: 1)

Example Response

{
  "query": "stellar",
  "results": {
    "movies": [{ "id": "3", "title": "Stellar Drift", "type": "movie" }],
    "tvShows": [],
    "channels": []
  },
  "total": 1
}

Watch History

GET/api/watch-history

Get the authenticated user's watch history sorted by most recent.

Example Response

{
  "data": [
    {
      "contentId": "3",
      "contentType": "movie",
      "title": "Stellar Drift",
      "progress": 78,
      "duration": 156,
      "watchedAt": "2026-04-17T21:30:00Z"
    }
  ]
}

POST/api/watch-history

Record or update watch progress for a piece of content.

Request Body

Parameter	Type	Required	Description
`contentId`	string	Yes	ID of the movie or episode
`contentType`	string	Yes	movie \| episode
`progress`	number	Yes	Progress in minutes watched
`duration`	number	Yes	Total duration in minutes

Example Response

{ "success": true, "progress": 78 }

Rate Limiting

All API endpoints are rate-limited per API key. Exceeding the limit returns a 429 Too Many Requests response.

Free / Starter Plan

100

requests per minute

Professional / Enterprise

1,000

requests per minute

← Features Guide Back to Docs →