API Reference

Authentication

All API endpoints (except /api/health and /api/v1/github/webhook) require authentication. Vardo supports two authentication methods:

Session cookies

The web dashboard uses session-based authentication managed by Better Auth. Sessions are stored in PostgreSQL, expire after 7 days (configurable) and are refreshed every 24 hours. When using the API from a browser context, the session cookie is sent automatically.

API tokens

Create API tokens from User Settings > API Tokens in the dashboard. Tokens use a vardo_ prefix, are stored as SHA-256 hashes and displayed only once at creation time. Tokens are scoped to a specific organization and user.

curl -s https://vardo.example.com/api/v1/organizations/{orgId}/apps \
  -H "Authorization: Bearer vardo_<your-token>"

When authenticating via token, the org context is derived from the token itself -- no cookie is required. This makes tokens suitable for CI/CD pipelines, scripts and API integrations.

Base URL

All versioned API endpoints follow the pattern:

/api/v1/organizations/{orgId}/...

The orgId is the organization ID (not the slug). You can find it from the organization list endpoint or from the dashboard URL.

Rate limits

Vardo uses a Redis-backed sliding window rate limiter applied per route via the withRateLimit wrapper.

When rate-limited, the API returns HTTP 429 with a Retry-After header indicating seconds until the oldest request in the window ages out. If Redis is unavailable, requests are allowed through -- a Redis outage won't take down the API.

Error format

All error responses follow a consistent shape:

{
  "error": "Human-readable error message"
}

Endpoints

Health

Organizations

Members

Invitations

Projects

Project environments

Project stats

Apps

Create app body

{
  "displayName": "My App",
  "name": "my-app",
  "description": "Optional description",
  "source": "git",
  "deployType": "dockerfile",
  "gitUrl": "https://github.com/user/repo",
  "gitBranch": "main",
  "containerPort": 3000,
  "autoDeploy": true,
  "generateDomain": true,
  "projectId": "optional-project-id"
}

source -- "git" or "direct"

deployType -- "compose", "dockerfile", "image", "static", "nixpacks" or "railpack"

Additional fields depending on deploy type:

• image: imageName (required)
• compose: composeContent (inline YAML)
• git sources: gitUrl, gitBranch, rootDirectory
• resource limits: cpuLimit (cores, max 64), memoryLimit (MB, 64-65536), diskWriteAlertThreshold (bytes)
• volumes: persistentVolumes array of { name, mountPath }
• ports: exposedPorts array of { internal, external?, protocol?, description? }
• connection info: connectionInfo array of { label, value, copyRef? }

Deployments

Deploy body (optional)

{
  "environmentId": "env_abc123",
  "groupEnvironmentId": "genv_abc123",
  "deployAll": true
}

• Omit the body or send {} to deploy to the default (production) environment.
• Set deployAll: true to trigger a project-wide deploy of all apps in the project.
• The response is a Server-Sent Events stream with log, stage, tier and done events.

Branches

Environment variables

Domains

Environments

Environment types: "production", "staging", "preview".

Monitoring

Org-level stats

Backups

Storage backends: S3, Cloudflare R2, Backblaze B2, SSH/SFTP, local filesystem.

Backup strategies are per-volume: tar for file volumes, pg_dump for Postgres.

Cron jobs

Cron job types: "command" (runs inside the container) or "url" (HTTP request).

Tags

Transfers

Deploy keys

API tokens

Notifications

Channel types: email (SMTP, Mailpace, Resend, Postmark), webhook (HTTP POST) and Slack (via webhook URL).

Digest

Activity log

Search

GitHub integration

Templates

DNS check

System alerts

Admin endpoints

All admin endpoints require isAppAdmin on the authenticated user.

Admin overview and health

Admin management

Admin mesh operations

These endpoints are only available when the mesh feature flag is enabled.

Mesh peer-to-peer endpoints

These are called instance-to-instance over WireGuard tunnels -- not by end users.

MCP server

Vardo exposes a Model Context Protocol server for AI agent integration at /api/mcp. Authenticate with a Bearer token (API token).

Available MCP tools (read-only):

Webhook format

Vardo receives GitHub webhooks at /api/v1/github/webhook. The webhook secret is verified using HMAC-SHA256 (x-hub-signature-256 header).

Supported events

push -- Triggers auto-deploy for apps that match the repository URL and branch with autoDeploy enabled.

{
  "ok": true,
  "deployments": [
    { "app": "my-app", "deploymentId": "abc123", "success": true }
  ]
}

pull_request -- Creates or destroys preview environments.

• opened, reopened, synchronize -- Creates a preview project environment for the matching project, deploys all apps and posts preview URLs as a PR comment.
• closed -- Destroys the preview environment and tears down all containers.

{
  "ok": true,
  "preview": {
    "groupEnvironmentId": "genv_abc123",
    "domains": [
      { "appName": "web", "domain": "pr-42-web.example.com" }
    ],
    "deployed": true
  }
}

All other event types are acknowledged with {"ok": true, "skipped": "<event-type>"}.

Setup endpoints

These endpoints are used during initial setup only and don't require authentication (the setup wizard runs before any user exists).