Deployments
Ingest a manifest and move the active pointer.
A deployment is one manifest plus the bundle it names. The environment points at one of them. That pointer is active.
List
GET /api/v1/environments/:name/deployments returns every deployment of that environment, newest first. ?active=true returns the one the environment points at.
curl -s \
-H "Authorization: Bearer <api-key>" \
"$PUPPI_ENGINE_URL/api/v1/environments/hello/deployments" Each row has id, environment_id, status, active, git, bundle_ref, sdk_version, signature, signing_key, validation, allow_contract_changes, created_by, and inserted_at. The manifest itself is not in the response. GET /api/v1/deployments/:id returns one row. active is true when the environment’s pointer is this id. signature and signing_key are whatever the client stored. The engine does not check them. created_by is the user id of the API key that ingested the row, or null when the caller has no user.
Ingest
POST /api/v1/environments/:name/deployments stores a deployment. The bundle has to be uploaded first. See Health and bundles.
curl -X POST \
-H "Authorization: Bearer <api-key>" \
-H "Content-Type: application/json" \
-d @manifest-body.json \
"$PUPPI_ENGINE_URL/api/v1/environments/hello/deployments" The body puppi deploy sends has manifest set to the object in manifest.json, plus:
{
"bundle_ref": "sha256:<hash>",
"git": { "branch": "main", "sha": "<commit>" },
"sdk_version": "<version>",
"activate": true,
"allow_contract_changes": ["core/customer"],
"created_by": "cli",
"signature": "<base64>",
"signing_key": "ed25519:<base64>"
} signature is the client’s signature over the bundle digest (sha256:<hex>). Omit both fields to store an unsigned deployment. On a remote environment, a signing_key that no connected worker trusts is a warning in validation.warnings (untrusted_signing_key) and the deploy still succeeds. Activating an older deployment reuses the signature stored on that row.
manifest and bundle_ref are required. activate defaults to true, which moves the environment’s pointer when the manifest is accepted. git defaults to branch local and sha local when omitted. allow_contract_changes is the list of asset keys whose schema change a strict environment accepts. The same key cannot be repeated, and each key has to be an asset whose declared schema changed. A created_by field in the body is ignored.
201 means status is ready and, when activate is true, the deployment is active. 422 means status is failed. The row is still returned, and the environment’s pointer does not move. validation holds errors and warnings.
bundle_ref has to be sha256: followed by 64 lowercase hex characters. A host path, a relative path, a file:// URL, uppercase hex, or the wrong length is 422 with {"error": "invalid", "details": {"bundle_ref": ["must be sha256: followed by 64 lowercase hex characters"]}}. No deployment row is stored.
Activate
POST /api/v1/deployments/:id/activate moves the pointer to a deployment whose status is ready. The body is {}. The CLI command is puppi activate <id>. It prints activated <id>. See Roll back a deployment.
curl -X POST \
-H "Authorization: Bearer <api-key>" \
-H "Content-Type: application/json" \
-d '{}' \
"$PUPPI_ENGINE_URL/api/v1/deployments/<id>/activate" Activation re-checks stored columns against the schemas in that deployment. A mismatch quarantines the current latest in place.