guest@tvcloud:~$ man tvcloud

TV Cloud documentation

TV Cloud keeps favorites, history, and settings in sync across the TVs on one account, and serves a programme guide keyed by stream id.

Panel

Managers register at /register. An admin approves the account before the panel login works. Admins land on /admin/dashboard. Managers land on /manager/apps.

Device API

TV apps call these routes on https://tvcloud.app/api. Send app_key in the JSON body when the endpoint asks for it. A successful body includes success, message_code, and message.

POST/api/create-account

Create an account, attach the first device, and store its data as the master copy. Returns accountKey.

{
  "app_key": "@ibocast",
  "macAddress": "AA:BB:CC:DD:EE:FF",
  "playlistUrl": "https://example.com/playlist.m3u",
  "playlistType": "m3u"
}

POST/api/device/register

Attach another device to an existing account and merge its data.

POST/api/sync

Upload the device lists and receive the merged master data. Favorites and history are unions by id. Continue-watching keeps the newest progress. A log object lists items to remove.

{
  "accountKey": "1234567890",
  "deviceId": "AA:BB:CC:DD:EE:FF",
  "syncData": {
    "favorites": {},
    "history": {},
    "continue_watching": {}
  }
}

GET/api/data/{accountKey}

Read the current master data, sync version, and last sync time.

GET/api/accounts/{accountKey}/devices

List the devices on an account.

POST/api/device/sync-control

Body fields accountKey, macAddress, and syncAction (start or stop).

POST/api/reset-account

Clear the master data for an account. Requires app_key, accountKey, and macAddress.

POST/api/remove-device

Detach a device and delete its stored rows. Same identity fields as reset.

Programme guide

The guide is public. Channel ids match the stream ids, for example MBC1.sa and BeINSports1.qa. Listings refresh from php artisan epg:grab, which writes storage/app/public/guide.xml.

GET/api/epg

Every channel, with now and next.

{
  "success": true,
  "updated_at": "2026-10-16T21:35:00+00:00",
  "guide_url": "https://tvcloud.app/api/guide.xml",
  "channels": [
    {
      "id": "MBC1.sa",
      "name": "MBC 1",
      "now": { "title": "…", "start": "…", "stop": "…" },
      "next": { "title": "…", "start": "…", "stop": "…" }
    }
  ]
}

GET/api/epg/{channel}

One channel and its programmes. Each programme has title, subtitle, description, category, image, start, and stop.

GET/api/guide.xml

The same guide as XMLTV, for players that read a guide URL directly.

Refresh the guide

From the project root, with Node 20 or newer:

php artisan epg:grab

The scheduler runs that command every day at 03:00. Channel sources live in epg/my-channels.xml. The xmltv_id on each channel is the id returned by the API.