In this section

Reference

API Reference

HTTP API reference for YotoShelf — 153 endpoints across 14 groups. Generated from OpenAPI spec produced by huma.

Source yotoshelf@d03c43091 Version 1.0.0 Generated from 2026-06

YotoShelf exposes a REST API documented via huma. The spec is generated at build time from the application source. When the server is running, a live Swagger UI is available at /api/docs and the raw spec at /openapi.yaml.

Authentication

The spec has no securitySchemes — auth is enforced in Go middleware, not OpenAPI declarations. Each operation shows a derived badge:

public — no session required (login endpoints, OAuth callbacks, health checks)
session — active session cookie required (POST /auth/login or OIDC flow)
admin — session required with admin role, or token auth (metrics)

Unauthenticated requests to protected endpoints return 401 Unauthorized. Error responses across all endpoints use application/problem+json (RFC 9457).

Regenerating the spec

The spec at src/data/openapi.yaml was generated from app commit d03c43091. To regenerate after updating the application:

cd path/to/yotoshelf
go run ./cmd/gen-openapi > ../yotoshelf.dev/src/data/openapi.yaml

The generator spins up an in-memory HTTP test server and fetches /openapi.yaml from huma. No database or external dependencies required. Download the raw spec: openapi.yaml.

Groups

admin 27 ops

User management, audit log, job control, and system operations. Requires admin role.

1 session 24 admin 2 public

auth 14 ops

6 session 8 public

cards 34 ops

Create, edit, publish, and delete MYO audio cards.

34 session

collections 25 ops

Organise cards into shared collections with role-based access.

25 session

devices 8 ops

Linked Yoto player devices.

8 session

icons 11 ops

AI-generated card icon management and regeneration.

11 session

import 2 ops

Import cards from a linked Yoto account.

2 session

jobs 1 ops

Background job queue status.

1 session

labels 6 ops

Printable card label generation and sharing.

6 session

publish 4 ops

Publish cards to linked Yoto accounts.

4 session

recording 4 ops

Audio recording and track management.

4 session

settings 11 ops

LLM provider and application settings. Requires admin role.

6 session 5 admin

tts 2 ops

Text-to-speech audio generation.

2 session

yoto 4 ops

Yoto account linking and OAuth callbacks.

3 session 1 public

Admin

User management, audit log, job control, and system operations. Requires admin role.

GET /admin/audit-log admin

View audit log

Parameters

Name	In	Type
`user_id`	query	`string`
`action`	query	`string`
`limit`	query	`integer (int64)`
`offset`	query	`integer (int64)`

Responses

200 OK array of AuditLogEntryOut

Field	Type	Description
`action`	`string`
`actor_id`	`string`
`created_at`	`string (date-time)`
`detail`	`string`
`id`	`string`
`ip`	`string`
`user_id`	`string`

GET /admin/deletion-requests admin

List pending deletion requests

Responses

200 OK array of DeletionRequestItem

Field	Type	Description
`created_at`	`string (date-time)`
`expires_at`	`string (date-time)`
`id`	`string`
`owned_collections`	`array \| null`
`reason`	`string`
`status`	`string`
`user_id`	`string`

POST /admin/deletion-requests/{id}/approve admin

Approve a deletion request

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body — ApproveDeletionInputBody

Field	Type	Req	Description
`reassignments`	`object`

Responses

204 No Content

POST /admin/deletion-requests/{id}/reject admin

Reject a deletion request

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

204 No Content

GET /admin/health admin

Admin comprehensive health report

Responses

200 OK AdminHealthOutputBody

Field	Type	Description
`cards`	`integer (int64)`
`checked_at`	`string (date-time)`
`collections`	`object`
`jobs`	`object`
`status`	`string`
`users`	`object`

GET /admin/jobs admin

List all jobs with optional status/type filters

Parameters

Name	In	Type
`status`	query	`string`
`type`	query	`string`
`limit`	query	`integer (int64)`
`offset`	query	`integer (int64)`

Responses

200 OK array of AdminJobOut

Field	Type	Description
`attempts`	`integer (int64)`
`completed_at`	`string \| null (date-time)`
`created_at`	`string (date-time)`
`error`	`string \| null`
`id`	`string`
`status`	`string`
`type`	`string`
`user_id`	`string`

DELETE /admin/jobs/{id} admin

Delete a job by ID

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

204 No Content

GET /admin/orphaned-collections admin

List orphaned collections

Responses

200 OK array of OrphanedCollectionOut

Field	Type	Description
`created_at`	`string (date-time)`
`description`	`string`
`id`	`string`
`name`	`string`
`slug`	`string`

POST /admin/orphaned-collections/{id}/assign admin

Assign an orphaned collection to a user

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body — AssignOrphanedInputBody

Field	Type	Req	Description
`user_id`	`string`	✓

Responses

204 No Content

POST /admin/rotate-key admin

Rotate the encryption key for stored tokens

Request body — RotateKeyInputBody

Field	Type	Req	Description
`old_key`	`string`	✓

Responses

200 OK MessageOutputBody

Field	Type	Description
`message`	`string`

POST /admin/seed-examples admin

Seed example cards for first-run experience

Responses

201 Created SeedExampleOutputBody

Field	Type	Description
`cards_created`	`integer (int64)`
`tracks_created`	`integer (int64)`

GET /admin/seed-status admin

Check whether example content has been seeded

Responses

200 OK SeedStatusOutputBody

Field	Type	Description
`seeded`	`boolean`

GET /admin/users admin

List all users

Responses

200 OK array of UserOut

Field	Type	Description
`auth_type`	`string`
`created_at`	`string (date-time)`
`display_name`	`string`
`email`	`string`
`email_verified_at`	`string (date-time)`
`id`	`string`
`locked_account_count`	`integer (int64)`
`role`	`string`
`status`	`string`

POST /admin/users admin

Create a new user

Request body — AdminCreateUserInputBody

Field	Type	Req
`display_name`	`string`
`email`	`string (email)`	✓
`password`	`string`	✓
`role`	`string`	✓

Responses

201 Created AdminUserOutputBody

Field	Type	Description
`created_at`	`string (date-time)`
`display_name`	`string`
`email`	`string`
`id`	`string`
`role`	`string`
`status`	`string`

DELETE /admin/users/{id} admin

Directly delete a user

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body — AdminDeleteUserInputBody

Field	Type	Req	Description
`reassignments`	`object`

Responses

204 No Content

PUT /admin/users/{id} admin

Update user role or display name

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body — AdminUpdateUserInputBody

Field	Type	Req	Description
`display_name`	`string`	✓
`role`	`string`	✓

Responses

200 OK AdminUserOutputBody

Field	Type	Description
`created_at`	`string (date-time)`
`display_name`	`string`
`email`	`string`
`id`	`string`
`role`	`string`
`status`	`string`

POST /admin/users/{id}/deactivate admin

Deactivate a user account

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

204 No Content

POST /admin/users/{id}/reactivate admin

Reactivate a deactivated user

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

204 No Content

POST /admin/users/{id}/resend-verification admin

Resend email verification to a user

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

200 OK MessageOutputBody

Field	Type	Description
`message`	`string`

POST /admin/users/{id}/reset-password admin

Admin-initiated password reset

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

200 OK AdminResetPasswordOutputBody

Field	Type	Description
`message`	`string`
`reset_link`	`string`

POST /admin/users/{id}/revoke-sessions admin

Revoke all sessions for a user

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

204 No Content

POST /admin/users/{id}/unlock admin

Unlock a locked user account

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

204 No Content

POST /admin/users/{id}/verify-email admin

Manually verify a user's email

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

204 No Content

GET /health public

Public health check

Responses

200 OK HealthOutputBody

Field	Type	Description
`status`	`string`

POST /library/rescan session

Trigger a full library rescan

Responses

202 Accepted MessageOutputBody

Field	Type	Description
`message`	`string`

GET /metrics admin

Basic system metrics

Responses

200 OK MetricsOutputBody

Field	Type	Description
`cards`	`integer (int64)`
`collections`	`object`
`jobs`	`object`
`users`	`object`

GET /ready public

Readiness check — pings database

Responses

200 OK ReadyOutputBody

Field	Type	Description
`db`	`string`

Auth

POST /auth/delete-request session

Request account deletion

Request body — DeletionRequestInputBody

Field	Type	Req	Description
`reason`	`string`

Responses

201 Created DeletionRequestOutputBody

Field	Type	Description
`message`	`string`

POST /auth/forgot-password public

Request a password reset email

Request body — ForgotPasswordInputBody

Field	Type	Req	Description
`email`	`string (email)`	✓

Responses

200 OK ForgotPasswordOutputBody

Field	Type	Description
`message`	`string`

POST /auth/login public

Login with email and password

Field	Type	Req	Description
`email`	`string (email)`	✓	User email
`password`	`string`	✓	User password

200 OK UserOut

Field	Type	Description
`auth_type`	`string`
`created_at`	`string (date-time)`
`display_name`	`string`
`email`	`string`
`email_verified_at`	`string (date-time)`
`id`	`string`
`locked_account_count`	`integer (int64)`
`role`	`string`
`status`	`string`

POST /auth/logout public

Logout and clear session

Responses

204 No Content

GET /auth/me session

Get current authenticated user

Responses

200 OK UserOut

Field	Type	Description
`auth_type`	`string`
`created_at`	`string (date-time)`
`display_name`	`string`
`email`	`string`
`email_verified_at`	`string (date-time)`
`id`	`string`
`locked_account_count`	`integer (int64)`
`role`	`string`
`status`	`string`

POST /auth/oidc/backchannel-logout public

OIDC backchannel logout (provider-initiated)

Responses

200 OK

GET /auth/oidc/callback public

OIDC callback (public)

Responses

204 No Content

GET /auth/oidc/login public

Initiate OIDC login flow

204 No Content

POST /auth/oidc/unlink session

Unlink OIDC SSO from account

Responses

204 No Content

PUT /auth/password session

Change password (requires current password)

Request body — ChangePasswordInputBody

Field	Type	Req	Description
`current_password`	`string`	✓
`new_password`	`string`	✓

Responses

200 OK ChangePasswordOutputBody

Field	Type	Description
`message`	`string`

PATCH /auth/profile session

Update display name

Request body — UpdateProfileInputBody

Field	Type	Req	Description
`display_name`	`string`	✓

Responses

200 OK UpdateProfileOutputBody

Field	Type	Description
`message`	`string`

POST /auth/reset-password public

Reset password using a token

Request body — ResetPasswordInputBody

Field	Type	Req	Description
`new_password`	`string`	✓
`token`	`string`	✓

Responses

200 OK ResetPasswordOutputBody

Field	Type	Description
`message`	`string`

POST /auth/sessions/revoke session

Revoke all sessions (log out everywhere)

Responses

200 OK

POST /auth/verify-email public

Verify email address using a token

Request body — VerifyEmailInputBody

Field	Type	Req	Description
`token`	`string`	✓

Responses

200 OK VerifyEmailOutputBody

Field	Type	Description
`message`	`string`

Cards

Create, edit, publish, and delete MYO audio cards.

GET /cards session

List all cards across all collections

Responses

200 OK array of CardOut

Field	Type	Description
`author`	`string`
`back_cover_hash`	`string \| null`
`back_cover_prompt`	`string`
`collection_id`	`string`
`collection_name`	`string`
`collection_slug`	`string`
`content_hash`	`string \| null`
`cover_hash`	`string \| null`
`cover_prompt`	`string`
`created_at`	`string (date-time)`
`description`	`string`
`slug`	`string`
`source_types`	`array \| null`
`title`	`string`
`total_duration_s`	`integer (int64)`
`track_count`	`integer (int64)`
`updated_at`	`string (date-time)`
`viewer_role`	`string \| null`

DELETE /cards/{slug} session

Delete a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Responses

204 No Content

GET /cards/{slug} session

Get a card by slug with its tracks

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Responses

200 OK CardDetailOut

Field	Type	Description
`author`	`string`
`back_cover_hash`	`string \| null`
`back_cover_prompt`	`string`
`collection_id`	`string`
`collection_name`	`string`
`collection_slug`	`string`
`content_hash`	`string \| null`
`cover_hash`	`string \| null`
`cover_prompt`	`string`
`created_at`	`string (date-time)`
`description`	`string`
`slug`	`string`
`source_types`	`array \| null`
`title`	`string`
`total_duration_s`	`integer (int64)`
`track_count`	`integer (int64)`
`tracks`	`array \| null`
`updated_at`	`string (date-time)`
`viewer_role`	`string \| null`

PUT /cards/{slug} session

Update a card's title and description

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body — UpdateCardInputBody

Field	Type	Req
`author`	`string`
`description`	`string`	✓
`title`	`string`	✓

Responses

204 No Content

GET /cards/{slug}/cover session

Serve card cover image

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`side`	query	`string`		Cover side

Responses

200 OK

POST /cards/{slug}/cover session

Upload card cover image (multipart)

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`side`	query	`string`		Cover side

Request body

No structured fields (see spec for raw schema).

Responses

204 No Content

POST /cards/{slug}/cover/accept-preview session

Promote a generated cover preview to the final cover

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body — AcceptCoverPreviewRequest

Field	Type	Req	Description
`side`	`string`		Cover side

Responses

200 OK GenerateCoverOutputBody

Field	Type	Description
`preview_hash`	`string`

POST /cards/{slug}/cover/generate session

Generate a preview cover image (does not commit)

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body — GenerateCoverRequest

Field	Type	Req	Description
`prompt`	`string`	✓	Description of the desired cover image
`side`	`string`		Cover side

Responses

200 OK GenerateCoverOutputBody

Field	Type	Description
`preview_hash`	`string`

GET /cards/{slug}/cover/preview session

Serve the pending cover preview

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`side`	query	`string`		Cover side

Responses

200 OK

PUT /cards/{slug}/home session

Move a card to a different home collection

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body — MoveCardHomeInputBody

Field	Type	Req	Description
`collection_id`	`string`	✓

Responses

204 No Content

POST /cards/{slug}/merge session

Merge multiple tracks into one

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body — MergeTracksInputBody

Field	Type	Req	Description
`title`	`string`
`track_slugs`	`array \| null`	✓

Responses

202 Accepted JobIDOutputBody

Field	Type	Description
`job_id`	`string`

GET /cards/{slug}/playback session

Get playback configuration for a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Responses

200 OK PlaybackConfigOut

Field	Type	Description
`autoadvance`	`string`
`overlay_timeout`	`integer (int64)`
`resume_timeout`	`integer (int64)`
`shuffle`	`string`

PUT /cards/{slug}/playback session

Update playback configuration for a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body — UpdatePlaybackConfigInputBody

Field	Type	Req
`autoadvance`	`string`	✓
`overlay_timeout`	`integer (int64)`	✓
`resume_timeout`	`integer (int64)`	✓
`shuffle`	`string`	✓

Responses

204 No Content

PUT /cards/{slug}/slug session

Rename a card's slug

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body — RenameSlugInputBody

Field	Type	Req	Description
`slug`	`string`	✓

Responses

204 No Content

GET /cards/{slug}/sources session

List source material tracks for a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Responses

200 OK array of SourceTrackOut

Field	Type	Description
`audio_path`	`string \| null`
`description`	`string`
`duration`	`integer \| null (int64)`
`file_size_bytes`	`integer (int64)`
`id`	`string`
`parent_track_id`	`string \| null`
`slug`	`string`
`title`	`string`

DELETE /cards/{slug}/sources/{track_slug} session

Purge a source material track (deletes file and DB record)

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`track_slug`	path	`string`	✓

Responses

204 No Content

POST /cards/{slug}/tracks session

Upload an audio track (multipart)

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body

No structured fields (see spec for raw schema).

Responses

201 Created TrackOut

Field	Type	Description
`description`	`string`
`duration`	`integer \| null (int64)`
`file_size_bytes`	`integer (int64)`
`icon_path`	`string \| null`
`icon_prompt`	`string`
`icon_source_path`	`string \| null`
`id`	`string`
`original_format`	`string`
`original_size_bytes`	`integer (int64)`
`position`	`integer (int64)`
`slug`	`string`
`source_type`	`string`
`stream_status`	`string \| null`
`title`	`string`
`transcode_status`	`string`
`transcoded_format`	`string`
`transcoded_size_bytes`	`integer (int64)`

DELETE /cards/{slug}/tracks/{track_slug} session

Delete a track from a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`track_slug`	path	`string`	✓

Responses

204 No Content

GET /cards/{slug}/tracks/{track_slug} session

Get a track by slug

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`track_slug`	path	`string`	✓

Responses

200 OK TrackDetailOut

Field	Type	Description
`description`	`string`
`duration`	`integer \| null (int64)`
`file_size_bytes`	`integer (int64)`
`icon_path`	`string \| null`
`icon_prompt`	`string`
`icon_source_path`	`string \| null`
`id`	`string`
`is_source`	`boolean`
`original_format`	`string`
`original_size_bytes`	`integer (int64)`
`parent_track_id`	`string \| null`
`position`	`integer (int64)`
`processing_job_id`	`string \| null`
`slug`	`string`
`source_type`	`string`
`stream_status`	`string \| null`
`title`	`string`
`transcode_status`	`string`
`transcoded_format`	`string`
`transcoded_size_bytes`	`integer (int64)`
`tts_instructions`	`string \| null`
`tts_provider`	`string \| null`
`tts_text`	`string \| null`
`tts_voice`	`string \| null`

GET /cards/{slug}/tracks/{track_slug}/audio session

Serve track audio file with Range support

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`track_slug`	path	`string`	✓

Responses

200 OK

PUT /cards/{slug}/tracks/{track_slug}/description session

Update a track's description

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`track_slug`	path	`string`	✓

Request body — UpdateTrackDescriptionInputBody

Field	Type	Req	Description
`description`	`string`	✓

Responses

204 No Content

POST /cards/{slug}/tracks/{track_slug}/fade session

Apply fade in/out to a track

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`track_slug`	path	`string`	✓

Request body — FadeTrackInputBody

Field	Type	Req	Description
`fade_in_ms`	`integer (int64)`	✓
`fade_out_ms`	`integer (int64)`	✓

Responses

202 Accepted JobIDOutputBody

Field	Type	Description
`job_id`	`string`

PUT /cards/{slug}/tracks/{track_slug}/icon-prompt session

Update a track's icon prompt

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`track_slug`	path	`string`	✓

Request body — UpdateTrackIconPromptInputBody

Field	Type	Req	Description
`icon_prompt`	`string`	✓

Responses

204 No Content

PUT /cards/{slug}/tracks/{track_slug}/slug session

Rename a track's slug

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`track_slug`	path	`string`	✓

Request body — RenameTrackSlugInputBody

Field	Type	Req	Description
`slug`	`string`	✓

Responses

204 No Content

POST /cards/{slug}/tracks/{track_slug}/split session

Split a track at marker points

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`track_slug`	path	`string`	✓

Request body — SplitTrackInputBody

Field	Type	Req	Description
`split_points`	`array \| null`	✓
`titles`	`array \| null`

Responses

202 Accepted JobIDOutputBody

Field	Type	Description
`job_id`	`string`

PUT /cards/{slug}/tracks/{track_slug}/title session

Update a track's title and auto-update slug

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`track_slug`	path	`string`	✓

Request body — UpdateTrackTitleInputBody

Field	Type	Req	Description
`title`	`string`	✓

Responses

200 OK UpdateTrackTitleOutputBody

Field	Type	Description
`slug`	`string`

POST /cards/{slug}/tracks/{track_slug}/trim session

Trim a track to a selection

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`track_slug`	path	`string`	✓

Request body — TrimTrackInputBody

Field	Type	Req
`end`	`number (double)`	✓
`start`	`number (double)`	✓
`title`	`string`

Responses

202 Accepted JobIDOutputBody

Field	Type	Description
`job_id`	`string`

PUT /cards/{slug}/tracks/reorder session

Reorder tracks on a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body — ReorderTracksInputBody

Field	Type	Req	Description
`positions`	`array \| null`	✓

Responses

204 No Content

GET /cards/{slug}/tracks/slug-available session

Check if a track slug is available within a card

Parameters

Name	In	Type	Req
`slug`	path	`string`	✓
`slug`	query	`string`	✓
`track_id`	query	`string`

Responses

200 OK TrackSlugAvailableOutputBody

Field	Type	Description
`available`	`boolean`

POST /cards/{slug}/tracks/stream session

Add a streaming track to a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body — AddStreamTrackInputBody

Field	Type	Req	Description
`stream_url`	`string`	✓
`title`	`string`	✓

Responses

201 Created TrackOut

Field	Type	Description
`description`	`string`
`duration`	`integer \| null (int64)`
`file_size_bytes`	`integer (int64)`
`icon_path`	`string \| null`
`icon_prompt`	`string`
`icon_source_path`	`string \| null`
`id`	`string`
`original_format`	`string`
`original_size_bytes`	`integer (int64)`
`position`	`integer (int64)`
`slug`	`string`
`source_type`	`string`
`stream_status`	`string \| null`
`title`	`string`
`transcode_status`	`string`
`transcoded_format`	`string`
`transcoded_size_bytes`	`integer (int64)`

POST /cards/{slug}/tracks/tts session

Generate a TTS audio track from text

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body — TTSGenerateInputBody

Field	Type	Req
`instructions`	`string`
`position`	`integer (int64)`
`text`	`string`	✓
`title`	`string`
`voice`	`string`	✓

Responses

201 Created TrackOut

Field	Type	Description
`description`	`string`
`duration`	`integer \| null (int64)`
`file_size_bytes`	`integer (int64)`
`icon_path`	`string \| null`
`icon_prompt`	`string`
`icon_source_path`	`string \| null`
`id`	`string`
`original_format`	`string`
`original_size_bytes`	`integer (int64)`
`position`	`integer (int64)`
`slug`	`string`
`source_type`	`string`
`stream_status`	`string \| null`
`title`	`string`
`transcode_status`	`string`
`transcoded_format`	`string`
`transcoded_size_bytes`	`integer (int64)`

GET /cards/slug-available session

Check if a card slug is available

Parameters

Name	In	Type	Req	Description
`slug`	query	`string`	✓

Responses

200 OK SlugAvailableOutputBody

Field	Type	Description
`available`	`boolean`

GET /collections/{collectionID}/cards session

List cards in a collection

Parameters

Name	In	Type	Req	Description
`collectionID`	path	`string`	✓

Responses

200 OK array of CardOut

Field	Type	Description
`author`	`string`
`back_cover_hash`	`string \| null`
`back_cover_prompt`	`string`
`collection_id`	`string`
`collection_name`	`string`
`collection_slug`	`string`
`content_hash`	`string \| null`
`cover_hash`	`string \| null`
`cover_prompt`	`string`
`created_at`	`string (date-time)`
`description`	`string`
`slug`	`string`
`source_types`	`array \| null`
`title`	`string`
`total_duration_s`	`integer (int64)`
`track_count`	`integer (int64)`
`updated_at`	`string (date-time)`
`viewer_role`	`string \| null`

POST /collections/{collectionID}/cards session

Create a new card in a collection

Parameters

Name	In	Type	Req	Description
`collectionID`	path	`string`	✓

Request body — CreateCardInputBody

Field	Type	Req
`author`	`string`
`description`	`string`	✓
`slug`	`string`
`title`	`string`	✓

Responses

201 Created CardOut

Field	Type	Description
`author`	`string`
`back_cover_hash`	`string \| null`
`back_cover_prompt`	`string`
`collection_id`	`string`
`collection_name`	`string`
`collection_slug`	`string`
`content_hash`	`string \| null`
`cover_hash`	`string \| null`
`cover_prompt`	`string`
`created_at`	`string (date-time)`
`description`	`string`
`slug`	`string`
`source_types`	`array \| null`
`title`	`string`
`total_duration_s`	`integer (int64)`
`track_count`	`integer (int64)`
`updated_at`	`string (date-time)`
`viewer_role`	`string \| null`

Collections

Organise cards into shared collections with role-based access.

GET /collections session

List collections for the authenticated user

Responses

200 OK array of CollectionOut

Field	Type	Description
`background_image_hash`	`string \| null`
`card_count`	`integer (int64)`
`created_at`	`string (date-time)`
`description`	`string`
`id`	`string`
`is_default`	`boolean`
`name`	`string`
`slug`	`string`
`viewer_role`	`string \| null`

POST /collections session

Create a new collection

Request body — CreateCollectionInputBody

Field	Type	Req
`description`	`string`	✓
`name`	`string`	✓
`slug`	`string`

Responses

201 Created CollectionOut

Field	Type	Description
`background_image_hash`	`string \| null`
`card_count`	`integer (int64)`
`created_at`	`string (date-time)`
`description`	`string`
`id`	`string`
`is_default`	`boolean`
`name`	`string`
`slug`	`string`
`viewer_role`	`string \| null`

DELETE /collections/{id} session

Delete a collection

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓
`cascade`	query	`boolean`

Responses

204 No Content

GET /collections/{id} session

Get a collection by ID

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

200 OK GetCollectionOutputBody

Field	Type	Description
`background_image_hash`	`string \| null`
`card_count`	`integer (int64)`
`cards`	`array \| null`
`created_at`	`string (date-time)`
`description`	`string`
`id`	`string`
`is_default`	`boolean`
`name`	`string`
`slug`	`string`
`viewer_role`	`string \| null`

PUT /collections/{id} session

Update a collection

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body — UpdateCollectionInputBody

Field	Type	Req	Description
`description`	`string`	✓
`name`	`string`	✓

Responses

204 No Content

GET /collections/{id}/background session

Serve collection background image

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

200 OK

POST /collections/{id}/background session

Upload collection background image (multipart)

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body

No structured fields (see spec for raw schema).

Responses

204 No Content

DELETE /collections/{id}/cards/{cardId}/link session

Unlink a card from a collection

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓
`cardId`	path	`string`	✓

Responses

204 No Content

POST /collections/{id}/cards/link session

Link a card to a collection

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body — LinkCardInputBody

Field	Type	Req	Description
`card_id`	`string`	✓

Responses

204 No Content

GET /collections/{id}/members session

List members of a collection

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

200 OK array of MemberOut

Field	Type	Description
`added_at`	`string (date-time)`
`display_name`	`string`
`email`	`string`
`role`	`string`
`user_id`	`string`

POST /collections/{id}/members session

Add a member to a collection

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body — AddMemberInputBody

Field	Type	Req	Description
`role`	`string`	✓
`user_id`	`string`	✓

Responses

204 No Content

DELETE /collections/{id}/members/{userId} session

Remove a member from a collection

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓
`userId`	path	`string`	✓

Responses

204 No Content

PUT /collections/{id}/members/{userId} session

Update a member's role in a collection

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓
`userId`	path	`string`	✓

Request body — UpdateMemberInputBody

Field	Type	Req	Description
`role`	`string`	✓

Responses

204 No Content

GET /collections/{id}/presets session

List generation presets for a collection

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

200 OK array of PresetOut

Field	Type	Description
`collection_id`	`string`
`created_at`	`string (date-time)`
`duration_min`	`integer (int64)`
`emoji`	`string`
`id`	`string`
`name`	`string`
`prompt_template`	`string`
`sort_order`	`integer (int64)`
`vocab_level`	`string`
`voice_id`	`string`

POST /collections/{id}/presets session

Create a generation preset

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body — CreatePresetInputBody

Field	Type	Req
`duration_min`	`integer (int64)`	✓
`emoji`	`string`	✓
`name`	`string`	✓
`prompt_template`	`string`	✓
`sort_order`	`integer (int64)`	✓
`vocab_level`	`string`	✓
`voice_id`	`string`	✓

Responses

201 Created PresetOut

Field	Type	Description
`collection_id`	`string`
`created_at`	`string (date-time)`
`duration_min`	`integer (int64)`
`emoji`	`string`
`id`	`string`
`name`	`string`
`prompt_template`	`string`
`sort_order`	`integer (int64)`
`vocab_level`	`string`
`voice_id`	`string`

DELETE /collections/{id}/presets/{preset_id} session

Delete a generation preset

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓
`preset_id`	path	`string`	✓

Responses

204 No Content

PUT /collections/{id}/presets/{preset_id} session

Update a generation preset

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓
`preset_id`	path	`string`	✓

Request body — UpdatePresetInputBody

Field	Type	Req
`duration_min`	`integer (int64)`	✓
`emoji`	`string`	✓
`name`	`string`	✓
`prompt_template`	`string`	✓
`sort_order`	`integer (int64)`	✓
`vocab_level`	`string`	✓
`voice_id`	`string`	✓

Responses

204 No Content

GET /collections/{id}/profile session

Get generation profile for a collection

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

200 OK CollectionProfileOut

Field	Type	Description
`avoid_themes`	`string`
`child_age`	`integer \| null (int64)`
`child_name`	`string`
`duration_min`	`integer (int64)`
`friends`	`string`
`interests`	`string`
`notes`	`string`
`pets`	`string`
`prompt_template`	`string`
`vocab_level`	`string`
`voice_id`	`string`

PATCH /collections/{id}/profile session

Update generation profile for a collection

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body — UpdateCollectionProfileInputBody

Field	Type	Req
`avoid_themes`	`string`	✓
`child_age`	`integer \| null (int64)`	✓
`child_name`	`string`	✓
`duration_min`	`integer (int64)`	✓
`friends`	`string`	✓
`interests`	`string`	✓
`notes`	`string`	✓
`pets`	`string`	✓
`prompt_template`	`string`	✓
`vocab_level`	`string`	✓
`voice_id`	`string`	✓

Responses

204 No Content

POST /collections/{id}/set-default session

Set a collection as the default for Quick Record

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

204 No Content

PUT /collections/{id}/slug session

Rename a collection's slug

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body — RenameCollectionSlugInputBody

Field	Type	Req	Description
`slug`	`string`	✓

Responses

204 No Content

GET /collections/{id}/stats session

Get stats for a collection

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

200 OK CollectionStatsOutputBody

Field	Type	Description
`card_count`	`integer (int64)`
`disk_bytes`	`integer (int64)`
`published_count`	`integer (int64)`
`total_duration_s`	`integer (int64)`
`track_count`	`integer (int64)`

GET /collections/by-slug/{slug} session

Get a collection by slug with its cards

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Responses

200 OK GetCollectionBySlugOutputBody

Field	Type	Description
`background_image_hash`	`string \| null`
`card_count`	`integer (int64)`
`cards`	`array \| null`
`created_at`	`string (date-time)`
`description`	`string`
`id`	`string`
`is_default`	`boolean`
`name`	`string`
`slug`	`string`
`viewer_role`	`string \| null`

POST /collections/default session

Get or create the default collection for Quick Record

Responses

200 OK CollectionOut

Field	Type	Description
`background_image_hash`	`string \| null`
`card_count`	`integer (int64)`
`created_at`	`string (date-time)`
`description`	`string`
`id`	`string`
`is_default`	`boolean`
`name`	`string`
`slug`	`string`
`viewer_role`	`string \| null`

GET /collections/slug-available session

Check if a collection slug is available

Parameters

Name	In	Type	Req	Description
`slug`	query	`string`	✓

Responses

200 OK SlugAvailableOutputBody

Field	Type	Description
`available`	`boolean`

Devices

Linked Yoto player devices.

GET /devices session

List all devices across all linked Yoto accounts

Responses

200 OK ListDevicesOutputBody

Field	Type	Description
`devices`	`array \| null`

GET /devices/{accountID}/{deviceID}/cache-status session

Get device cache status from Yoto

Parameters

Name	In	Type	Req	Description
`accountID`	path	`string`	✓
`deviceID`	path	`string`	✓

Responses

200 OK CacheStatusOut

Field	Type	Description
`account_id`	`string`
`device_id`	`string`

POST /devices/{accountID}/{deviceID}/command session

Send a command to a device

Parameters

Name	In	Type	Req	Description
`accountID`	path	`string`	✓
`deviceID`	path	`string`	✓

Request body — SendCommandInputBody

Field	Type	Req	Description
`card_id`	`string`
`command`	`string`	✓

Responses

200 OK MessageOutputBody

Field	Type	Description
`message`	`string`

GET /devices/{accountID}/{deviceID}/info session

Get full device info including status and settings

Parameters

Name	In	Type	Req	Description
`accountID`	path	`string`	✓
`deviceID`	path	`string`	✓

Responses

200 OK InfoSnapshot

Field	Type	Description
`cached`	`boolean`
`device_family`	`string`
`device_id`	`string`
`device_type`	`string`
`form_factor`	`string`
`fw_version`	`string`
`generation`	`string`
`last_updated`	`string (date-time)`
`name`	`string`
`online`	`boolean`
`settings`	`object`
`status`	`object`

GET /devices/{accountID}/{deviceID}/published session

List cards published to this device's account

Parameters

Name	In	Type	Req	Description
`accountID`	path	`string`	✓
`deviceID`	path	`string`	✓

Responses

200 OK PublishedCardsOutputBody

Field	Type	Description
`cards`	`array \| null`

PUT /devices/{accountID}/{deviceID}/settings session

Update device settings

Parameters

Name	In	Type	Req	Description
`accountID`	path	`string`	✓
`deviceID`	path	`string`	✓

Request body — UpdateSettingsInputBody

Field	Type	Req	Description
`clock_face`	`string`
`day_brightness`	`string`
`day_max_volume`	`string`
`day_time`	`string`
`night_brightness`	`string`
`night_max_volume`	`string`
`night_time`	`string`
`shutdown_timeout_min`	`string`
`timezone`	`string`

Responses

200 OK MessageOutputBody

Field	Type	Description
`message`	`string`

PUT /devices/{accountID}/{deviceID}/shortcuts session

Update device shortcut button assignments

Parameters

Name	In	Type	Req	Description
`accountID`	path	`string`	✓
`deviceID`	path	`string`	✓

Request body — UpdateShortcutsInputBody

Field	Type	Req	Description
`shortcuts`	`array \| null`	✓

Responses

200 OK MessageOutputBody

Field	Type	Description
`message`	`string`

POST /seed session

Seed content to Yoto devices

Request body — SeedContentInputBody

Field	Type	Req
`account_id`	`string`	✓
`card_ids`	`array \| null`	✓
`collection_id`	`string`	✓
`device_ids`	`array \| null`	✓
`schedule_at`	`string \| null`	✓

Responses

202 Accepted SeedJobOut

Field	Type	Description
`job_ids`	`array \| null`

Icons

AI-generated card icon management and regeneration.

GET /cards/{slug}/icons/{position} session

Serve 16×16 track icon PNG

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`position`	path	`integer (int64)`	✓

Responses

200 OK

GET /cards/{slug}/icons/{position}-full session

Serve full-resolution track illustration

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`position`	path	`integer (int64)`	✓

Responses

200 OK

GET /cards/{slug}/icons/{position}/preview/{index} session

Serve an icon preview PNG

Parameters

Name	In	Type	Req
`slug`	path	`string`	✓
`position`	path	`integer (int64)`	✓
`index`	path	`integer (int64)`	✓

Responses

200 OK

POST /cards/{slug}/icons/{position}/regenerate session

Regenerate a single icon for a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`position`	path	`integer (int64)`	✓

Responses

200 OK GenerateIconsOutputBody

Field	Type	Description
`generated`	`integer (int64)`
`message`	`string`

POST /cards/{slug}/icons/{position}/select session

Select an icon preview as the final icon

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`position`	path	`integer (int64)`	✓

Request body — SelectPreviewInputBody

Field	Type	Req	Description
`index`	`integer (int64)`	✓

Responses

204 No Content

POST /cards/{slug}/icons/{position}/variations session

Generate N icon variations for preview

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`position`	path	`integer (int64)`	✓

Request body — GenerateVariationsInputBody

Field	Type	Req	Description
`count`	`integer (int64)`	✓
`prompt`	`string`

Responses

200 OK VariationsOutputBody

Field	Type	Description
`count`	`integer (int64)`
`estimated_usd`	`number (double)`

POST /cards/{slug}/icons/generate session

Batch generate icons for a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Responses

200 OK GenerateIconsOutputBody

Field	Type	Description
`generated`	`integer (int64)`
`message`	`string`

POST /cards/{slug}/icons/sample session

Generate icon samples for a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Responses

200 OK GenerateIconsOutputBody

Field	Type	Description
`generated`	`integer (int64)`
`message`	`string`

POST /cards/{slug}/icons/theme session

Suggest an icon theme for a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Responses

200 OK SuggestThemeOutputBody

Field	Type	Description
`palettes`	`array \| null`

PUT /cards/{slug}/icons/theme session

Approve an icon theme for a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body — ApproveThemeInputBody

Field	Type	Req
`colors`	`array \| null`	✓
`palette_name`	`string`	✓
`style`	`string`	✓

Responses

204 No Content

POST /cards/{slug}/tracks/{position}/icon session

Upload a custom icon for a track position

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓
`position`	path	`integer (int64)`	✓

Request body

No structured fields (see spec for raw schema).

Responses

200 OK

Import

Import cards from a linked Yoto account.

POST /cards/import-from-yoto session

Import a MYO card from a linked Yoto account (async)

Request body — ImportFromYotoInputBody

Field	Type	Req	Description
`account_id`	`string`	✓
`yoto_card_id`	`string`	✓

Responses

202 Accepted ImportFromYotoOutputBody

Field	Type	Description
`card_slug`	`string`
`job_id`	`string`

GET /yoto-accounts/{id}/library session

List MYO cards from a linked Yoto account

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

200 OK array of YotoLibraryCardOut

Field	Type	Description
`already_imported`	`boolean`
`chapter_count`	`integer (int64)`
`cover_url`	`string \| null`
`locally_edited`	`boolean`
`title`	`string`
`yoto_card_id`	`string`

Jobs

Background job queue status.

GET /jobs/{id} session

Get a single job by ID

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

200 OK JobOut

Field	Type	Description
`attempts`	`integer (int64)`
`completed_at`	`string \| null (date-time)`
`created_at`	`string (date-time)`
`error`	`string \| null`
`id`	`string`
`payload`	`string`
`status`	`string`
`type`	`string`

Labels

Printable card label generation and sharing.

GET /labels/{filename} session

Download a generated label file

Parameters

Name	In	Type	Req	Description
`filename`	path	`string`	✓

Responses

200 OK

POST /labels/{id}/share session

Create a share link for a label

Name	In	Type	Req	Description
`id`	path	`string`	✓

201 Created LabelShareOut

Field	Type	Description
`access_count`	`integer (int64)`
`card_slugs`	`string`
`created_at`	`string (date-time)`
`expires_at`	`string \| null (date-time)`
`id`	`string`
`label_id`	`string`
`slug`	`string`
`url`	`string`

POST /labels/generate session

Generate print-ready label PDF/SVG

Request body — GenerateLabelsRequest

Field	Type	Req
`card_slugs`	`array \| null`	✓
`format`	`string`	✓
`page_size`	`string`	✓

Responses

201 Created GenerateLabelsOutputBody

Field	Type	Description
`filename`	`string`
`url`	`string`

DELETE /shares session

Revoke all label share links for the authenticated user

Responses

204 No Content

GET /shares session

List label share links for the authenticated user

Responses

200 OK array of LabelShareOut

Field	Type	Description
`access_count`	`integer (int64)`
`card_slugs`	`string`
`created_at`	`string (date-time)`
`expires_at`	`string \| null (date-time)`
`id`	`string`
`label_id`	`string`
`slug`	`string`
`url`	`string`

DELETE /shares/{id} session

Revoke a label share link

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

204 No Content

Publish

Publish cards to linked Yoto accounts.

GET /cards/{slug}/publish-status session

Get publish status for a card

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Responses

200 OK array of PublishRecordOut

Field	Type	Description
`account_label`	`string`
`card_id`	`string`
`content_hash_at_publish`	`string \| null`
`id`	`string`
`last_published_at`	`string \| null (date-time)`
`status`	`string`
`yoto_account_id`	`string`
`yoto_card_id`	`string \| null`

GET /jobs session

List background jobs

Responses

200 OK array of JobOut

Field	Type	Description
`attempts`	`integer (int64)`
`completed_at`	`string \| null (date-time)`
`created_at`	`string (date-time)`
`error`	`string \| null`
`id`	`string`
`payload`	`string`
`status`	`string`
`type`	`string`

POST /publish session

Publish cards to Yoto accounts

Request body — PublishCardsInputBody

Field	Type	Req
`account_ids`	`array \| null`	✓
`card_slugs`	`array \| null`	✓
`collection_id`	`string`	✓

Responses

202 Accepted

POST /publish/verify session

Verify published cards against Yoto accounts

Request body — VerifyPublishInputBody

Field	Type	Req	Description
`account_ids`	`array \| null`	✓
`card_slugs`	`array \| null`	✓

Responses

200 OK VerifyPublishOutputBody

Field	Type	Description
`results`	`array \| null`

Recording

Audio recording and track management.

POST /cards/{slug}/tracks/record-start session

Start a recording session with ffmpeg stdin pipe

Parameters

Name	In	Type	Req	Description
`slug`	path	`string`	✓

Request body — RecordStartInputBody

Field	Type	Req	Description
`title`	`string`

Responses

201 Created RecordStartOutputBody

Field	Type	Description
`chunk_interval_s`	`integer (int64)`
`session_id`	`string`

POST /recording/{session_id}/abandon session

Abandon a recording session

Parameters

Name	In	Type	Req	Description
`session_id`	path	`string`	✓

Responses

204 No Content

POST /recording/{session_id}/chunk session

Write a chunk to the recording ffmpeg stdin pipe

Parameters

Name	In	Type	Req	Description
`session_id`	path	`string`	✓

Request body

No structured fields (see spec for raw schema).

Responses

204 No Content

POST /recording/{session_id}/finish session

Finish recording: close pipe, transcode FLAC to M4A, create track

Parameters

Name	In	Type	Req	Description
`session_id`	path	`string`	✓

Request body — RecordFinishBody

Field	Type	Req	Description
`title`	`string`

Responses

200 OK RecordFinishOutputBody

Field	Type	Description
`track_id`	`string`
`track_slug`	`string`

Settings

LLM provider and application settings. Requires admin role.

GET /admin/llm-providers admin

List system LLM providers

Responses

200 OK array of LLMProviderOut

Field	Type	Description
`budget_left`	`number (double)`
`budget_usd`	`number (double)`
`enabled`	`boolean`
`has_key`	`boolean`
`id`	`string`
`model`	`string`
`monthly_budget_cents`	`integer \| null (int64)`
`monthly_spend_cents`	`integer (int64)`
`monthly_spend_reset_at`	`string`
`owner_type`	`string`
`priority`	`integer (int64)`
`provider`	`string`
`spent_usd`	`number (double)`

POST /admin/llm-providers admin

Create a system LLM provider

Request body — CreateProviderInputBody

Field	Type	Req
`api_key`	`string`	✓
`budget_usd`	`number (double)`	✓
`enabled`	`boolean`	✓
`model`	`string`	✓
`monthly_budget_cents`	`integer (int64)`
`priority`	`integer (int64)`	✓
`provider`	`string`	✓

Responses

201 Created LLMProviderOut

Field	Type	Description
`budget_left`	`number (double)`
`budget_usd`	`number (double)`
`enabled`	`boolean`
`has_key`	`boolean`
`id`	`string`
`model`	`string`
`monthly_budget_cents`	`integer \| null (int64)`
`monthly_spend_cents`	`integer (int64)`
`monthly_spend_reset_at`	`string`
`owner_type`	`string`
`priority`	`integer (int64)`
`provider`	`string`
`spent_usd`	`number (double)`

DELETE /admin/llm-providers/{id} admin

Delete a system LLM provider

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

204 No Content

PUT /admin/llm-providers/{id} admin

Update a system LLM provider

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body — UpdateProviderInputBody

Field	Type	Req
`api_key`	`string`
`budget_usd`	`number (double)`	✓
`enabled`	`boolean`	✓
`model`	`string`	✓
`monthly_budget_cents`	`integer (int64)`
`priority`	`integer (int64)`	✓
`provider`	`string`	✓

Responses

204 No Content

POST /admin/llm-providers/test admin

Test an LLM provider API key

Request body — TestProviderInputBody

Field	Type	Req	Description
`api_key`	`string`	✓
`provider`	`string`	✓

Responses

200 OK TestProviderOutputBody

Field	Type	Description
`message`	`string`
`ok`	`boolean`

GET /settings/llm-providers session

List user LLM providers

Responses

200 OK array of LLMProviderOut

Field	Type	Description
`budget_left`	`number (double)`
`budget_usd`	`number (double)`
`enabled`	`boolean`
`has_key`	`boolean`
`id`	`string`
`model`	`string`
`monthly_budget_cents`	`integer \| null (int64)`
`monthly_spend_cents`	`integer (int64)`
`monthly_spend_reset_at`	`string`
`owner_type`	`string`
`priority`	`integer (int64)`
`provider`	`string`
`spent_usd`	`number (double)`

POST /settings/llm-providers session

Create a user LLM provider

Request body — CreateProviderInputBody

Field	Type	Req
`api_key`	`string`	✓
`budget_usd`	`number (double)`	✓
`enabled`	`boolean`	✓
`model`	`string`	✓
`monthly_budget_cents`	`integer (int64)`
`priority`	`integer (int64)`	✓
`provider`	`string`	✓

Responses

201 Created LLMProviderOut

Field	Type	Description
`budget_left`	`number (double)`
`budget_usd`	`number (double)`
`enabled`	`boolean`
`has_key`	`boolean`
`id`	`string`
`model`	`string`
`monthly_budget_cents`	`integer \| null (int64)`
`monthly_spend_cents`	`integer (int64)`
`monthly_spend_reset_at`	`string`
`owner_type`	`string`
`priority`	`integer (int64)`
`provider`	`string`
`spent_usd`	`number (double)`

DELETE /settings/llm-providers/{id} session

Delete a user LLM provider

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

204 No Content

PUT /settings/llm-providers/{id} session

Update a user LLM provider

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Request body — UpdateProviderInputBody

Field	Type	Req
`api_key`	`string`
`budget_usd`	`number (double)`	✓
`enabled`	`boolean`	✓
`model`	`string`	✓
`monthly_budget_cents`	`integer (int64)`
`priority`	`integer (int64)`	✓
`provider`	`string`	✓

Responses

204 No Content

POST /settings/llm-providers/{id}/test session

Test a user LLM provider API key

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

200 OK TestProviderOutputBody

Field	Type	Description
`message`	`string`
`ok`	`boolean`

GET /settings/llm-providers/cascade session

Get resolved LLM provider cascade for user

Responses

200 OK array of LLMProviderOut

Field	Type	Description
`budget_left`	`number (double)`
`budget_usd`	`number (double)`
`enabled`	`boolean`
`has_key`	`boolean`
`id`	`string`
`model`	`string`
`monthly_budget_cents`	`integer \| null (int64)`
`monthly_spend_cents`	`integer (int64)`
`monthly_spend_reset_at`	`string`
`owner_type`	`string`
`priority`	`integer (int64)`
`provider`	`string`
`spent_usd`	`number (double)`

Tts

Text-to-speech audio generation.

POST /tts/preview session

Preview a TTS voice with a short text sample

Request body — PreviewTTSVoiceRequest

Field	Type	Req
`instructions`	`string`
`text`	`string`	✓
`voice`	`string`	✓

Responses

200 OK

GET /tts/voices session

List available TTS voices

Responses

200 OK array of VoiceOut

Field	Type	Description
`description`	`string`
`id`	`string`
`name`	`string`
`provider`	`string`

Yoto

Yoto account linking and OAuth callbacks.

GET /yoto-accounts session

List linked Yoto accounts

Responses

200 OK ListYotoAccountsOutputBody

Field	Type	Description
`accounts`	`array \| null`

DELETE /yoto-accounts/{id} session

Unlink a Yoto account

Parameters

Name	In	Type	Req	Description
`id`	path	`string`	✓

Responses

204 No Content

GET /yoto-accounts/callback public

Yoto OAuth callback (public)

Responses

204 No Content

GET /yoto-accounts/link session

Initiate Yoto OAuth link flow

Responses

204 No Content

API Reference

Authentication

Regenerating the spec

Groups

Admin

Parameters

Responses

Responses

Parameters

Request body — ApproveDeletionInputBody

Responses

Parameters

Responses

Responses

Parameters

Responses

Parameters

Responses

Responses

Parameters

Request body — AssignOrphanedInputBody

Responses

Request body — RotateKeyInputBody

Responses

Responses

Responses

Responses

Request body — AdminCreateUserInputBody

Responses

Parameters

Request body — AdminDeleteUserInputBody

Responses

Parameters

Request body — AdminUpdateUserInputBody

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Parameters

Responses

Responses

Responses

Responses

Responses

Auth

Request body — DeletionRequestInputBody

Responses

Request body — ForgotPasswordInputBody

Responses

Request body — LoginInputBody

Responses

Responses

Responses

Responses

Responses

Responses

Responses

Request body — ChangePasswordInputBody

Responses

Request body — UpdateProfileInputBody

Responses

Request body — ResetPasswordInputBody

Responses

Responses

Request body — VerifyEmailInputBody

Responses

Cards

Responses

Parameters

Responses

Parameters