API Reference

Vesta’s API server exposes a RESTful API for every platform operation — the CLI and web UI are both built on it. All paths below are relative to /api/v1 unless noted.

Authentication

Most endpoints require a bearer token. Create one under API tokens, then:

curl -H "Authorization: Bearer <token>" https://<api-host>/api/v1/apps

Tokens carry scopes (read, write, deploy) and users carry roles (admin, developer, viewer). Write endpoints reject the viewer role.

Unauthenticated endpoints

Projects & environments

Apps

Apps live inside a project, so they are created under the project and addressed by app ID afterwards.

Deployments

Deploy request body — environment is required:

{
  "environment": "production",
  "tag": "v1.2.3",
  "reason": "hotfix for #412",
  "commitSHA": "7f3c9a1"
}

To deploy from git instead of a pre-built tag, send type: "git" with a git reference:

{
  "environment": "production",
  "type": "git",
  "git": { "branch": "main" }
}

Builds

Config, secrets & env vars

Observability & operations

Notifications & alerts

Add-ons

Cost & quotas

Cost responses accept ?window= (24h, 7d, 30d, 90d, or a Go duration) and ?groupBy=app|environment. Every response reports the rate card it used and whether those rates are the built-in estimate, so a figure can be checked rather than taken on trust.

Quota responses report committed — what the environment’s apps add up to at their autoscaling maximum — alongside wouldExceed, which says whether enforcing the configured quota would already refuse work.

Git connections & repositories

Registry credentials

Creating a credential accepts scope (global or project) and, for a project-scoped one, project. Only an administrator can create a global credential. A credential you may not use is absent from the listing and returns 404 rather than 403 when addressed directly.

Platform settings

GET /settings/security is readable by any authenticated user; writing it requires an administrator. Under the restricted profile an app runs as a non-root user with a read-only filesystem, so a developer who cannot see the profile has no way to explain their own app’s failure to start.

Its observed field reports, per environment, whether network policies are actually being enforced — which is a different question from whether isolation is turned on, because NetworkPolicy is enforced by the cluster’s network plugin rather than by Kubernetes.

Users, teams & audit