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.
| 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 |
GET, PUT, PATCH, DELETE | /environments/:name/webhook | Environments |
POST | /environments/:name/webhook/rotation | Environments |
POST | /environments/:name/webhook/test | 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 |
POST | /runs/:id/cancel | Runs and assets |
GET | /runs/:id/events | 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 |
GET, POST | /worker-tokens | Workers |
DELETE | /worker-tokens/:id | Workers |
GET | /workers | Workers |
GET | /workers/socket | Workers |