/v1 API reference

The management API is versioned under /v1 and protected by a bearer token (see Authentication & RBAC). Roles below are the minimum required; the super-admin bypasses project membership. Handlers live under src/api/; this page groups the surface by resource.

note

The route table is enforced in code (src/api/* + src/app.rs) and summarized in ADR-008. If you build from a newer revision, treat the handlers as authoritative over this page.

Health & node

Method	Path	Auth	Description
GET	/healthz	public	Liveness — {"status":"ok"}
GET	/v1/node	Viewer	Node metadata, host CPU/mem, disk usage, control_domain

Auth, users & tokens

Method	Path	Auth	Description
POST	/v1/auth/login	public (credentials)	Username + password → session token
GET	/v1/me	any token	Current principal + memberships
POST	/v1/bootstrap	admin token	One-time admin account creation
GET / POST	/v1/users	Admin	List / create users
DELETE	/v1/users/{user_id}	Admin	Delete a user
GET / POST	/v1/api-tokens	any token	List / mint API tokens
DELETE	/v1/api-tokens/{token_id}	owner	Revoke an API token

Projects & members

Method	Path	Auth	Description
GET	/v1/projects	Viewer	List projects you belong to
POST	/v1/projects	super-admin	Create a project
GET	/v1/projects/{id}	Viewer	Project details
PUT	/v1/projects/{id}	Admin	Update shared env / limits
DELETE	/v1/projects/{id}	Admin	Delete (must be empty)
GET	/v1/projects/{id}/members	Viewer	List members + roles
POST	/v1/projects/{id}/members	Admin	Add member with role
DELETE	/v1/projects/{id}/members/{user_id}	Admin	Remove member

Services

Method	Path	Auth	Description
GET / POST	/v1/services	Viewer / Operator	List / create services
GET	/v1/services/{id}	Viewer	Service config (env redacted for Viewer)
PUT / DELETE	/v1/services/{id}	Operator	Update / delete
GET	/v1/services/{id}/logs	Operator	Recent logs
GET	/v1/services/{id}/logs/stream	Operator	Live SSE log tail
GET	/v1/services/{id}/metrics	Viewer	cgroup v2 + procfs metrics
GET	/v1/services/{id}/requests	Viewer	Recent ingress access-log entries
POST	/v1/services/{id}/uploads	Operator	Stream a tar.zst build context → upload_id

Domains

Method	Path	Auth	Description
GET / POST	/v1/services/{id}/domains	Viewer / Operator	List / attach domains
GET	/v1/services/{id}/domains/{domain_id}	Viewer	Domain details
POST	/v1/services/{id}/domains/{domain_id}/verify	Operator	Verify ownership (HTTP-01 challenge)
DELETE	/v1/services/{id}/domains/{domain_id}	Operator	Detach domain
GET	/.well-known/denia-challenge/{token}	public	Verification token (returned only when request Host matches)

Deployments

Method	Path	Auth	Description
POST	/v1/deployments	Operator	Create deployment (Git / ExternalImage / Upload)
GET	/v1/deployments/{id}	Viewer	Deployment status + artifact
GET	/v1/deployments/{id}/logs/stream	Operator	SSE build/deploy log
GET	/v1/services/{id}/deployments	Viewer	List a service's deployments

Jobs

Method	Path	Auth	Description
GET / POST	/v1/jobs	Viewer / Operator	List / create jobs
GET	/v1/jobs/{id}	Viewer	Job config
PUT / DELETE	/v1/jobs/{id}	Operator	Update / delete
POST	/v1/jobs/{id}/run	Operator	Trigger a run now
GET	/v1/jobs/{id}/runs	Viewer	List runs

Console

Method	Path	Auth	Description
GET	/v1/services/{id}/console/replicas	Operator	List attachable replicas
POST	/v1/services/{id}/console/tickets	Operator	Mint a single-use 30s ticket
GET	/v1/services/{id}/console/ws	ticket	WebSocket upgrade (ticket in query, outside bearer)

Registries & credentials

Method	Path	Auth	Description
GET / POST	/v1/projects/{id}/registries	Viewer / Operator	List / add external registry (payload SOPS-encrypted)
GET	/v1/projects/{id}/registries/{registry_id}	Viewer	Registry metadata (no credential payload)
PUT / DELETE	/v1/projects/{id}/registries/{registry_id}	Operator	Update / delete
POST / DELETE	/v1/projects/{id}/credentials/git	Operator	Store / remove a Git deploy key

Hosted registry control & OCI cache

Method	Path	Auth	Description
GET	/v1/registry/repositories	Viewer	List hosted-registry repositories (project-filtered)
GET	/v1/registry/status	Viewer	Disk usage, blob count, last GC
POST	/v1/registry/gc	super-admin	Trigger hosted-registry GC
GET	/v1/oci/cache/status	Viewer	External-pull layer-cache stats
POST	/v1/oci/cache/gc	Operator	Trigger layer-cache GC

The OCI Distribution /v2 endpoints are documented separately: /v2 registry API.