Documentation for the complete download flow.

MovieMini API runs at api.moviemini.cc. The gateway owns login, public discovery, documentation, health, ticket, and download routes. Caddy routes the remaining /api/* catalog calls and /img/* poster requests to the existing MovieMini backend service.

The gateway resolves the requested quality from the read-only catalog, mints a just-in-time provider URL, and proxies the bytes—so callers never see the upstream provider URL or any signing credential.

API surface:

GET  /
GET  /openapi.json
GET  /health/live
GET  /health/ready

POST /api/auth/login          (MovieMini API gateway)
GET  /api/search              (existing MovieMini backend)
GET  /api/:type/:id           (existing MovieMini backend)
GET  /v1/catalog              (movie/TV discovery)
GET  /v1/catalog/:type/:id    (authenticated provider detail)

POST /v1/media/movie/:id/download-ticket
POST /v1/media/tv/:id/download-ticket
HEAD /v1/downloads/:ticket
GET  /v1/downloads/:ticket

https://api.moviemini.cc

The OpenAPI machine-readable description is available at /openapi.json.

Sign in with an existing MovieMini account:

The response contains a signed HS256 JWT. Include it in the Authorization header on every catalog and ticket request:

Authorization: Bearer <your-session-jwt>

When the gateway issues a download ticket it returns a download_url. That URL contains the ticket credential in the path segment and does not require an Authorization header—it is the bearer credential. Treat it with the same care as a password: it is short-lived, media-specific, and carries your byte budget.

The /v1/catalog endpoint provides movie and TV discovery directly through the gateway. Use type (movie or tv), q, page, and limit query parameters. The narrow public response contains only title IDs, names, years, cached poster paths, media types, and quality labels.

Send a Bearer token to retrieve provider-grouped CM and OrangePlay choices. Provider URLs and credentials are never returned.

type is movie or tv. The detail response includes the numeric id you pass to the ticket endpoint. Request only a quality listed for that title by the catalog.

Example search:

curl -s "https://api.moviemini.cc/api/search?q=dune&type=movie"   -H "Authorization: Bearer <your-session-jwt>"

const res = await fetch(
  'https://api.moviemini.cc/api/search?q=dune&type=movie',
  { headers: { Authorization: 'Bearer <your-session-jwt>' } }
);
const data = await res.json();

import requests
r = requests.get(
    'https://api.moviemini.cc/api/search',
    params={'q': 'dune', 'type': 'movie'},
    headers={'Authorization': 'Bearer <your-session-jwt>'},
)
data = r.json()

Path parameter

Request body (JSON)

Successful response — 201 Created

{
  "download_url": "https://download.api.moviemini.cc/v1/downloads/<ticket>",
  "expires_in": 60
}

expires_in is the number of seconds until the ticket becomes invalid. Begin the download before it expires.

curl -s -X POST   "https://api.moviemini.cc/v1/media/movie/12345/download-ticket"   -H "Authorization: Bearer <your-session-jwt>"   -H "Content-Type: application/json"   -d '{"quality":"1080p","provider":"cm"}'

const res = await fetch(
  'https://api.moviemini.cc/v1/media/movie/12345/download-ticket',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <your-session-jwt>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ quality: '1080p', provider: 'cm' }),
  }
);
const { download_url, expires_in } = await res.json();

import requests
r = requests.post(
    'https://api.moviemini.cc/v1/media/movie/12345/download-ticket',
    headers={'Authorization': 'Bearer <your-session-jwt>'},
    json={'quality': '1080p', 'provider': 'cm'},
)
ticket = r.json()  # { download_url, expires_in }

Path parameter

Request body (JSON)

Successful response — 201 Created

{
  "download_url": "https://download.api.moviemini.cc/v1/downloads/<ticket>",
  "expires_in": 60
}

curl -s -X POST   "https://api.moviemini.cc/v1/media/tv/7890/download-ticket"   -H "Authorization: Bearer <your-session-jwt>"   -H "Content-Type: application/json"   -d '{"quality":"720p","provider":"orangeplay","seasonNumber":1,"episodeNumber":3}'

const res = await fetch(
  'https://api.moviemini.cc/v1/media/tv/7890/download-ticket',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer <your-session-jwt>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ quality: '720p', provider: 'orangeplay', seasonNumber: 1, episodeNumber: 3 }),
  }
);
const { download_url, expires_in } = await res.json();

import requests
r = requests.post(
    'https://api.moviemini.cc/v1/media/tv/7890/download-ticket',
    headers={'Authorization': 'Bearer <your-session-jwt>'},
    json={'quality': '720p', 'provider': 'orangeplay', 'seasonNumber': 1, 'episodeNumber': 3},
)
ticket = r.json()

No request body or Authorization header is needed—the ticket in the URL path is the credential.

Response headers on success (200)

curl -I "https://download.api.moviemini.cc/v1/downloads/<ticket>"

No request body or Authorization header is needed.

If the file exceeds the server's per-request byte limit, the gateway returns 416 Range Not Satisfiable with the message "Full object exceeds request byte limit; request a byte range". In that case use the Range header to download in chunks (see Single-byte ranges & resume).

On success the gateway responds with 200 OK and streams bytes directly. Response headers include Content-Length, Content-Type, Content-Disposition, and Accept-Ranges: bytes.

curl -L -o movie.mp4   "https://download.api.moviemini.cc/v1/downloads/<ticket>"

const res = await fetch(
  'https://download.api.moviemini.cc/v1/downloads/<ticket>'
);
// res.body is a ReadableStream
const buffer = await res.arrayBuffer();
// or pipe res.body to a writable stream

import requests
with requests.get(
    'https://download.api.moviemini.cc/v1/downloads/<ticket>',
    stream=True,
) as r:
    with open('movie.mp4', 'wb') as f:
        for chunk in r.iter_content(chunk_size=1024 * 1024):
            f.write(chunk)

Append a Range header to any GET request:

Range: bytes=<start>-<end>
Range: bytes=<start>-
Range: bytes=-<suffix-length>

On a valid range the gateway responds with 206 Partial Content and sets the Content-Range response header:

HTTP/1.1 206 Partial Content
Content-Range: bytes <start>-<end>/<total>
Content-Length: <chunk-size>

Resume pattern

If a download is interrupted, resume from the last successfully received byte while the ticket remains in its active window. Issue a fresh ticket if that window has expired:

# Interrupted after receiving 52428800 bytes of a 1073741824-byte file:
curl -L   -H "Range: bytes=52428800-"   -o movie_part.mp4   "https://download.api.moviemini.cc/v1/downloads/<ticket>"

A ticket may serve more than one range during its active session, but every request is constrained by the ticket byte budget and per-user concurrency limit. Do not assume it is a permanent URL.

Common headers — all responses

CORS headers — cross-origin requests only

Download-specific headers (HEAD and GET)

Error envelope

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description.",
    "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

Status codes and error codes

If a full-file GET would exceed the server's configured maxRequestBytes limit, the request is rejected with 416 Range Not Satisfiable and the message:

Full object exceeds request byte limit; request a byte range

In this case, use HEAD to obtain the total file size, then download in chunks using the Range header while the ticket remains active.

Similarly, if a Range request would exceed maxRequestBytes, it is rejected with 416 Range Not Satisfiable and the message:

Range exceeds request byte limit

Key constraints

Session JWTs

• Store your session JWT securely (e.g. an environment variable or a secrets manager). Never commit it to source control or expose it in client-side code.
• The JWT is HS256-signed with the MovieMini session secret. It is verified server-side on every ticket request.
• Keep tokens out of URLs and logs, and follow the existing MovieMini account recovery process if one is exposed.

Ticket URLs

• Issue tickets immediately before starting a download; do not cache or pre-generate them in bulk.
• A claimed ticket remains usable only for its short active session and bounded byte budget. An expired ticket is rejected with a 4xx error.
• Never log the full download_url—log only the X-Request-Id for tracing.

Provider URL privacy

The gateway deliberately never exposes upstream provider URLs or signing credentials in any response. All provider resolution and byte forwarding happen server-side. This is by design and will not change.

CORS

Cross-origin requests are restricted to an explicit allow-list. If your origin is not on the list, the gateway returns 403 ORIGIN_DENIED. Contact the platform team to add an approved origin.

The example below downloads a 1080p movie in a single ranged chunk after checking the file size with HEAD. Replace the placeholder values with real credentials and IDs from your account.

# 1. Start with the JWT returned by the existing MovieMini login
TOKEN="<your-session-jwt>"

# 2. Search the catalog
curl -s "https://api.moviemini.cc/api/search?q=dune&type=movie"   -H "Authorization: Bearer $TOKEN"

# 3. Issue a movie ticket (replace 12345 with the real ID; set provider to cm or orangeplay)
TICKET_URL=$(curl -s -X POST   "https://api.moviemini.cc/v1/media/movie/12345/download-ticket"   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{"quality":"1080p","provider":"cm"}' | jq -r '.download_url')

# 4. Read metadata
curl -I "$TICKET_URL"

# 5. Download; ranged retries can reuse the ticket while it remains active
curl -L -o movie.mp4 "$TICKET_URL"

const BASE = 'https://api.moviemini.cc';

// 1. Use the JWT returned by the existing MovieMini login
const token = '<your-session-jwt>';
const auth = { Authorization: `Bearer ${token}` };

// 2. Search, inspect the response, and choose a movie ID
const searchRes = await fetch(`${BASE}/api/search?q=dune&type=movie`, { headers: auth });
const searchResults = await searchRes.json();
const movieId = 12345;

// 3. Issue ticket — provider must be 'cm' or 'orangeplay'
const ticketRes = await fetch(`${BASE}/v1/media/movie/${movieId}/download-ticket`, {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({ quality: '1080p', provider: 'cm' }),
});
const { download_url } = await ticketRes.json();

// 4. HEAD — get file size
const headRes = await fetch(download_url, { method: 'HEAD' });
const totalBytes = Number(headRes.headers.get('content-length'));

// 5. Download one range; retry while the ticket remains active
const dlRes = await fetch(download_url, {
  headers: { Range: `bytes=0-${totalBytes - 1}` },
});
// dlRes.body is a ReadableStream — pipe to a file writer

import requests

BASE = 'https://api.moviemini.cc'

# 1. Use the JWT returned by the existing MovieMini login
token = '<your-session-jwt>'
auth = {'Authorization': f'Bearer {token}'}

# 2. Search, inspect the response, and choose a movie ID
search_results = requests.get(
    f'{BASE}/api/search', params={'q': 'dune', 'type': 'movie'}, headers=auth
).json()
movie_id = 12345

# 3. Issue ticket — provider must be 'cm' or 'orangeplay'
ticket = requests.post(
    f'{BASE}/v1/media/movie/{movie_id}/download-ticket',
    headers=auth,
    json={'quality': '1080p', 'provider': 'cm'},
).json()
download_url = ticket['download_url']

# 4. HEAD — get file size
head = requests.head(download_url)
total = int(head.headers['Content-Length'])

# 5. Download in a single range; retry while the ticket remains active
with requests.get(
    download_url,
    headers={'Range': f'bytes=0-{total - 1}'},
    stream=True,
) as r:
    r.raise_for_status()
    with open('movie.mp4', 'wb') as f:
        for chunk in r.iter_content(chunk_size=1024 * 1024):
            f.write(chunk)