API Reference
The engine serves a REST API under /api/v1 on port 9090. All endpoints require a session cookie except setup, auth, webhooks, and self-update routes.
Projects
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/projects | Create project |
| GET | /api/v1/projects | List all projects |
| GET | /api/v1/projects/:id | Get project |
| PATCH | /api/v1/projects/:id | Update branch / port / buildContext |
| PATCH | /api/v1/projects/:id/env | Update env vars (encrypted at rest) |
| DELETE | /api/v1/projects/:id | Delete project |
| POST | /api/v1/projects/:id/rollback | Rollback to previous deployment |
| POST | /api/v1/projects/:id/cancel-deploy | Cancel in-progress deployment |
| POST | /api/v1/projects/:id/generate-pipeline | AI-generate GitHub Actions CI |
Deployments & environments
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/deploy | Trigger deployment { projectId } |
| GET | /api/v1/deployments | List all deployments |
| GET | /api/v1/status | Current active deployment |
| POST | /api/v1/projects/:id/environments/:envId/promote | Promote build from source environment |
GitHub integration
| Method | Path | Description |
|---|---|---|
| GET | /api/auth/github/install | Start official App install (redirects to GitHub) |
| GET | /api/auth/github/callback | Install callback (via versiongate.tech relay) |
| GET | /api/github/repos | List repositories for the installation |
| GET | /api/github/repos/:owner/:repo/branches | List branches |
| POST | /api/webhooks/github | Direct GitHub signature webhook (dev / advanced) |
| POST | /api/webhooks/github/relay | Fan-out from versiongate.tech (hop-signed) |
Public relay routes on versiongate.tech: GET /api/github/callback, POST /api/github/register, POST /api/webhooks/github.
System
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/system/preflight | Host compatibility checks (no DB required) |
| GET | /api/v1/system/server-stats | Host CPU / memory / disk / network |
| POST | /api/v1/system/reconcile | Manual crash-recovery trigger |
| GET | /health | Engine health check |
Setup
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/setup/status | Returns { configured: boolean } |
| POST | /api/v1/setup/apply | Apply initial config { domain, databaseUrl, geminiApiKey? } |
Full environment-variable reference lives in the repository's docs/SETUP.md.
Authentication
Create the first admin with
bun run create-admin, then sign in at /login. API requests use the session cookie issued on login.