Deployments

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 $PUPPI_API_TOKEN" \
  "$PUPPI_ENGINE_URL/api/v1/environments/hello/deployments"

Each row has id, environment_id, status, active, git, bundle_ref, sdk_version, 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.

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 $PUPPI_API_TOKEN" \
  -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"
}

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.

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.

Activate

POST /api/v1/deployments/:id/activate moves the pointer to a deployment whose status is ready. The body is {}. This is how you roll the code back to an older id. See Roll back a deployment.

curl -X POST \
  -H "Authorization: Bearer $PUPPI_API_TOKEN" \
  -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.