Skip to Content
Puppi

Environments

Create an environment, and bind its connections.

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 remote or hosted. kind is persistent (the default) or preview. strict defaults to false. A body that selects local is 403 {"error": "local_not_allowed"} and inserts nothing.

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

The body may also include signature and signing_key. signing_key is the public key ed25519:<base64>. signature is the signature over the environment’s name and storage_prefix. The engine stores both and does not check them. Creating a name that already exists does not replace a stored signature.

201 returns the environment: id, name, kind, git_ref, storage_prefix, strict, schedules_paused, alert_email, owner_id, executor, signature, signing_key, active_deployment_id, and inserted_at. GET /api/v1/environments/:name returns the same object. An unknown name is 404. alert_email defaults to true. owner_id is the API key’s user, or null when the caller has no user. A value in the create body is ignored.

Choose hosted for Puppi-managed execution or remote for your worker pool. remote queues the attempt for a worker in the tenant’s pool. That mode’s public name is self-hosted. A hosted run reaches public addresses only. A private database needs a public address or a self-hosted worker.

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 <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"executor":"remote"}' \
  "$PUPPI_ENGINE_URL/api/v1/placement"

A body that selects local is 403 {"error": "local_not_allowed"} and writes nothing. 200 returns {"data": {"executor": "remote", "environments": […]}}. POST /api/v1/environments/:name/placement sets the executor on that one environment and returns the environment. The same local refusal applies.

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, mode, signature, and signing_key. 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.

signature covers the binding’s name, type, config, secret refs, and mode. A re-bind that omits signature keeps the stored signature. A re-bind that sends one replaces the stored signature and key. The response includes both fields.

curl -X PUT \
  -H "Authorization: Bearer <api-key>" \
  -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 <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"value":"postgres"}' \
  "$PUPPI_ENGINE_URL/api/v1/environments/hello/secrets/warehouse_password"

{"on_worker": true} declares the name and stores no value. The row’s backend is worker and version is null. If that name already held a value, the value is deleted first. puppi worker list shows a connected worker that does not have the file.

curl -X PUT \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"on_worker":true}' \
  "$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.

Failure email

alert_email defaults to true. An opening alert emails the environment’s owner when they are a confirmed member of the tenant, or the tenant’s confirmed owners and admins otherwise. PUT /api/v1/environments/:name/alert-email with {"enabled": false} turns that mail off. The caller is an owner or an admin. A member is 403. A caller with no user is 403. The alert still opens. {"enabled": true} turns it back on.

PUT /api/v1/environments/:name/owner with {"owner_id": "<user id>"} changes the owner. The new owner must be a confirmed member of the tenant. Anyone else is 422 with {"error": "not_confirmed_member"}. An owner or an admin may call it. A member is 403. A caller with no user is 403. Another tenant’s environment is 404.

curl -X PUT \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}' \
  "$PUPPI_ENGINE_URL/api/v1/environments/hello/alert-email"
curl -X PUT \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"owner_id":"usr_01HZX3QK7Y8B2N4M6P0R1S2T3V"}' \
  "$PUPPI_ENGINE_URL/api/v1/environments/hello/owner"

Failure webhook

One https URL per environment. Puppi POSTs a JSON event when an alert opens and when it resolves.

curl -X PUT \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks"}' \
  "$PUPPI_ENGINE_URL/api/v1/environments/hello/webhook"

enabled defaults to true. The response includes secret when the webhook is created. A later PUT keeps the secret and omits it. GET never returns the secret. POST /api/v1/environments/:name/webhook/rotation returns a new secret. DELETE removes the webhook. POST …/webhook/test sends one event and does not open an alert.

The body is JSON with "version": 1.

FieldMeaning
typealert.opened, alert.resolved, or alert.test
idAlert id. Null for a test.
environmentEnvironment name.
asset_keyAsset key. Null when the failure has no asset, and for a test.
partitionPartition. Null when there is none.
kindrun_failed or quarantined. Null for a test.
run_idRun id. Null for a test.
materialization_idThe materialization that run wrote, or null.
opened_atWhen the alert opened, ISO-8601. Null for a test.
urlLink to the run. A test links to the environment’s settings page.

The body does not include the attempt error. A URL that is not https, or a host that is not a public address, is refused and nothing is saved.

Puppi-Signature is t=<unix seconds>,v1=<hex>. v1 is HMAC-SHA256 of the string <t>.<raw body>, keyed with the secret, encoded as lowercase hex. A receiver verifies that HMAC over the raw body bytes and rejects the request when the absolute difference between now and t is more than 5 minutes. Puppi resolves the host when it sends and refuses a private, loopback, link-local, or Fly 6PN (fdaa::/16) address, including 0.0.0.0/8 and 100.64.0.0/10. It does not follow redirects.