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 items must be part of the family's library (any that aren't are filtered out).
items is an Array - ordering is retained as provided upon create or update of a group.
items can 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

Required Scope

family:library:manage

Responses

201 Createdapplication/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

imageIdstring

Examplefp-cards

itemsarray

Example[{"contentId":"37KwQ"}]

namestring

ExampleMy Favourites

POST

/card/family/library/groups

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

Request Body

curl "https://api.yotoplay.com/card/family/library/groups"