Health and bundles

GET /api/v1/health answers when the API is up. puppi dev waits on this route.

curl -s \
  -H "Authorization: Bearer $PUPPI_API_TOKEN" \
  "$PUPPI_ENGINE_URL/api/v1/health"

{"data": {"status": "ok", "sdk_version": "<version>"}}

sdk_version is the version a bundle has to be built against. The running engine reports its configured value.

Ask whether a bundle is stored

The hash is the sha256 of the bundle bytes. GET and HEAD return 200 when the engine has them, and 404 when it does not. puppi deploy sends HEAD and uploads only on 404.

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "Authorization: Bearer $PUPPI_API_TOKEN" \
  "$PUPPI_ENGINE_URL/api/v1/bundles/<sha256>"

A stored bundle answers {"ref": "sha256:<hash>"}. This route is not wrapped in data.

Upload the bytes

PUT sends the raw bundle as the body, not JSON. The body is limited to 64 MB. 201 means the bytes were new. 200 means the engine already had this hash. 422 with hash_mismatch means the bytes do not match the hash in the path.

curl -X PUT \
  -H "Authorization: Bearer $PUPPI_API_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @dist/bundle.js \
  "$PUPPI_ENGINE_URL/api/v1/bundles/<sha256>"

{"ref": "sha256:<hash>", "size": 12000, "created": true}

puppi deploy sends HEAD first and PUTs only when the engine answers 404. The manifest then names "bundle_ref": "sha256:<hash>". See Deployments.