API Reference

Complete REST API documentation for While — 43 endpoints.

Authentication

All endpoints require an API key passed via the Authorization header. Admin endpoints use the x-admin-secret header instead.

Base URL: https://while.sh

# Standard API (Bearer token)
Authorization: Bearer whl_your_api_key

# Admin API (shared secret)
x-admin-secret: your_admin_secret

Generate API keys via the admin endpoint or in Settings. Keys can be scoped: full, deploy, operate, read-only, sensors-only.

Projects

5 endpoints

GET/api/projects

List all projects with environments and deploy counts

POST/api/projects

Create a project with staging + production environments

{ "name": "my-app", "slug": "my-app" }

GET/api/projects/:id

Get project detail with environments, deployments, and domains

DELETE/api/projects/:id

Delete a project and all associated resources

GET/api/projects/:id/environments

List environments for a project

Deployments

4 endpoints

POST/api/environments/:id/deploy

Trigger a new deployment (guardrails enforced)

{ "gitUrl": "https://github.com/you/app", "commitMsg": "fix: bug" }

GET/api/environments/:id/deployments

List deployments for an environment

GET/api/deployments/:id

Get deployment details (status, logs, timing)

POST/api/deployments/:id/cancel

Cancel a running deployment

Databases

5 endpoints

GET/api/environments/:id/databases

List databases for an environment

POST/api/environments/:id/databases

Provision a managed PostgreSQL database

{ "engine": "postgresql" }

GET/api/databases/:id

Get database details

GET/api/databases/:id/credentials

Get database connection credentials (host, port, user, password)

DELETE/api/databases/:id

Delete a managed database

Domains

5 endpoints

GET/api/environments/:id/domains

List domains for an environment

POST/api/environments/:id/domains

Add a custom domain with auto-SSL

{ "domain": "app.example.com" }

GET/api/domains/:id

Get domain details including SSL status

POST/api/domains/:id/verify-ssl

Trigger SSL certificate verification

DELETE/api/domains/:id

Remove a custom domain

Environment Variables

3 endpoints

GET/api/environments/:id/vars

List all environment variables (secrets masked)

POST/api/environments/:id/vars

Set an environment variable (upsert)

{ "key": "DATABASE_URL", "value": "postgres://...", "isSecret": true }

DELETE/api/environments/:id/vars/:key

Delete an environment variable

Scale

3 endpoints

GET/api/environments/:id/scale

Get current replica count and status

PUT/api/environments/:id/scale

Scale to a specific number of replicas

{ "replicas": 3 }

POST/api/environments/:id/scale/restart

Rolling restart of all pods

Errors

3 endpoints

GET/api/environments/:id/errors

List errors (filterable by status: open/resolved)

POST/api/environments/:id/errors

Ingest an error from your application

{ "message": "TypeError: ...", "stack": "...", "file": "app.ts", "line": 42 }

PATCH/api/errors/:id

Resolve an error

Performance Metrics

2 endpoints

GET/api/environments/:id/metrics

Get current latency (p50/p95/p99), throughput, and error rate

POST/api/environments/:id/metrics

Record performance data points

{ "p50": 12, "p95": 45, "p99": 120, "throughput": 500, "errorRate": 0.01 }

Uptime Checks

5 endpoints

GET/api/environments/:id/uptime

List uptime checks

POST/api/environments/:id/uptime

Create an HTTP health check

{ "url": "https://myapp.com/health", "interval": 60 }

GET/api/environments/:id/uptime/summary

Get uptime status and percentages

POST/api/uptime/:id

Run an uptime check immediately

DELETE/api/uptime/:id

Delete an uptime check

Logs

1 endpoints

GET/api/environments/:id/logs

Query application logs (supports level, limit, since filters)

Webhooks

5 endpoints

GET/api/webhooks

List all webhook subscriptions

POST/api/webhooks

Create a webhook subscription

{ "url": "https://agent.com/hook", "events": ["deployment.failed"], "secret": "optional" }

GET/api/webhooks/:id

Get webhook details

DELETE/api/webhooks/:id

Delete a webhook subscription

POST/api/webhooks/:id/test

Send a test payload to the webhook URL

Admin

2 endpoints

POST/api/admin/api-keys

Generate a new API key (requires x-admin-secret header)

{ "tenantId": "...", "name": "my-key", "scopes": ["full"] }

GET/api/admin/api-keys

List API keys (no plaintext, requires x-admin-secret header)

Response Format

All endpoints return JSON. Successful responses return the resource directly. Errors return:

// Success (200/201)
{ "id": "clx...", "name": "my-app", ... }

// Error (400/401/403/404/500)
{ "error": "Project not found" }

// 403 — Guardrail blocked
{ "error": "Production is locked. Disable production lock in guardrail settings to deploy." }

// 403 — Rate limit
{ "error": "Deploy rate limit exceeded: 20/20 deploys in the last hour." }