A Yoto card is a large JSON object which consists of a few components.
cardId, title, and slug - Identity fields that uniquely identify and name the card.
metadata - Descriptive information about the card including category, age range, author, cover image, description, languages, and status. This section helps users discover and understand the content.
content - The playback structure defining how the card plays, including chapters with tracks (audio files or streams), playback configuration, and activity type.
| Field name |
Type |
Required |
Description |
Constraints / Validation |
cardId |
string |
No |
Specify the card ID if you want to overwrite an existing card |
(^[a-zA-Z0-9]+$) Exactly 5 characters |
createdAt |
string |
No |
ISO datetime when the card was first created |
Must be a valid ISO datetime (e.g. 2025-09-09T13:10:00.000Z) |
updatedAt |
string |
No |
ISO datetime when the card was last modified |
Must be a valid ISO datetime (e.g. 2025-09-09T13:10:00.000Z) |
title |
string |
Yes |
Playlist title |
Minimum 1 character Maximum 100 characters |
slug |
string |
No |
URL-friendly identifier for the card |
|
| Field name |
Type |
Required |
Description |
Constraints / Validation |
activity |
string |
No |
|
|
chapters |
array |
Yes |
An array of chapters |
Minimum 1 character |
config |
object |
No |
An object containing config fields |
|
playbackType |
enum |
No |
|
One of: linear, interactive |
version |
string |
No |
To help you track different versions of the content |
|
Chapters
| Field name |
Type |
Required |
Description |
Constraints / Validation |
key |
string |
Yes |
|
|
title |
string |
Yes |
The chapter title |
|
overlayLabel |
string |
No |
|
|
availableFrom |
date |
No |
|
|
overlayLabelOverride |
string |
No |
|
|
tracks |
array |
Yes |
An array of tracks |
|
ambient |
object |
No |
An object containing ambient fields |
|
defaultTrackDisplay |
string |
Yes |
|
|
defaultTrackAmbient |
string |
Yes |
|
|
duration |
number |
No |
The total duration of the chapter in seconds |
|
fileSize |
number |
No |
The total size of the chapter in bytes |
|
display |
object |
Yes |
An object containing display fields |
|
hasStreams |
boolean |
No |
Legacy property |
|
displayOverlay |
string |
No |
|
|
Config
| Field name |
Type |
Required |
Description |
Constraints / Validation |
autoadvance |
enum |
No |
Defines how the player should behave when a track ends |
One of: next, repeat, none |
onlineOnly |
boolean |
No |
|
|
resumeTimeout |
number |
No |
Sets how long the currently-played position is stored (in seconds). The default is 2592000 (30 days), so the player will remember your last-played position for a month. |
|
shuffle |
array |
No |
Shuffles tracks each time played. Only supported when played on Yoto players, not in the app. See shuffle |
|
Tracks
| Field name |
Type |
Required |
Description |
Constraints / Validation |
title |
string |
Yes |
The track title |
|
trackUrl |
string |
Yes |
The track URL, can be either a yoto:sha256 url or a regular web URL |
|
key |
string |
Yes |
|
|
format |
enum |
Yes |
The file format of the track's audio file, with opus or mp3 preferred |
One of: mp3, aac, alac, flac, pcm_s16le, opus, ogg, x-m4a, wav, aiff, mpeg, or empty string |
uid |
string |
Yes |
|
|
type |
enum |
Yes |
|
One of: audio, stream |
display |
object |
Yes |
An object containing display fields |
|
displayOverlay |
string |
No |
Unused legacy property |
|
overlayLabelOverride |
string |
No |
|
|
overlayLabel |
string |
No |
Used in the app for track numbering |
|
ambient |
object |
No |
An object containing ambient fields |
|
duration |
number |
Yes |
The duration of the track in seconds |
|
fileSize |
number |
Yes |
The size of the track in bytes |
|
channels |
enum |
No |
The audio channel configuration of the track |
One of: stereo, mono |
events |
object |
No |
An object containing events fields |
|
isNew |
boolean |
No |
|
|
Ambient
| Field name |
Type |
Required |
Description |
Constraints / Validation |
defaultTrackDisplay |
string |
Yes |
|
|
Display
| Field name |
Type |
Required |
Description |
Constraints / Validation |
icon16x16 |
string |
No |
The sha256 of the icon |
(^yoto:#[a-zA-Z0-9_-]{43}$) |
iconUrl16x16 |
string |
No |
Must be a fully qualified URL of a 16x16 png icon with a 32-bit RGBA color format, including alpha transparency. |
|
Shuffle
| Field name |
Type |
Required |
Description |
Constraints / Validation |
start |
number |
Yes |
The 0-based index of the track to start shuffling from. For example, start = 2 would set the 3rd chapter as the shuffle start (e.g., [0,1,2]) |
|
end |
number |
Yes |
The index of the last chapter to include in the shuffle group. For example, end = 7 would include chapters up to and including index 7 (e.g., [...5,6,7]) |
|
limit |
number |
Yes |
The number of shuffled tracks to select for playback. For example, if you have 100 tracks being shuffled but want only 10 to be played each time, set limit to 10. This adds variety without a long run time. |
|
Events
| Field name |
Type |
Required |
Description |
Constraints / Validation |
onEnd |
object |
No |
An object containing onEnd fields |
|
onLhb |
object |
No |
An object containing onLhb fields |
|
onRhb |
object |
No |
An object containing onRhb fields |
|
OnEnd
| Field name |
Type |
Required |
Description |
Constraints / Validation |
cmd |
enum |
Yes |
|
One of: stop, repeat, goto |
params |
record |
No |
|
|
OnLhb
| Field name |
Type |
Required |
Description |
Constraints / Validation |
cmd |
enum |
Yes |
|
One of: stop, repeat, goto |
params |
record |
No |
|
|
OnRhb
| Field name |
Type |
Required |
Description |
Constraints / Validation |
cmd |
enum |
Yes |
|
One of: stop, repeat, goto |
params |
record |
No |
|
|
| Field name |
Type |
Required |
Description |
Constraints / Validation |
media |
object |
No |
An object containing media fields |
|
accent |
string |
No |
The narration's accent |
|
author |
string |
No |
The author |
|
copyright |
string |
No |
|
|
readBy |
string |
No |
Name of the narrator |
|
accents |
array |
No |
List of accents |
|
authors |
array |
No |
List of authors |
|
copyrights |
array |
No |
List of copyrights |
|
narrators |
array |
No |
List of narrator names |
|
category |
enum |
No |
|
One of: none, stories, music, radio, podcast, sfx, activities, alarms |
cover |
object |
No |
An object containing cover fields |
|
description |
string |
No |
Use this field to provide a description of the content |
|
error |
object |
No |
An object containing error fields |
|
feedUrl |
string |
No |
Used for podcast feeds |
|
genres |
array |
No |
|
Maximum 3 characters |
languages |
array |
No |
The language of the content, must be a valid BCP47 language code |
|
maxAge |
number |
No |
|
|
minAge |
number |
No |
|
|
musicTypes |
array |
No |
|
Maximum 3 characters |
note |
string |
No |
|
|
| Field name |
Type |
Required |
Description |
Constraints / Validation |
duration |
number |
Yes |
|
|
fileSize |
number |
Yes |
|
|
Cover
| Field name |
Type |
Required |
Description |
Constraints / Validation |
imageL |
string |
No |
The URL of the card's cover image |
|
Error
| Field name |
Type |
Required |
Description |
Constraints / Validation |
code |
string |
Yes |
|
|
message |
string |
Yes |
|
|
