Reference · TVs

Get a TV

GET /v1/tvs/{uid}

Returns a TV by its uid.

Path parameter

Name	Type	Description
`uid`	`string`	uid of the TV.

Response fields

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

404 not_found The endpoint does not exist, or the item does not exist or belongs to an organization the user cannot see.
Key and rate limit errors apply to every endpoint. See all errors

RequestcURLPHPJavaScript

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

<?php
$ch = curl_init('https://api.on-cloud.live/v1/tvs/c98cb8f9cc62887d1f6cf5693df9219c');
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/c98cb8f9cc62887d1f6cf5693df9219c', {
  headers: { 'X-API-Key': process.env.API_KEY }
});
const { data } = await res.json();

Response200

{
  "data": {
    "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"
  }
}

Item that does not exist or without access404

{
  "error": {
    "code": "not_found",
    "message": "Item not found or you do not have access to it."
  }
}