Public API

The Public API lets you manage projects, web services and deployments programmatically — from CI pipelines, CLIs or any HTTP client. It is the only externally supported HTTP surface of the platform.

The base URL is https://api.runsite.app.

Authentication

Every request must include an API key in the Authorization header:

Authorization: Bearer ak_live_a1b2c3d4...

Create and manage keys from the dashboard — see API Keys. Requests without a valid, active key get 401 Unauthorized.

Note

The dashboard uses session-based authentication internally; for programmatic access always use API keys.

Describe the presented key

GET /api/v1/users/me/api-key

Returns the key’s id, name, key_prefix, scope and expiry — never the key itself. Use it to discover what a key is allowed to do before calling a write endpoint.

---

Projects

List projects

GET /api/v1/projects

Returns all projects owned by the authenticated user.

Create a project

POST /api/v1/projects
Content-Type: application/json

{
  "name": "my-app",
  "description": "My application"
}

Get project details

GET /api/v1/projects/{project_id}

---

Web Services

List web services

GET /api/v1/web-services

Create a web service

POST /api/v1/web-services
Content-Type: application/json

{
  "name": "backend-api",
  "project_id": "uuid",
  "git_repository_url": "https://github.com/user/repo",
  "port": 3000,
  "build_command": "npm run build",
  "min_instances": 1,
  "max_instances": 3
}

Get a web service

GET /api/v1/web-services/{web_service_id}

Deploy / Start / Restart / Stop

POST /api/v1/web-services/{web_service_id}/deploy
POST /api/v1/web-services/{web_service_id}/start
POST /api/v1/web-services/{web_service_id}/restart
POST /api/v1/web-services/{web_service_id}/stop

deploy and start are the same action — they start the existing image and do not rebuild. To build and release a new commit, create a deployment:

POST /api/v1/web-services/{web_service_id}/deployments

which returns the new deployment, including the id to poll with GET /api/v1/web-services/{web_service_id}/deployments/{deployment_id}.

restart re-rolls existing instances without rebuilding. stop releases compute (env vars and disks are preserved).

These four actions return the service’s lifecycle status — starting, stopping, restarting — and refuse a service blocked by the content policy or suspended for bandwidth.

Get container logs

GET /api/v1/web-services/{web_service_id}/logs?tail=100&since=1710000000

Parameter	Type	Default	Description
tail	int	100	Number of log lines (1–10000)
since	int	—	Unix timestamp to filter logs from

Get current metrics

GET /api/v1/web-services/{web_service_id}/metrics

Returns CPU (millicores and percent of limit), memory (bytes and percent of limit) and the running instance count. Responds 404 when the service is not running and has no metrics to report.

Get metrics history

GET /api/v1/web-services/{web_service_id}/metrics/history?period=3600

Parameter	Type	Default	Description
period	int	3600	Window in seconds, from 60 to 604800 (7 days)

Per-service request rate and latency are not collected and are not available through this API.

---

Deployments

List deployments

GET /api/v1/web-services/{web_service_id}/deployments?limit=10&offset=0

Parameter	Type	Default	Description
limit	int	10	Results per page (1–100)
offset	int	0	Pagination offset

Trigger a deployment

POST /api/v1/web-services/{web_service_id}/deployments
Content-Type: application/json

{
  "branch": "main"
}

The branch field is optional — defaults to the service’s configured branch.

Get deployment details

GET /api/v1/web-services/{web_service_id}/deployments/{deployment_id}

Roll back to a previous deployment

POST /api/v1/web-services/{web_service_id}/deployments/{deployment_id}/rollback

---

Environment Variables

List env vars

GET /api/v1/web-services/{web_service_id}/env

Values of secret variables are masked in the response.

Create an env var

POST /api/v1/web-services/{web_service_id}/env
Content-Type: application/json

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

Bulk replace env vars

PUT /api/v1/web-services/{web_service_id}/env/bulk
Content-Type: application/json

{
  "variables": [
    {"key": "NODE_ENV", "value": "production"},
    {"key": "PORT", "value": "3000", "is_secret": false}
  ]
}

Delete an env var

DELETE /api/v1/web-services/{web_service_id}/env/{var_id}

---

Project Secrets

Project secrets are scoped per environment (production, staging, development) and can be reused across services in the project.

List secrets

GET /api/v1/projects/{project_id}/secrets

Returns secrets grouped by key.

Create a secret

POST /api/v1/projects/{project_id}/secrets
Content-Type: application/json

{
  "key": "STRIPE_SECRET_KEY",
  "value": "sk_live_...",
  "scope": "production",
  "is_secret": true
}

Scope	Description
production	Used in production deployments
staging	Used in staging environments
development	Used in development environments

Bulk replace secrets

PUT /api/v1/projects/{project_id}/secrets/bulk
Content-Type: application/json

{
  "secrets": [
    {"key": "API_SECRET", "value": "value1", "scope": "production"},
    {"key": "API_SECRET", "value": "value2", "scope": "staging"}
  ]
}

Delete a secret

DELETE /api/v1/projects/{project_id}/secrets/{secret_id}

---

Managed Databases

Read-only. Connection URLs and credentials are never returned.

List databases

GET /api/v1/databases?limit=50&offset=0

Returns Postgres and Valkey instances of the active workspace in one list, each carrying kind, status, plan name, configured limits and hostnames.

Get a database

GET /api/v1/databases/{database_id}

Same fields plus current CPU and memory usage when the instance is running. Usage is collected for Postgres only; for Valkey those fields are null.

Both endpoints are scoped to the caller’s active workspace.

---

Error Responses

All errors follow a consistent format:

{
  "detail": "Error message describing what went wrong"
}

Status	Description
400	Bad request — invalid input
401	Unauthorized — invalid or missing credentials
403	Forbidden — insufficient scope
404	Resource not found
429	Rate limit exceeded

A 403 raised by the scope check carries a structured detail rather than a string, so a client can tell the caller which scope the key is missing:

{
  "detail": {
    "code": "insufficient_scope",
    "required": "write",
    "actual": "read"
  }
}

429 means the public API rate limit (30 requests per minute) was exceeded. The budget is per API key, so two keys never share one bucket.

---

Try it interactively

Browse and call the API live in the API Explorer.