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.

Projects

List projects

GET /api/projects

Returns all projects owned by the authenticated user.

Create a project

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

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

Get project details

GET /api/projects/{project_id}

Web Services

List web services

GET /api/web-services

Create a web service

POST /api/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/web-services/{web_service_id}

Deploy / Restart / Stop

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

/deploy triggers a fresh deployment of the current configured branch. /restart re-rolls existing instances without rebuilding. /stop releases compute (env vars and disks are preserved).

Get container logs

GET /api/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

Deployments

List deployments

GET /api/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/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/web-services/{web_service_id}/deployments/{deployment_id}

Roll back to a previous deployment

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

Environment Variables

List env vars

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

Values of secret variables are masked in the response.

Create an env var

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

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

Bulk replace env vars

PUT /api/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/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/projects/{project_id}/secrets

Returns secrets grouped by key.

Create a secret

POST /api/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/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/projects/{project_id}/secrets/{secret_id}

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

Try it interactively

Browse and call the API live in the API Explorer.