Skip to Content
Puppi

API

Call the engine over HTTP.

The base path is /api/v1. The CLI is the usual client. These pages document the routes it calls.

Send Authorization: Bearer with a per-user API key from puppi login. That key acts as that user in the tenant it was approved for.

GET /whoami returns the user and tenant:

{"data": {"user": {"id": "usr_…", "email": "ada@example.com", "name": "Ada"}, "tenant": {"id": "ten_…", "name": "usr_…", "slug": "usr-…"}}}

DELETE /session revokes the API key on the request.

POST /device/code and POST /device/token are the device authorization grant, outside /api/v1. Their bodies are the RFC 8628 objects, not {"data": …}. The signed-in page at /device is where the user confirms the code.

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

A missing or wrong key is 401 {"error": "unauthorized"}. local_not_allowed is 403. An owner-or-admin route returns 403 forbidden for a member. 404 is not_found, not_in_active_manifest, or no_such_materialization. A validation failure is 422:

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

POST /runs/:id/cancel on a finished run is 409 already_settled. Other refusals are named on the route that returns them.

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

MethodPathPage
GET/healthHealth and bundles
GET, HEAD, PUT/bundles/:hashHealth and bundles
GET, POST/environmentsEnvironments
GET/environments/:nameEnvironments
POST/placementEnvironments
POST/environments/:name/placementEnvironments
GET/environments/:name/bindingsEnvironments
PUT, DELETE/environments/:name/bindings/:nameEnvironments
GET/environments/:name/secretsEnvironments
PUT, DELETE/environments/:name/secrets/:nameEnvironments
GET, PUT, PATCH, DELETE/environments/:name/webhookEnvironments
POST/environments/:name/webhook/rotationEnvironments
POST/environments/:name/webhook/testEnvironments
POST/environments/:name/schedules/pauseEnvironments
POST/environments/:name/schedules/resumeEnvironments
GET, POST/environments/:name/deploymentsDeployments
GET/deployments/:idDeployments
POST/deployments/:id/activateDeployments
GET, POST/environments/:name/runsRuns and assets
GET/runs/:idRuns and assets
POST/runs/:id/cancelRuns and assets
GET/runs/:id/eventsRuns and assets
GET/environments/:name/assetsRuns and assets
GET/environments/:name/assets/*keyRuns and assets
GET/environments/:name/stalenessRuns and assets
GET/materializations/:idMaterializations
GET/materializations/:id/upstreamMaterializations
POST/environments/:name/rollbacksMaterializations
GET, POST/worker-tokensWorkers
DELETE/worker-tokens/:idWorkers
GET/workersWorkers
GET/workers/socketWorkers