API

The API is the HTTP control plane. The base path is /api/v1. The CLI is the client you use day to day. These pages are the routes it calls.

Send Authorization: Bearer $PUPPI_API_TOKEN. The compose stack’s token is dev. A missing or wrong token is 401 with {"error": "unauthorized"}. With no token configured, the API is open and the process warns at boot.

Most successes are {"data": …}. The bundle routes and the executor lease return the object itself. A refusal is {"error": "<reason>"}, and a refusal that carries extra values adds "detail". A validation failure is 422:

{"error": "invalid", "details": {"name": ["can't be blank"]}}

404 is not_found, not_in_active_manifest, or no_such_materialization. Every other refusal is 422.

Environment routes take the environment name. A deployment, a run, and a materialization are addressed by id.

Method	Path	Page
GET	/health	Health and bundles
GET, HEAD, PUT	/bundles/:hash	Health and bundles
GET, POST	/environments	Environments
GET	/environments/:name	Environments
POST	/placement	Environments
POST	/environments/:name/placement	Environments
GET	/environments/:name/bindings	Environments
PUT, DELETE	/environments/:name/bindings/:name	Environments
GET	/environments/:name/secrets	Environments
PUT, DELETE	/environments/:name/secrets/:name	Environments
POST	/environments/:name/schedules/pause	Environments
POST	/environments/:name/schedules/resume	Environments
GET, POST	/environments/:name/deployments	Deployments
GET	/deployments/:id	Deployments
POST	/deployments/:id/activate	Deployments
GET, POST	/environments/:name/runs	Runs and assets
GET	/runs/:id	Runs and assets
GET	/environments/:name/assets	Runs and assets
GET	/environments/:name/assets/*key	Runs and assets
GET	/environments/:name/staleness	Runs and assets
GET	/materializations/:id	Materializations
GET	/materializations/:id/upstream	Materializations
POST	/environments/:name/rollbacks	Materializations
POST	/executor/claims/lease	Executor claims
GET	/executor/claims/bundle	Executor claims
POST	/executor/claims/events	Executor claims
POST	/executor/claims/heartbeat	Executor claims
POST	/executor/claims/complete	Executor claims