Card Content Schema

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.

Top-level card properties

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 140 characters
slug	string	No	URL-friendly identifier for the card

Content

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	Unused legacy property
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	Unused legacy property

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 chapters each time played. Tracks within each chapter always play in order. Each entry defines a group of chapters (by start and end index) to shuffle and optionally crop. Only supported when played on Yoto players, not in the app.

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 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	Unused legacy property
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 first chapter to shuffle. For example, start = 1 leaves chapter 0 fixed and begins shuffling from chapter 1.
end	number	Yes	The 0-based index of the last chapter to shuffle (inclusive). For example, end = 9 means chapters up to and including index 9 are shuffled.
limit	number	Yes	The number of chapters to keep after shuffling. For example, if 7 chapters are shuffled but limit is 2, only 2 random chapters will be played. Set limit to end - start + 1 to keep all chapters.

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

Metadata

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

Media

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