Runs and assets

A manual run plans the whole active graph. The engine answers before the attempts finish.

Start a run

curl -X POST \
  -H "Authorization: Bearer $PUPPI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"force": true}' \
  "$PUPPI_ENGINE_URL/api/v1/environments/hello/runs"

202 means the run was accepted. force defaults to false. true bypasses the staleness gate. The body is the run, plus attempts and outcome.

status is running when the run started, or queued when a run of the same plan is already in flight. A trigger that arrives while one is already queued comes back as that queued run.

GET /api/v1/environments/:name/runs lists the newest 100 runs, without attempts. GET /api/v1/runs/:id returns one run with its attempts. Each attempt has id, asset_key, partition, number, status, executor, error_class, error_message, observed_reads, secret_versions, bindings, logs, timings, started_at, and finished_at. outcome is the per-asset summary. success and failed_by_check stay distinct.

List assets

GET /api/v1/environments/:name/assets returns every asset in the active deployment. Each row has key, definition, latest, latest_attempt, next_run_at, and staleness.

definition includes role, group, visibility, deps, connections, schema, schedule, and code_version. latest is the current materialization, or null. latest_attempt is the newest attempt for that asset across every run, or null. next_run_at is computed from the schedule. It is null while schedules are paused. staleness is one verdict per partition: current, or stale with reasons.

curl -s \
  -H "Authorization: Bearer $PUPPI_API_TOKEN" \
  "$PUPPI_ENGINE_URL/api/v1/environments/hello/assets/core/customer"

The key keeps its slash. The detail adds history, newest first. Each history row has retained: true when the engine still has the data. A rollback to a row that is not retained is 422 data_not_retained.

Staleness

GET /api/v1/environments/:name/staleness returns the same verdicts, one object per asset and partition, with asset_key and partition on each.