Job structure

A Job is the unit of work you submit to AVFlow.

Request body

{
  "name": "room-recording-001",
  "metadata": { "customerId": "acme-42" },
  "sources": [],
  "nodes": [],
  "sinks": [],
  "policies": { "maxDurationSec": 7200, "idleTimeoutSec": 60 }
}

Fields

Field	Type	Required	Description
name	string	Yes	Human-readable name, max 128 characters. Used in API paths (/v1/jobs/:name). Must not contain whitespace or /, ?, #.
metadata	map	No	Opaque key/value pairs for your own bookkeeping (not interpreted by AVFlow).
sources	array	Yes	1–5 sources.
nodes	array	No	Processing nodes (mixers, ASR, etc.). May be empty.
sinks	array	Yes	1–3 sinks.
policies	object	No	Runtime limits. See Policies.

Updating a running job

Resubmit the full job with the same name via POST /v1/jobs (upsert). AVFlow applies changes without restarting the pipeline when possible.

Field	Hot-update
metadata	Immutable — rejected on update (400 INVALID_JOB).
sources / nodes / sinks	Add or remove components freely.
Node / sink inputs	Supported — node inputs reconnect; sink inputs use make-before-break switching (brief overlap while new upstream tracks appear). Changing an input’s select rewires that edge the same way.
Node / sink config	Partial support — depends on component type; encoding params are fixed after sink start.

Typical pattern when adding a source: submit an update that adds the source and extends downstream inputs (e.g. append the new source name to a mixer’s inputs array) in the same request.

Response fields

The server adds read-only fields:

Field	Description
id	Server-generated job ID (job_…)
status	Job lifecycle state — see Job status
createdAt / updatedAt	RFC 3339 timestamps
error	Job-level error, if any
componentStatus	Per-component status and error
usage	Present on running jobs only — cumulative per-component metrics (see Manage jobs)

Job status

The same status vocabulary is used by the control plane (D1) and the avflow runtime (GET /v1/jobs/:name when the job is reachable):

Status	Meaning
submitted	Accepted by the control plane; runtime not started yet
starting	Pipeline bootstrapping (Chrome, bridges, component attach)
running	Pipeline active (job.started recorded)
stopping	DELETE /v1/jobs/:name accepted (202); teardown in progress
completed	Finished normally (including user DELETE)
failed	Terminal failure

Typical progression: submitted → starting → running → completed or failed. On user DELETE, the runtime returns 202 with stopping; the control plane records stopping after that accept; job.completed or job.failed seals the row when teardown finishes.

Job-level details live in the error field when present. Per-component problems use componentStatus.<name>.status — commonly running, starting, or error (a component fault does not change the job’s top-level status until the job terminates).

GET /v1/jobs (list) returns summary rows from the control-plane store with the same status values.

Component shape

Sources, nodes, and sinks share:

{ "name": "my_src", "type": "livekit", "config": { } }

Nodes and sinks also require inputs — an array of upstream component names. See Wiring & DAG.

Limits

Resource	Limit
Sources per job	5
Sinks per job	3
video_mixer inputs	16