My TV Channel

Start here. Returns who the account is, its subscription tier and limits, how much weekly upload/stream quota is used and remaining, and every channel the owner has with its ready-asset count and what it still needs to go live (launchGaps). Call this before creating anything so you know the real limits for THIS account rather than assuming.

{
  "type": "object",
  "properties": {},
  "required": []
}

List the channels owned by this account.

{
  "type": "object",
  "properties": {},
  "required": []
}

Get one channel by id. Includes scheduleStatus (inactive | pending | active | error) — poll this to confirm a channel has gone live — plus watchUrl, launchedAt and isArchived.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "integer",
      "description": "Channel id"
    }
  },
  "required": [
    "channel_id"
  ]
}

Check whether a channel handle is free before trying to create it. The handle becomes the subdomain: {handle}.my-tv-channel.com. 3-63 chars, lowercase a-z, 0-9 and hyphens.

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "description": "Desired handle, e.g. \"retro-arcade\""
    }
  },
  "required": [
    "handle"
  ]
}

Create a 24/7 linear TV channel. It will NOT be live yet — a channel goes live automatically once it has at least 4 ready assets AND at least 15 minutes of total content. is_public lists it in Discover and is available on every subscription tier, including Starter.

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "description": "3-63 chars, lowercase a-z 0-9 and hyphens. Becomes {handle}.my-tv-channel.com"
    },
    "name": {
      "type": "string",
      "description": "Display name"
    },
    "channel_type": {
      "type": "string",
      "enum": [
        "thematic",
        "location"
      ],
      "description": "Use \"thematic\" unless the channel is tied to a place"
    },
    "description": {
      "type": "string"
    },
    "primary_language": {
      "type": "string",
      "description": "ISO 639-1, e.g. \"en\", \"fr\""
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "category": {
      "type": "string"
    },
    "orientation": {
      "type": "string",
      "enum": [
        "horizontal",
        "vertical"
      ],
      "description": "vertical = 9:16"
    },
    "is_public": {
      "type": "boolean",
      "description": "List in Discover. Available on all tiers."
    },
    "location": {
      "type": "object",
      "description": "Required only when channel_type is \"location\"",
      "properties": {
        "latitude": {
          "type": "number"
        },
        "longitude": {
          "type": "number"
        },
        "radius_km": {
          "type": "number"
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "handle",
    "name",
    "channel_type"
  ]
}

Update an existing channel: name, description, visibility, category, language, age rating, or the community chat link. Only send the fields you are changing.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "category": {
      "type": "string"
    },
    "keywords": {
      "type": "string",
      "description": "Multilingual search keywords"
    },
    "primary_language": {
      "type": "string",
      "description": "ISO 639-1, e.g. \"en\""
    },
    "age_classification": {
      "type": "string",
      "enum": [
        "4+",
        "9+",
        "13+",
        "16+",
        "18+"
      ]
    },
    "is_public": {
      "type": "boolean",
      "description": "List in Discover. Allowed on every tier."
    },
    "show_schedule": {
      "type": "boolean"
    },
    "allow_offline_download": {
      "type": "boolean"
    },
    "chat_platform": {
      "type": "string",
      "enum": [
        "discord",
        "guilded",
        "matrix",
        "revolt",
        "kick",
        "restream"
      ],
      "description": "Community chat platform shown as an overlay on the player. Discord is the fully supported one; the others are accepted but only Discord has a working embed today."
    },
    "chat_server_id": {
      "type": "string",
      "description": "Discord server (guild) id — the owner must supply this; you cannot discover it"
    },
    "chat_channel_id": {
      "type": "string",
      "description": "Discord channel id within that server"
    }
  },
  "required": [
    "channel_id"
  ]
}

Take a channel off the air and out of every listing. This ARCHIVES rather than destroys: the handle stays reserved and assets and schedule history are retained, so it can be restored. Refuses with 409 while transcodes are still running. Idempotent. This is the reversible way to take a channel down; delete_asset removes individual videos instead.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "integer"
    }
  },
  "required": [
    "channel_id"
  ]
}

Add a video to a channel from a direct media URL. THIS IS THE MAIN WAY TO ADD CONTENT over MCP — you cannot upload local file bytes through this interface, so if the owner has local files, ask them to host them somewhere reachable or upload via the app. The URL must be a direct, public, unauthenticated link to mp4/mov/m4v/mpeg/mpg/avi, or a FINITE .m3u8 (VOD, not a live stream) — not a web page, not behind a login, not a YouTube/Vimeo watch page. The server downloads it. Returns immediately; the asset then goes downloading -> pending -> transcoding -> ready. Duration counts against the weekly upload quota. Re-submitting the same URL to the same channel returns the original asset instead of importing twice.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "integer"
    },
    "url": {
      "type": "string",
      "description": "Direct, public media URL"
    },
    "title": {
      "type": "string"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "weight": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10,
      "description": "How often it plays, 0-10 (default 5). Set it here rather than after — see set_asset_weight."
    }
  },
  "required": [
    "channel_id",
    "url"
  ]
}

Import a YouTube video that the OWNER UPLOADED THEMSELVES. This will not work for anyone else's video, by design — a channel built from other people's videos is a copyright problem for the owner. Ownership is proved by a tag only the uploader can add: 1. The owner's tag looks like 'MyTVChannelApp#<device-id>'. When the import fails for a missing tag, the 403 error message contains that account's exact tag string. 2. They paste that exact string into the video's description or tags on YouTube. 3. Retry the import. You cannot do step 2 for them and you cannot bypass it. Public finished videos only: no live streams, no private or age-restricted videos, no playlists or channel URLs. Capped at 10 per day. Counts against the same weekly upload quota as everything else.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "integer"
    },
    "url": {
      "type": "string",
      "description": "A single-video YouTube URL (watch, shorts or youtu.be)"
    },
    "title": {
      "type": "string",
      "description": "Overrides the YouTube title"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "weight": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10
    }
  },
  "required": [
    "channel_id",
    "url"
  ]
}

List the videos on a channel.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "integer"
    }
  },
  "required": [
    "channel_id"
  ]
}

Poll transcode progress. Give either channel_id (all its videos) or asset_id (one). Each asset reports uploadStatus (downloading -> pending -> transcoding -> ready) and the summary tells you when meetsLaunchRequirements becomes true: 4+ ready assets AND 900+ seconds. Poll every 30-60s; transcoding takes roughly real-time/4.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "integer"
    },
    "asset_id": {
      "type": "integer"
    }
  },
  "required": []
}

Change how often a video plays (weight 0-10, default 5; 0 removes it from rotation entirely), and optionally its title or tags. IMPORTANT ORDERING: weights only affect what actually airs when the schedule is (re)generated. A channel builds its schedule the instant it crosses the launch threshold, so weights set AFTER that are stored but do not air. Either set the weight when you import each video, or call regenerate_schedule afterwards. Weights are relative: identical weights across every video produce a uniform rotation, and the spread between them is what shapes airtime.

{
  "type": "object",
  "properties": {
    "asset_id": {
      "type": "integer"
    },
    "weight": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10
    },
    "title": {
      "type": "string"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Tag videos seqXX01, seqXX02 … (XX = any two letters) to force them to play in order as a mini-series."
    }
  },
  "required": [
    "asset_id"
  ]
}

Remove a video from a channel. Soft delete — it stops being scheduled immediately and the schedule regenerates automatically. Idempotent. The asset is retained and stops being scheduled; it is not erased. Affects one video — archive_channel takes a whole channel off the air.

{
  "type": "object",
  "properties": {
    "asset_id": {
      "type": "integer"
    }
  },
  "required": [
    "asset_id"
  ]
}

Re-queue a video whose transcode failed. Only works on assets in a failed state.

{
  "type": "object",
  "properties": {
    "asset_id": {
      "type": "integer"
    }
  },
  "required": [
    "asset_id"
  ]
}

Rebuild the channel's schedule now using the current weights. Call this after changing weights on a channel that is ALREADY live, otherwise the change will not air until the hourly cron. Throttled to one call per channel per 5 minutes; exceeding that returns 429 with a Retry-After header giving the seconds remaining. Requires the channel to meet launch requirements.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "integer"
    }
  },
  "required": [
    "channel_id"
  ]
}

Read the channel's EPG — what is playing and what is coming up. Note this one returns a plain array of entries (unlike other tools, which return an object).

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "integer"
    }
  },
  "required": [
    "channel_id"
  ]
}

Read the channel's declarative schedule rules (fixed time slots and dayparts), plus its scheduling mode and timezone.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "integer"
    }
  },
  "required": [
    "channel_id"
  ]
}

DRY-RUN a ruleset. Saves nothing. Returns {valid, errors, warnings, preview} where preview is a simulated 24h grid of what would actually air. Intended as the dry run for set_schedule_rules: rules are wall-clock, slots start on-or-after their time, and dayparts reweight the random fill, so the airing result is hard to predict from the rules alone. Unlike set_schedule_rules this is not tier-gated and works on any tier. Same payload as set_schedule_rules.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "integer"
    },
    "timezone": {
      "type": "string",
      "description": "IANA name, e.g. \"Europe/Paris\""
    },
    "hours": {
      "type": "integer",
      "description": "How many hours to simulate (default 24, max 168)"
    },
    "rules": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Same shape as set_schedule_rules"
    }
  },
  "required": [
    "channel_id",
    "rules"
  ]
}

Give the channel a durable schedule: fixed slots ("news at 18:00") and dayparts ("no kids content after 22:00"). The scheduler re-honours these on EVERY rebuild, so you set them once instead of babysitting the grid. **Pro tier or higher.** This REPLACES the entire ruleset — send every rule you want, not just new ones. Sending an empty array removes all rules and returns the channel to plain weighted-random. Validate first with validate_schedule_rules. Rule shapes: time_slot {rule_type:'time_slot', start_time:'18:00', end_time?:'21:00', days_mask:127, selector_type:'asset'|'tag'|'playlist', selector_value:<id|tag|[ids]>, priority?:0} daypart_weight {rule_type:'daypart_weight', start_time:'22:00', end_time:'06:00', days_mask:127, selector_type:'asset'|'tag', selector_value:..., weight_multiplier:0-10} days_mask is a bitmask: bit0=Mon … bit6=Sun. 127=daily, 31=Mon-Fri, 96=weekend. end_time on a time_slot makes it a BLOCK that keeps drawing from the selector until that time — that is how you get 'cartoons 06:00-09:00' rather than one cartoon. selector_type 'playlist' with an array of asset ids plays them IN ORDER. weight_multiplier 0 removes matching assets from that window entirely. Set `timezone` (IANA) or the times mean UTC, which is almost never what the owner meant. Slots start ON-OR-AFTER their time: the programme running into a slot is never cut short, so an 18:00 slot may begin at 18:02. That is intended.

{
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "integer"
    },
    "timezone": {
      "type": "string",
      "description": "IANA name, e.g. \"Europe/Paris\". Strongly recommended."
    },
    "rules": {
      "type": "array",
      "description": "The COMPLETE ruleset. Empty array clears all rules.",
      "items": {
        "type": "object",
        "properties": {
          "rule_type": {
            "type": "string",
            "enum": [
              "time_slot",
              "daypart_weight"
            ]
          },
          "start_time": {
            "type": "string",
            "description": "HH:MM or HH:MM:SS, wall clock in the channel timezone"
          },
          "end_time": {
            "type": "string",
            "description": "Required for daypart_weight; on a time_slot makes it a block"
          },
          "days_mask": {
            "type": "integer",
            "minimum": 0,
            "maximum": 127
          },
          "selector_type": {
            "type": "string",
            "enum": [
              "asset",
              "tag",
              "playlist"
            ]
          },
          "selector_value": {
            "description": "Asset id, tag name, or array of asset ids"
          },
          "weight_multiplier": {
            "type": "number",
            "minimum": 0,
            "maximum": 10
          },
          "priority": {
            "type": "integer",
            "description": "Higher wins when slots overlap"
          }
        },
        "required": [
          "rule_type",
          "start_time",
          "selector_type",
          "selector_value"
        ]
      }
    }
  },
  "required": [
    "channel_id",
    "rules"
  ]
}