API types

Every schema a studio's requests and responses are made of.

AdoptRequest

Field	Type	About
duration_s	number
fps	number
height	integer
kind required	AssetKind
path required	string	Absolute, inside the caller's stage directory (unlinked after adopting) or its data directory (left in place, read-only).
pinned	boolean
width	integer

Asset

Field	Type	About
bytes required	integer
created_at required	string
duration_s required	number \| null
fps required	number \| null
height required	integer \| null
id required	ULID
kind required	AssetKind
library_path required	string \| null	The readable hardlink, relative to the library root. Null when it could not be made (Q11), and null for any caller that is not the origin studio, since it names that studio, a month and a filename (M4 first review, #9).
mime required	string
origin_studio required	string \| null	The studio that first stored these bytes. Null for any caller that is not that studio, so a dedup hit or a shared read never reveals another studio (M4 first review, #9).
pinned required	boolean
sha256 required	string
state required	string (ready \| missing \| corrupt)
thumb required	string	This API's path to the thumbnail, e.g. /api/v1/assets/{id}/thumb?w=320. Needs the Bearer header; a page prefixes /helm to go through its proxy (M6 Q10).
url required	string	This API's path to the bytes, e.g. /api/v1/assets/{id}. Needs the Bearer header; a page prefixes /helm to go through its proxy (M6 Q10).
warnings	string[]	Present on an adopt or upload response when something short of failure happened, such as no library link.
width required	integer \| null

AssetKind

One of image, video, audio, other.

Capability

One of kv, records, assets, gallery, timeline, jobs, gallery.read_all, kv.shared, handoff.send.

Error

Field	Type	About
details	object
error required	string	A stable snake_case code a program branches on.
message required	string	A sentence for a person.

ExportPlan

Field	Type	About
duration_s required	number
frames required	integer
mode required	string (copy \| conform)	`copy` copies the picture and re-encodes the sound; `conform` re-encodes both. Nothing copies sound (M8 Q13).
preset required	ExportPreset
reasons required	ExportReason[]
target required	TimelineTarget

ExportPreset

Encoding only, never size or rate, which the target already states (M8 Q9). `h264` is yuv420p, High profile, MP4 with fast start, and AAC-LC at 192 kb/s.

One of h264.

ExportReason

Why an export cannot copy its picture, one per clip that stops it.

Field	Type	About
clip	integer	The clip's place in its track, counting from 1.
code required	string	container, codec, profile, level, size, aspect, field_order, pixel_format, time_base, frame_rate, colour, parameter_sets, trimmed, image, transition, not_probed, no_video.
message required	string
track	string

ExportRequest

Field	Type	About
preset required	ExportPreset

GapEvent

Field	Type	About
reason required	string	Events were lost; re-read state rather than trusting the stream.

Handoff

Field	Type	About
created_at required	string
id required	ULID
item_id required	ULID
role required	string \| null
to_studio required	StudioIdValue

HandoffRequest

Field	Type	About
item_id required	ULID
role	string
to_studio required	StudioIdValue

InboxEntry

Field	Type	About
created_at required	string
from_studio required	StudioIdValue
id required	ULID
item required	Item \| null	Null when the sender has since deleted the item.
item_id required	ULID
role required	string \| null

InboxEvent

Field	Type	About
from_studio required	StudioIdValue
inbox_id required	ULID
item_id required	ULID
role	string \| null

InboxPage

Everything in Page, and:

Field	Type	About
items	InboxEntry[]

Item

Field	Type	About
asset required	Asset
asset_id required	ULID
created_at required	string
id required	ULID
inputs required	ItemInput[]
kind required	AssetKind
params required	JSONObject
session_id required	ULID \| null
starred required	boolean
studio_id required	StudioIdValue
tags required	Tag[]
timeline_id required	ULID \| null	Set when this item is a sequence's export (R48, 02 §10). The gallery labels such an item "timeline" rather than by a studio (M8 Q17).
title required	string \| null

ItemCreate

Field	Type	About
asset_id required	ULID
inputs	ItemInput[]
kind required	AssetKind
params required	JSONObject
session_id	ULID
tags	Tag[]
title	string

ItemEvent

Field	Type	About
change required	string (added \| updated \| deleted)
item required	Item

ItemInput

Field	Type	About
asset_id required	ULID
role required	string	e.g. first_frame, last_frame, reference, audio_bed, clip

ItemPage

Everything in Page, and:

Field	Type	About
items	Item[]

ItemUpdate

Field	Type	About
starred	boolean
tags	Tag[]
title	string \| null

JSONObject

Job

Field	Type	About
cancel_requested_at	string
created_at required	string
finished_at	string
id required	ULID
kind required	JobKind
last_error	JobError
progress_den required	integer
progress_num required	integer
started_at	string
state required	JobState
steps	StepRun[]
studio_id	StudioIdValue
subject_id	string
subject_kind	string
warnings	string[]

JobError

installations.last_failure and jobs.last_error (02 §4). Install codes: clone_failed, tool_missing, env_failed, step_failed, step_timeout, cancelled, interrupted, auth_required, disk_space, weights_failed, linked_missing, uninstall_failed. env_failed (creating a Python environment, docs/decisions.md M5 Q7) has no step_index. A task job's code is the studio's own.

Field	Type	About
code required	string
exit_code	integer
log_file_id	ULID
message required	string
phase	string
step_index	integer

JobEvent

Field	Type	About
job required	Job

JobKind

One of install, build, download, update, export, uninstall, task.

JobLogEnd

Field	Type	About
last_error	JobError
state required	JobState

JobLogLine

Field	Type	About
step_index	integer	Absent for a task job.
text required	string

JobLogStep

Field	Type	About
command required	string
step_index required	integer
step_name required	string

JobPage

Everything in Page, and:

Field	Type	About
items	Job[]

JobState

One of queued, running, succeeded, failed, cancelled, interrupted.

KVDoc

Field	Type	About
doc required	JSONObject
etag required	string
key required	string
ns required	string
updated_at required	string

KVKey

Field	Type	About
bytes required	integer
key required	string
updated_at required	string

KVKeyPage

Everything in Page, and:

Field	Type	About
items	KVKey[]

LogAppend

Field	Type	About
lines required	string[]

Me

Field	Type	About
api_version required	string	This document's info.version.
capabilities required	Capability[]
daemon_version required	string	The daemon's or helm dev's build version.
paths required	object
provider required	string (daemon \| embedded)
quota required	object
studio_id required	StudioIdValue

Page

Field	Type	About
next_cursor required	string \| null	Null on the last page.

QuotaUse

Field	Type	About
limit required	integer
used required	integer

Record

Field	Type	About
collection required	string
created_at required	string
doc required	JSONObject
etag required	string
id required	ULID
updated_at required	string

RecordPage

Everything in Page, and:

Field	Type	About
items	Record[]

Session

Field	Type	About
created_at required	string
etag required	string
id required	ULID
name required	string
opened_at required	string \| null
state required	JSONObject
studio_id required	StudioIdValue

SessionCreate

Field	Type	About
name required	string
state	JSONObject

SessionDuplicate

Field	Type	About
name required	string

SessionPage

Everything in Page, and:

Field	Type	About
items	Session[]

SessionUpdate

A JSON merge patch over the session's writable fields. `state` members merge; a null member removes that key.

Field	Type	About
name	string
state	JSONObject

ShutdownEvent

Field	Type	About
reason required	string

StepRun

Field	Type	About
command required	string
exit_code	integer
finished_at	string
log_file_id	ULID
started_at	string
state required	string (pending \| running \| succeeded \| skipped \| failed \| interrupted \| cancelled)
step_index required	integer
step_name required	string

StudioIdValue

A manifest id (schema/manifest.json `id`).

TaskCreate

Field	Type	About
progress_den	integer
progress_num	integer
state	string (queued \| running)
subject_id	string
subject_kind	string

TaskUpdate

Field	Type	About
last_error	object
progress_den	integer
progress_num	integer
state	string (running \| succeeded \| failed \| cancelled)

ThemeEvent

Field	Type	About
theme required	string (system \| light \| dark)

Timeline

The framework's sequence document (R44, 05 §6). One video track, V1, contiguous from 0, and up to eight audio tracks.

Field	Type	About
created_at required	string
duration_s required	number	V1's end, computed and never stored.
etag required	string
id required	ULID
name required	string
revision required	integer	Rises by one on every write. The ETag.
studio_id required	string \| null	The studio that created it; null for the launcher's own (M8 Q11).
target required	TimelineTarget
tracks required	TimelineTrack[]
updated_at required	string

TimelineAppend

Field	Type	About
asset_id required	ULID
timeline_id	ULID
track	string

TimelineClip

A reference with in and out points; sources are never modified or copied (R44). `in` and `out` are times in the source, `at` is where it sits in the sequence, and an image clip uses `hold` instead.

Field	Type	About
asset_id required	ULID
at	number	Where it sits in the sequence. Assigned when clips are laid end to end.
audio	boolean	Whether a video clip's own sound plays under it. Defaults to true.
gain_db	number	Applied to this clip's own sound. Defaults to 0.
hold	number	How long an image is held. Images only, and never with in or out.
in	number	Where the clip starts in its source. Defaults to 0.
out	number	Where it ends in its source. Defaults to the source's end.
studio_id	string \| null	The studio whose asset this is, for the clip's hue and name. Null when the caller could not learn it from an item it may read (M8 Q11). Set by the daemon, and ignored in a request.
transition_in	TimelineTransition

TimelineCreate

Field	Type	About
clips	TimelineClip[]	Laid end to end from 0, on V1 for video and images and on A1 for sound. Not with `tracks`.
name required	string
target required	TimelineTargetInput
tracks	TimelineTrack[]	The whole document. Not with `clips`.

TimelineOpened

Field	Type	About
opened required	boolean
surface required	string	browser or app.

TimelinePage

Everything in Page, and:

Field	Type	About
items	Timeline[]

TimelineRevert

Field	Type	About
revision required	integer

TimelineRevision

Field	Type	About
clip_count required	integer
duration_s required	number
revision required	integer
saved_at required	string

TimelineRevisionPage

Everything in Page, and:

Field	Type	About
items	TimelineRevision[]

TimelineTarget

What every clip is conformed to (R44, R47). Geometry and rates only: the codec belongs to the export's preset, not the document (M8 Q9). Output is always stereo, and is tagged BT.709 limited range when it is re-encoded.

Field	Type	About
fps required	number (23.976 \| 24 \| 25 \| 29.97 \| 30 \| 48 \| 50 \| 59.94 \| 60)	One of the rates the daemon knows exactly; 23.976, 29.97 and 59.94 are 24000/1001, 30000/1001 and 60000/1001, which no JSON number writes exactly.
height required	integer	Even.
sample_rate required	integer (44100 \| 48000)
width required	integer	Even.

TimelineTargetInput

The target as a request gives it; `sample_rate` defaults to 48000.

Field	Type	About
fps required	number (23.976 \| 24 \| 25 \| 29.97 \| 30 \| 48 \| 50 \| 59.94 \| 60)
height required	integer
sample_rate	integer (44100 \| 48000)
width required	integer

TimelineTrack

Field	Type	About
clips required	TimelineClip[]
gain_db	number
kind required	string (video \| audio)
name	string	V1, A1, A2 — kind and position. Assigned by the daemon, and ignored in a request.

TimelineTransition

The one transition (01 §14). It is centred on the cut and takes half its duration of handle from each side, so adding one moves no clip.

Field	Type	About
duration required	number
type required	string (dissolve)

TimelineUpdate

Field	Type	About
name	string
target	TimelineTargetInput
tracks	TimelineTrack[]

API types

AdoptRequest

Asset

AssetKind

Capability

Error

ExportPlan

ExportPreset

ExportReason

ExportRequest

GapEvent

Handoff

HandoffRequest

InboxEntry

InboxEvent

InboxPage

Item

ItemCreate

ItemEvent

ItemInput

ItemPage

ItemUpdate

JSONObject

Job

JobError

JobEvent

JobKind

JobLogEnd

JobLogLine

JobLogStep

JobPage

JobState

KVDoc

KVKey

KVKeyPage

LogAppend

Me

Page

QuotaUse

Record

RecordPage

Session

SessionCreate

SessionDuplicate

SessionPage

SessionUpdate

ShutdownEvent

StepRun

StudioIdValue

Tag

TaskCreate

TaskUpdate

ThemeEvent

Timeline

TimelineAppend

TimelineClip

TimelineCreate

TimelineOpened

TimelinePage

TimelineRevert

TimelineRevision

TimelineRevisionPage

TimelineTarget

TimelineTargetInput

TimelineTrack

TimelineTransition

TimelineUpdate

ULID