Reference · Playlists

Get a playlist

GET /v1/playlists/{uid}

Returns a playlist by its uid, with its items in playback order and the TVs that use it.

Path parameter

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

Response fields

uid string: Playlist identifier.
name string: Playlist name.
organization object: Organisation of the playlist: uid and name.
total_time integer: Total playlist time, in seconds.
total_time_is_approximate boolean: true if the total time is an estimate.
items array: Playlist items, in playback order.
items[].position integer: Position of the item in the playlist.
items[].type string: file for a file or entertainment for entertainment content. Other types may appear.
items[].uid string: Identifier of the file or the entertainment content.
items[].display_time integer | null: Display time set on the item, in seconds, or null if none is set.
items[].file object | null: File details, with the same fields as “List files”, or null if the item is not a file or the user cannot see the files of its organisation.
tvs array: TVs that use the playlist (uid, name and organization). Only TVs the user can see are listed.

Possible errors

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

RequestcURLPHPJavaScript

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

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

Response200

{
  "data": {
    "uid": "e4da3b7fbbce2345d7772b0674a318d5",
    "name": "Lista principal",
    "organization": {
      "uid": "8f14e45fceea167a5a36dedd4bea2543",
      "name": "Loja Centro"
    },
    "total_time": 85,
    "total_time_is_approximate": true,
    "items": [
      {
        "position": 1,
        "type": "file",
        "uid": "a87ff679a2f3e71d9181a67b7542122c",
        "display_time": null,
        "file": {
          "uid": "a87ff679a2f3e71d9181a67b7542122c",
          "name": "Promoção de verão",
          "type": "video",
          "duration": 30,
          "archived": false,
          "organization": {
            "uid": "8f14e45fceea167a5a36dedd4bea2543",
            "name": "Loja Centro"
          }
        }
      },
      {
        "position": 2,
        "type": "entertainment",
        "uid": "noticias",
        "display_time": 15,
        "file": null
      },
      {
        "position": 3,
        "type": "file",
        "uid": "6512bd43d9caa6e02c990b0a82652dca",
        "display_time": 10,
        "file": {
          "uid": "6512bd43d9caa6e02c990b0a82652dca",
          "name": "Cardápio do dia",
          "type": "image",
          "duration": 10,
          "archived": false,
          "organization": {
            "uid": "8f14e45fceea167a5a36dedd4bea2543",
            "name": "Loja Centro"
          }
        }
      }
    ],
    "tvs": [
      {
        "uid": "c98cb8f9cc62887d1f6cf5693df9219c",
        "name": "Recepção",
        "organization": {
          "uid": "8f14e45fceea167a5a36dedd4bea2543",
          "name": "Loja Centro"
        }
      },
      {
        "uid": "45c48cce2e2d7fbdea1afc51c7c6ad26",
        "name": "Vitrine",
        "organization": {
          "uid": "8f14e45fceea167a5a36dedd4bea2543",
          "name": "Loja Centro"
        }
      }
    ]
  }
}

Item that does not exist or without access404

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