create a group
The contextual family is the authorised user's family.
There is a limit of 20 groups per family (anything over returns 400 Bad Request
group-limit).The content Id's in
itemsmust be part of the family's library (any that aren't are filtered out).itemsis an Array - ordering is retained as provided upon create or update of a group.itemscan be an empty Array (families can have groups without content).Content can be added to as many groups as a family is allowed. A piece of content will only be stored and show once in a group (duplicate content is removed).
Groups can have the same name. The name is UTF-8 so supports any unicode characters. There is a limit of 100 characters for the name (anything over 100 is truncated).
ImageIds
An imageId can either be set to a pre-made image ID, or an uploaded image ID.
Uploaded imageId
This is the ID returned after uploading an image to the Media API via the 'upload a family image' endpoint. The resulting imageUrl generated for these images will be a URL pointing to the 'get a family image' endpoint for the imageId which redirects to a signed S3 URL.
e.g.
https://api.yotoplay.com/media/family/images/{imageId}
https://api.yotoplay.com/media/family/images/1afea16db1aeb62f8ba84cdb191eee7c1dd734d23098b4756717c3e2bded8c6a
Responses
201 Created application/json
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
{ "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-06-06T13:07:29.283Z", "familyId": "65b120377258d846de4595d8", "id": "OWdb1hxIWyvf4p__y10y5", "imageId": "fp-cards", "imageUrl": "https://cdn.yoto.io/library/groups/fp-cards.png", "items": [ { "addedAt": "2024-06-06T13:07:29.291Z", "contentId": "37KwQ" } ], "lastModifiedAt": "2024-06-06T13:07:29.283Z", "name": "My Favourites"}400 Bad Request (Missing Body) / 400 Bad Request (Missing Fields) / 400 Bad Request (Group Limit Reached) application/json
errorobject
codestring
messagestring
{ "error": { "code": "group-limit", "message": "Maximum 20 groups can be created" }}Body application/json
imageId string
Example
fp-cards items array
Example
[{"contentId":"37KwQ"}] name string
Example
My Favourites POST
/card/family/library/groupsServer URL: https://api.yotoplay.com
Authorization (bearerAuth)
Request Body
curl "https://api.yotoplay.com/card/family/library/groups"--header "Authorization: Bearer [YOUR_TOKEN]"const options = { method: 'POST', headers: { 'Authorization': 'Bearer [YOUR_TOKEN]' }};
fetch('https://api.yotoplay.com/card/family/library/groups', options) .then(response => response.json()) .then(response => console.log(response)) .catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [ CURLOPT_URL => "https://api.yotoplay.com/card/family/library/groups", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", 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;}import requests
url = "https://api.yotoplay.com/card/family/library/groups"
headers = { "Authorization": "Bearer [YOUR_TOKEN]"}
response = requests.request("POST", url, headers=headers)
print(response.text)