REST API

The same API serves both sides of Pagifier. Developers validate, deploy, inspect, and approve. Platform engineers manage connections, pipelines, roles, and tokens. RBAC decides which part each token may touch.

All /v1 endpoints except the schema and signed Git webhook receiver require a 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, 409 when the config's ingress (host, path) pair is already owned by another application — the response names the owner (host www.abc.com path / is already owned by acme/frontend in prod).

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

Git delivery

Developer-facing pipeline endpoints:

Endpoint	Purpose
GET /v1/pipeline-templates	List the installed control-manifest templates
POST /v1/pipeline-templates/{template}/render	Render a commit-ready version 2 pagifier.toml
GET /v1/pipelines	List active Git-observed pipelines
GET /v1/pipelines/{pipeline}	Read one resolved pipeline and its manifest commit
GET /v1/pipeline-runs?pipelineId=...	List build, approval, and deploy runs
GET /v1/pipeline-runs/{run}	Read one run and its approvals
POST /v1/pipeline-runs/{run}/approval	Approve or reject a gated deployment
GET /v1/artifacts/{artifact}	Read immutable build artifact metadata

Platform-managed endpoints:

Endpoint	Purpose
POST /v1/git-connections	Store an encrypted GitHub, GitLab, or generic provider credential
GET /v1/git-connections	List connection health without exposing credentials
POST /v1/git-connections/{connection}/test	Resolve a repository's protected ref
PUT /v1/git-connections/{connection}/credential	Rotate the provider and optional webhook secret
POST /v1/pipelines	Fetch, validate, snapshot, and activate a control manifest
POST /v1/hooks/git/{tenant}/{connection}	Public signed provider webhook receiver

See Deploy from Git for the developer flow and Git integration for provider setup.

Tokens and roles

Endpoint	Purpose
POST /v1/tokens	Create an expiring token and scoped role bindings; secret returned once
GET /v1/tokens	List token metadata, never secrets
DELETE /v1/tokens/{token}	Revoke immediately
GET /v1/roles	List built-in and custom roles
PUT /v1/roles/{role}	Create or replace a custom role
GET /v1/bindings	List principal bindings

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>.

Normal tokens are opaque pgf_... credentials backed by a principal, expiry, revocation state, and role bindings. Bindings may target the tenant, one application, repository, application/environment, or infrastructure target. The API checks the required permission and resource scope on every call.

Legacy tokens from PAGIFIER_API_TOKENS remain tenant bootstrap administrators during migration. Invalid or missing tokens get 401; valid tokens outside their allowed scope get 403.