Environments

An environment is the place a deployment runs. These routes create one, place it, and write its bindings and secrets.

Create and list

GET /api/v1/environments lists the environments for the caller. POST creates one. name, storage_prefix, and executor are required. executor is local or remote. kind is persistent (the default) or preview. strict defaults to false.

curl -X POST \
  -H "Authorization: Bearer $PUPPI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"hello","storage_prefix":"hello","executor":"local"}' \
  "$PUPPI_ENGINE_URL/api/v1/environments"

201 returns the environment: id, name, kind, git_ref, storage_prefix, strict, schedules_paused, executor, active_deployment_id, and inserted_at. GET /api/v1/environments/:name returns the same object. An unknown name is 404.

local runs each attempt on the engine host. remote queues the attempt for a worker in the tenant’s pool.

Place every environment

POST /api/v1/placement sets executor on every environment the caller owns. An attempt that has already started keeps the placement it started with.

curl -X POST \
  -H "Authorization: Bearer $PUPPI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"executor":"local"}' \
  "$PUPPI_ENGINE_URL/api/v1/placement"

The body is {"data": {"executor": "local", "environments": […]}}. POST /api/v1/environments/:name/placement sets the executor on that one environment and returns the environment.

Bind a connection

GET /api/v1/environments/:name/bindings lists bindings. PUT /api/v1/environments/:name/bindings/:connection writes one. The body may include config, secret_refs, and mode. mode defaults to live. read_only makes ctx.emit fail for assets stored on this binding. Secret values are not in the response. secret_refs names them.

curl -X PUT \
  -H "Authorization: Bearer $PUPPI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"config":{"host":"127.0.0.1"},"secret_refs":{"password":"warehouse_password"}}' \
  "$PUPPI_ENGINE_URL/api/v1/environments/hello/bindings/warehouse"

DELETE removes the binding and returns {"data": {"name": "warehouse"}}.

Write a secret

GET /api/v1/environments/:name/secrets lists names. Each row has name, backend, version, and rotated_at. The value is never returned.

curl -X PUT \
  -H "Authorization: Bearer $PUPPI_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value":"postgres"}' \
  "$PUPPI_ENGINE_URL/api/v1/environments/hello/secrets/warehouse_password"

DELETE retires the secret in its backend and removes the row. The response is {"data": {"name": "warehouse_password"}}.

Pause schedules

POST /api/v1/environments/:name/schedules/pause sets schedules_paused. POST …/schedules/resume clears it. Both return the environment. A manual POST …/runs still starts.