Reference · TVs

List TVs

GET /v1/tvs

Lists the activated TVs of the organizations where the user can see TVs, in alphabetical order.

Paginated response: items come in data and the page information in meta. Pagination and filters

Parameters

Name	Type	Description
`organization`	`string`	uid of an organization, to return only its items (see `/organizations`).
`q`	`string`	Part of the name, up to 100 characters.
`page`	`integer`	Page, starting at 1. Default: 1.
`per_page`	`integer`	Items per page, from 1 to 100. Default: 50.

Fields of each item

uid string: TV identifier, the same one used in the control panel.
name string: TV name.
description string: TV description (may be empty).
organization object: Organization of the TV: uid and name.
playlist object | null: The TV's playlist (uid and name), or null if there is none.
status string: online, alert or offline, as explained below.
last_seen_at string | null: Last contact between the TV and the platform, or null if it has never connected.
activated_at string | null: When the TV was activated.
app_version string: Version of the app installed on the TV.
os string: TV operating system, such as android.
device object: Device brand (brand) and model (model), when the TV reports them.
timezone string | null: TV time zone, such as America/Sao_Paulo, or null.

How the status is calculated

online contact less than 3 minutes ago, playing
alert contact between 3 and 9 minutes ago, or the TV is still starting
offline no contact for 10 minutes or more, or never connected

It is the same rule as the status colors in the control panel.

Possible errors

400 invalid_parameter A parameter has an invalid value, such as per_page above the maximum.
404 organization_not_found The organization given is not an organization where the user can see this type of item.
Key and rate limit errors apply to every endpoint. See all errors

RequestcURLPHPJavaScript

curl "https://api.on-cloud.live/v1/tvs?per_page=2" \
  -H "X-API-Key: $API_KEY"

<?php
$ch = curl_init('https://api.on-cloud.live/v1/tvs?per_page=2');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('API_KEY')],
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://api.on-cloud.live/v1/tvs?per_page=2', {
  headers: { 'X-API-Key': process.env.API_KEY }
});
const { data, meta } = await res.json();

Response200

{
  "data": [
    {
      "uid": "d3d9446802a44259755d38e6d163e820",
      "name": "Caixa 2",
      "description": "",
      "organization": {
        "uid": "1679091c5a880faf6fb5e6087eb1b2dc",
        "name": "Loja Shopping Norte"
      },
      "playlist": null,
      "status": "offline",
      "last_seen_at": "2026-11-01T18:04:51-03:00",
      "activated_at": "2025-03-12T09:41:05-03:00",
      "app_version": "3.12.83",
      "os": "android",
      "device": {
        "brand": "Philco",
        "model": "PTV32G70"
      },
      "timezone": "America/Sao_Paulo"
    },
    {
      "uid": "c98cb8f9cc62887d1f6cf5693df9219c",
      "name": "Recepção",
      "description": "TV da entrada",
      "organization": {
        "uid": "8f14e45fceea167a5a36dedd4bea2543",
        "name": "Loja Centro"
      },
      "playlist": {
        "uid": "e4da3b7fbbce2345d7772b0674a318d5",
        "name": "Lista principal"
      },
      "status": "online",
      "last_seen_at": "2026-11-03T14:32:10-03:00",
      "activated_at": "2025-03-12T09:41:05-03:00",
      "app_version": "3.12.84",
      "os": "android",
      "device": {
        "brand": "TCL",
        "model": "43P635"
      },
      "timezone": "America/Sao_Paulo"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 2,
    "total": 3,
    "total_pages": 2
  }
}