get a group

Gets a group for a family.

• The contextual family is the authorised user's family

• If a family does not own the queried group or the group does not exist, a 404 Not Found is returned

• The cards property represents each of the items in the group

  • Each items.contentId must be in the family's library (and not have been removed or expired)

  • Each items.contentId must be available on Yoto

  • if an items.contentId is not in a family's library or is not avaialbe it is excluded from the cards array

• imageId can be a pre-made image ID (e.g. fp-cards), with the resulting imageUrl being set to a CDN URL for the image.

• Alternatively, imageId can be set to an ID for an image uploaded to the Media API via the 'upload a family image' endpoint. The resulting imageUrl will be a URL pointing to the 'get a family image' endpoint for the imageId which redirects to a signed S3 URL.

Responses

200

200 OK (premade image) application/json

Schema

cardsarray

[items]object

availabilitystring

cardIdstring

contentobject

activitystring

chaptersarray

[items]object

ambient

defaultTrackAmbient

defaultTrackDisplay

displayobject

durationnumber

fileSizenumber

hasStreamsboolean

keystring

overlayLabelstring

overlayLabelOverride

tracksarray

[items]object

ambient

display

formatstring

keystring

overlayLabelstring

overlayLabelOverride

titlestring

trackUrlstring

transitionsobject

typestring

configobject

onlineOnlyboolean

editSettingsobject

autoOverlayLabelsstring

editKeysboolean

versionstring

createdAtstring

metadataobject

authorstring

categorystring

coverobject

imageLstring

descriptionstring

mediaobject

durationnumber

fileSizenumber

hasStreamsboolean

statusobject

namestring

updatedAtstring

slugstring

sortkeystring

titlestring

updatedAtstring

userIdstring

createdAtstring

familyIdstring

idstring

imageIdstring

imageUrlstring

itemsarray

[items]object

addedAtstring

contentIdstring

lastModifiedAtstring

namestring

JSON

{
  "cards": [
    {
      "availability": "free",
      "cardId": "37KwQ",
      "content": {
        "activity": "yoto_Player",
        "chapters": [
          {
            "ambient": null,
            "defaultTrackAmbient": null,
            "defaultTrackDisplay": null,
            "display": {},
            "duration": 0,
            "fileSize": 0,
            "hasStreams": true,
            "key": "ZjjerfMN6",
            "overlayLabel": "1",
            "overlayLabelOverride": null,
            "tracks": [
              {
                "ambient": null,
                "display": null,
                "format": "mp3",
                "key": "vi0LaS7efY",
                "overlayLabel": "1",
                "overlayLabelOverride": null,
                "title": "BBC Radio 1",
                "trackUrl": "http://stream.live.vc.bbcmedia.co.uk/bbc_radio_one",
                "transitions": {},
                "type": "stream"
              }
            ]
          },
          {
            "ambient": null,
            "defaultTrackAmbient": null,
            "defaultTrackDisplay": null,
            "display": {},
            "duration": 0,
            "fileSize": 0,
            "hasStreams": true,
            "key": "R5QS1Mto0",
            "overlayLabel": "2",
            "overlayLabelOverride": null,
            "tracks": [
              {
                "ambient": null,
                "display": null,
                "format": "mp3",
                "key": "BwJKdlUbUm",
                "overlayLabel": "2",
                "overlayLabelOverride": null,
                "title": "BBC Radio 2",
                "trackUrl": "http://stream.live.vc.bbcmedia.co.uk/bbc_radio_two",
                "transitions": {},
                "type": "stream"
              }
            ]
          },
          {
            "ambient": null,
            "defaultTrackAmbient": null,
            "defaultTrackDisplay": null,
            "display": {},
            "duration": 0,
            "fileSize": 0,
            "hasStreams": true,
            "key": "IIPNvhWrh",
            "overlayLabel": "3",
            "overlayLabelOverride": null,
            "tracks": [
              {
                "ambient": null,
                "display": null,
                "format": "mp3",
                "key": "-HyLtuQraF",
                "overlayLabel": "3",
                "overlayLabelOverride": null,
                "title": "BBC Radio 3",
                "trackUrl": "http://stream.live.vc.bbcmedia.co.uk/bbc_radio_three",
                "transitions": {},
                "type": "stream"
              }
            ]
          },
          {
            "ambient": null,
            "defaultTrackAmbient": null,
            "defaultTrackDisplay": null,
            "display": {},
            "duration": 0,
            "fileSize": 0,
            "hasStreams": true,
            "key": "3RibkqzYS",
            "overlayLabel": "4",
            "overlayLabelOverride": null,
            "tracks": [
              {
                "ambient": null,
                "display": null,
                "format": "mp3",
                "key": "VnuJbNtm6c",
                "overlayLabel": "4",
                "overlayLabelOverride": null,
                "title": "BBC Radio 4",
                "trackUrl": "http://stream.live.vc.bbcmedia.co.uk/bbc_radio_fourfm",
                "transitions": {},
                "type": "stream"
              }
            ]
          },
          {
            "ambient": null,
            "defaultTrackAmbient": null,
            "defaultTrackDisplay": null,
            "display": {},
            "duration": 0,
            "fileSize": 0,
            "hasStreams": true,
            "key": "b2S4vSub7",
            "overlayLabel": "5",
            "overlayLabelOverride": null,
            "tracks": [
              {
                "ambient": null,
                "display": null,
                "format": "mp3",
                "key": "j2ZXWTTGjN",
                "overlayLabel": "5",
                "overlayLabelOverride": null,
                "title": "BBC Radio 5",
                "trackUrl": "http://stream.live.vc.bbcmedia.co.uk/bbc_radio_five_live",
                "transitions": {},
                "type": "stream"
              }
            ]
          },
          {
            "ambient": null,
            "defaultTrackAmbient": null,
            "defaultTrackDisplay": null,
            "display": {},
            "duration": 0,
            "fileSize": 0,
            "hasStreams": true,
            "key": "dD2AAOBZd",
            "overlayLabel": "6",
            "overlayLabelOverride": null,
            "tracks": [
              {
                "ambient": null,
                "display": null,
                "format": "mp3",
                "key": "y-5jnSM1RI",
                "overlayLabel": "6",
                "overlayLabelOverride": null,
                "title": "DEAD",
                "trackUrl": "http://a.fake.url/blah",
                "transitions": {},
                "type": "stream"
              }
            ]
          },
          {
            "ambient": null,
            "defaultTrackAmbient": null,
            "defaultTrackDisplay": null,
            "display": {},
            "duration": 0,
            "fileSize": 0,
            "hasStreams": true,
            "key": "bOBo8Q3a8",
            "overlayLabel": "7",
            "overlayLabelOverride": null,
            "tracks": [
              {
                "ambient": null,
                "display": null,
                "format": "mp3",
                "key": "fPGz211BW4",
                "overlayLabel": "7",
                "overlayLabelOverride": null,
                "title": "BBC Radio 6",
                "trackUrl": "http://stream.live.vc.bbcmedia.co.uk/bbc_6music",
                "transitions": {},
                "type": "stream"
              }
            ]
          }
        ],
        "config": {
          "onlineOnly": true
        },
        "editSettings": {
          "autoOverlayLabels": "chapters",
          "editKeys": false
        },
        "version": "1"
      },
      "createdAt": "2021-01-12T09:32:27.141Z",
      "metadata": {
        "author": "Greg",
        "category": "radio",
        "cover": {
          "imageL": "https://card-content.yotoplay.com/yoto/pub/bLwkrFs6iwUBYcLNU-Iglcvci2MxCIAly84EyI2Yky4"
        },
        "description": "Radio Radio Radio",
        "media": {
          "duration": 0,
          "fileSize": 0,
          "hasStreams": true
        },
        "status": {
          "name": "live",
          "updatedAt": "2021-01-13T11:20:38.356Z"
        }
      },
      "slug": "my-radio-card",
      "sortkey": "my-radio-card",
      "title": "My Radio Card",
      "updatedAt": "2023-01-26T17:30:50.674Z",
      "userId": "yoto"
    }
  ],
  "createdAt": "2024-05-24T10:38:39.330Z",
  "familyId": "65b120377258d846de4595d8",
  "id": "5H6rsCEwk-7MWW-KYlv4U",
  "imageId": "fp-cards",
  "imageUrl": "https://cdn.yoto.io/library/groups/fp-cards.png",
  "items": [
    {
      "addedAt": "2024-05-24T10:38:39.330Z",
      "contentId": "37KwQ"
    }
  ],
  "lastModifiedAt": "2024-05-24T10:38:39.330Z",
  "name": "My Favourites"
}

Path Parameters

groupId string Required

GET

/card/family/library/groups/{groupId}

Server URL: https://api.yotoplay.com

Authorization (bearerAuth)

Token

Try it out

cURL

curl "https://api.yotoplay.com/card/family/library/groups/{groupId}"
--header "Authorization: Bearer [YOUR_TOKEN]"

JavaScript

const options = {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer [YOUR_TOKEN]'
  }
};

fetch('https://api.yotoplay.com/card/family/library/groups/{groupId}', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.yotoplay.com/card/family/library/groups/{groupId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer [YOUR_TOKEN]"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Python

import requests

url = "https://api.yotoplay.com/card/family/library/groups/{groupId}"

headers = {
    "Authorization": "Bearer [YOUR_TOKEN]"
}

response = requests.request("GET", url, headers=headers)

print(response.text)