REST API
The API is the only surface developers and CI systems interact with. All
/v1 endpoints (except the schema and console) require a tenant-scoped
bearer token. The machine-readable spec lives at docs/api/openapi.yaml
in the repository.
Deployments
POST /v1/applications/{app}/environments/{env}/deployments
Multipart upload creating a new immutable release.
| Field | Required | |
|---|---|---|
config | yes | The project pagifier.yaml |
archive | yes | app.zip (sources or prebuilt artifact) |
signature | per policy | cosign sign-blob signature of the archive (base64) |
Query wait=true streams NDJSON progress lines until the release is
Available or Failed; the final line carries done, success, url, and
the build log tail on failure.
Response 201 includes releaseId, the content-addressed image,
artifactSha256, statusUrl, and configChanges — a human-readable diff
of the resolved configuration versus the active release.
Errors: 400 invalid configuration (with the full problem list),
403 signing policy violations.
POST /v1/applications/{app}/environments/{env}/rollback
Points the application at a previous release — no rebuild, the existing
image redeploys. Body {"releaseId": "..."} targets a specific release;
an empty body targets the most recent superseded one. 409 when the
target is already active or not deployable.
Validation & schema
POST /v1/validate
Dry run: resolves the posted pagifier.yaml (raw body or multipart
config) against live platform templates. 200 returns
{valid: true, resolved: {...}}; 400 returns every problem found.
GET /v1/schema/pagifier.json (public)
JSON Schema for project files — point yaml-language-server at it for
editor autocomplete.
Inspection
| Endpoint | Returns |
|---|---|
GET /v1/applications | The caller's applications with live phase, URL, canary weight, active color |
GET /v1/applications/{app}/environments/{env} | Full status including the active release's phase, image, message, and build log |
GET .../releases?limit=N | Deployment history, newest first |
GET .../releases/{id} | One history record plus live phase |
GET .../releases/{id}/config | The fully resolved configuration snapshot |
GET .../events | Platform audit trail merged with Kubernetes events |
GET .../logs?tailLines=N | Application pod logs, plain text |
Operational
| Endpoint | |
|---|---|
GET /healthz | Liveness |
GET /readyz | Readiness (checks the store) |
GET /metrics | Prometheus metrics |
GET /console | The web console (public page; data calls authenticated) |
Authentication
Authorization: Bearer <token>. Tokens are tenant-scoped service
credentials provisioned by the platform team; every resource a token can
see or touch belongs to its tenant. Invalid or missing tokens get 401;
resources outside the tenant read as 404.