Play an episode from a link without storing it

POST/tv/episodes/{id}/proxy-source/

write Change: creates or edits. Scopes

The episode plays from a link (url) or a bucket object (s3_key) and nothing is stored. delivery: proxy: server relays it and viewers never see the source. delivery: redirect: viewers are sent to the source itself; server only checks it first. Answers 201 with the new file.

Path parameters

idstring (uuid)required
The episode's id.

Body

deliverystring
"proxy": a node of yours fetches the source and passes it through, hiding the origin and paying the bandwidth. "redirect": the viewer is sent to the source and fetches it themselves — no bandwidth cost, but the URL is visible to them and playback is beyond your reach.
- proxy - proxy
- redirect - redirect
Default: "proxy"
serverstring (uuid)required
Node that will carry a proxied title, and probe the source for either.
urlstring
Direct HTTP(S) source. Never sent to a proxied viewer.
s3_keystring
storagestring (uuid)can be null
Bucket for s3_key; the VOD bucket when absent.

Response

201 OK

mediaobjectrequired
- idstring (uuid)requiredread-only
- statestringrequiredread-only
  Lifecycle of the file itself, not of any one node's copy. "ready" means at least one node finished ingest and can serve it; per-node progress lives on MediaAsset.
  - draft - Draft
  - ingesting - Ingesting
  - ready - Ready
  - failed - Failed
- original_namestringrequiredread-only
  Filename as uploaded, downloaded, or found in the watch folder. Kept for operator recognition only.
- containerstringrequiredread-only
  File extension of what is actually served (mkv, mp4, ts, …). Ingest keeps the source's own container byte for byte, so this is whatever the file arrived as; the play URL carries it because players pick a demuxer from the extension.
- size_bytesintegerrequiredread-only
  Size of the finished file. Drives the per-node storage quota.
- duration_secondsnumberrequiredread-onlycan be null
  Null until a node probes the file.
- video_codecstringrequiredread-only
  e.g. H.264, HEVC. Decides whether the operator preview player can show it.
- widthintegerrequiredread-onlycan be null
- heightintegerrequiredread-onlycan be null
- fpsnumberrequiredread-onlycan be null
  Null when the file declares a variable or unknown rate.
- checksumstringrequiredread-only
  Of the finished file. Node-to-node replication verifies against this, so a truncated copy is caught before it is ever served.
- is_readybooleanrequiredread-only
  Whether a streaming server can serve this file now.
- assetsobject[]requiredread-only
  - idstring (uuid)requiredread-only
  - serverstring (uuid)requiredread-only
  - server_namestringrequiredread-only
  - server_instance_idstringrequiredread-only
  - statusstringrequiredread-only
  - progress_pctintegerrequiredread-only
  - bytes_doneintegerrequiredread-only
  - bytes_totalintegerrequiredread-only
  - errorstringrequiredread-only
    Why the last attempt failed. Cleared on a successful retry.
  - last_verified_atstring (date-time)requiredread-onlycan be null
    When the node last confirmed the file is present and the right size.
- audio_tracksobject[]requiredread-only
  - idstring (uuid)requiredread-only
  - indexintegerrequiredread-only
    Position within the stored container, 0-based.
  - languagestringrequiredread-only
    ISO 639-2 code as tagged in the container (eng, fra, ara). Empty when the source carried no tag.
  - titlestringrequiredread-only
  - codecstringrequiredread-only
  - channelsintegerrequiredread-onlycan be null
  - is_defaultbooleanrequiredread-only
- subtitle_tracksobject[]requiredread-only
  - idstring (uuid)requiredread-only
  - indexintegerrequiredread-only
    Position within the stored container, 0-based.
  - languagestring
    ISO 639-2 code (eng, fra, ara). Required for operator-supplied files — an untagged subtitle shows up as "Track 3" on every player.
  - titlestring
  - codecstringrequiredread-only
    subrip, ass, hdmv_pgs_subtitle, ...
  - is_defaultboolean
  - is_forcedboolean
    Shown automatically for foreign-language passages even when subtitles are off.
  - is_sdhboolean
  - source_urlstring (uri)
    Where an operator-supplied subtitle was fetched from. Empty for tracks that came out of the source media.
- deliverystringrequiredread-only
  Who carries the bytes. "stored" is the normal path: a node holds a copy and serves it off local disk. "proxy" keeps nothing — a node opens the source per viewer and passes the bytes through, so the title costs no storage and the viewer never learns the origin, but every byte crosses your bandwidth. "redirect" costs you neither: the viewer is sent to the source and fetches it themselves — which necessarily shows them the URL, and puts playback beyond anything you can observe or cut off. All three inherit the source's reliability: if it goes away, so does the film.
  - stored - Stored on a node
  - proxy - Proxied through a node
  - redirect - Sent straight to the source
- source_urlstring (uri)requiredread-only
  Upstream this file is proxied from. Empty for stored files. Operator-visible only: it is handed to a node over the authenticated server-to-server channel and never reaches a viewer, which is the point of proxying.
- source_storagestring (uuid)requiredread-onlycan be null
  Set when the source is an object in one of the panel's buckets (Settings → Storage). The file is then addressed by its key and a signed URL is made each time it is needed, because a signed URL expires and a stored one would stop the film after a few hours.
- source_storage_namestringrequiredread-only
- source_keystringrequiredread-only
- source_labelstringrequiredread-only
- supports_rangesbooleanrequiredread-only
  Whether the proxied source answered a range request when it was probed. False means the film plays from the start but cannot be scrubbed — accepted rather than refused, because a source that plays is worth more than one that is rejected for a feature the viewer may not use.
- proxy_serverstring (uuid)requiredread-onlycan be null
  The node that carries a proxied title's traffic. Chosen by the operator rather than routed, because this is a bandwidth bill and picking which machine pays it is their decision, not a load-balancing one. Required for "proxy"; meaningless for the other two, since one serves from disk and the other never touches us.
- proxy_server_namestringrequiredread-only
- proxy_balancedbooleanrequiredread-only
  Proxied through whichever streaming node the panel picks at each play (load balanced: a viewer stays on one node, different viewers spread over all of them) instead of one chosen node. The operator opts into spreading the bandwidth bill; with it off, proxy_server alone carries the title.
- created_atstring (date-time)requiredread-only
- updated_atstring (date-time)requiredread-only
replacedstring (uuid)requiredcan be null
The file it replaced, if any.
warningstringrequiredcan be null
Said when the source cannot be seeked: most players will not open it by redirect.

Errors

400 Something sent is not valid. Each field that is wrong is named with what is wrong.
401 No credential, or one that is wrong, expired or revoked.
403 The account, or the key's or app's scopes, may not do this.
404 Nothing with this id, or nothing the account can see.
429 Slow down: wait the seconds in the Retry-After header, then try again.
502 The server could not read the source.

What each error means

cURL

curl -X POST 'https://panel.example.com/tv/episodes/1/proxy-source/' \
  -H "Authorization: Bearer $MINIMUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "server": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b"
}'

Python

import os
import requests

response = requests.post(
    "https://panel.example.com/tv/episodes/1/proxy-source/",
    headers={"Authorization": f"Bearer {os.environ['MINIMUS_API_KEY']}"},
    json={
        "server": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b"
    },
)
response.raise_for_status()
print(response.json())

JavaScript

const response = await fetch('https://panel.example.com/tv/episodes/1/proxy-source/', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.MINIMUS_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "server": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b"
  }),
});
if (!response.ok) throw new Error(`${response.status}`);
console.log(await response.json());

Response 201

{
  "media": {
    "id": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b",
    "state": {
      "0": "d",
      "1": "r",
      "2": "a",
      "3": "f",
      "4": "t"
    },
    "original_name": "string",
    "container": "string",
    "size_bytes": 1,
    "duration_seconds": 1.5,
    "video_codec": "string",
    "width": 1,
    "height": 1,
    "fps": 1.5,
    "checksum": "string",
    "is_ready": true,
    "assets": [
      {
        "id": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b",
        "server": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b",
        "server_name": "string",
        "server_instance_id": "string",
        "status": {
          "0": "p",
          "1": "e",
          "2": "n",
          "3": "d",
          "4": "i",
          "5": "n",
          "6": "g"
        },
        "progress_pct": 1,
        "bytes_done": 1,
        "bytes_total": 0,
        "error": "string",
        "last_verified_at": "2026-11-13T12:00:00Z"
      }
    ],
    "audio_tracks": [
      {
        "id": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b",
        "index": 1,
        "language": "string",
        "title": "Channel A",
        "codec": "string",
        "channels": 1,
        "is_default": true
      }
    ],
    "subtitle_tracks": [
      {
        "id": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b",
        "index": 1,
        "language": "string",
        "title": "Channel A",
        "codec": "string",
        "is_default": true,
        "is_forced": true,
        "is_sdh": true,
        "source_url": "https://example.com/"
      }
    ],
    "delivery": {
      "0": "s",
      "1": "t",
      "2": "o",
      "3": "r",
      "4": "e",
      "5": "d"
    },
    "source_url": "https://example.com/",
    "source_storage": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b",
    "source_storage_name": "string",
    "source_key": "string",
    "source_label": "string",
    "supports_ranges": true,
    "proxy_server": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b",
    "proxy_server_name": "",
    "proxy_balanced": true,
    "created_at": "2026-11-13T12:00:00Z",
    "updated_at": "2026-11-13T12:00:00Z"
  },
  "replaced": "3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b",
  "warning": "string"
}

Play an episode from a link without storing it

Path parameters#

Body#

Response#

201 OK

Errors#

Path parameters

Body

Response

Errors