API Reference

All API endpoints for the OpenBerth server.

All API endpoints require authentication via Authorization: Bearer <api_key> header. The server listens on 127.0.0.1:3456 behind Caddy.

Deployments

POST /api/deploy

Upload a tarball to deploy. Multipart form with tarball field.

POST /api/deploy/code

Deploy inline files as JSON. Body: {"files": {"index.html": "..."}, "name": "my-app"}

POST /api/deploy/{id}/update

Update a deployment with a new tarball.

POST /api/deploy/{id}/update/code

Update a deployment with inline files.

GET /api/deployments

List all deployments for the authenticated user.

DELETE /api/deployments

Destroy all deployments for the authenticated user.

GET /api/deployments/{id}

Get deployment status, URL, framework, and details.

PATCH /api/deployments/{id}

Update deployment metadata (e.g., network quota).

DELETE /api/deployments/{id}

Destroy a deployment permanently.

GET /api/deployments/{id}/logs

Get container logs. Optional ?tail=N query parameter.

GET /api/deployments/{id}/source

Download deployment source code. Optional ?format=json for JSON response with file contents.

POST /api/deployments/{id}/protect

Set access control. Body: {"mode": "basic_auth", "username": "...", "password": "..."} or {"mode": "user", "users": ["alice", "bob"]}

POST /api/deployments/{id}/lock

Lock or unlock a deployment. Body: {"locked": true}. A locked deployment keeps running but rejects updates, destroy, protect, and metadata changes.

Sandbox

POST /api/sandbox

Create a dev sandbox. Body: {"files": {...}, "name": "...", "env": {...}}

POST /api/sandbox/{id}/push

Push file changes. Body: {"changes": [{"op": "write", "path": "app.js", "content": "..."}]}

POST /api/sandbox/{id}/install

Install packages. Body: {"packages": ["express", "cors"]}

POST /api/sandbox/{id}/exec

Execute a command. Body: {"command": "ls -la", "timeout": 30}

GET /api/sandbox/{id}/logs

Get sandbox logs. Optional ?tail=N.

DELETE /api/sandbox/{id}

Destroy a sandbox.

POST /api/sandbox/{id}/promote

Promote to production deployment.

Data API

Per-deployment document store. See Persistent Data for details.

GET /_data

POST /_data/{collection}

GET /_data/{collection}

GET /_data/{collection}/{id}

PUT /_data/{collection}/{id}

DELETE /_data/{collection}/{id}

DELETE /_data/{collection}

Gallery

GET /api/gallery

Public gallery listing of deployments.

Admin

GET /api/admin/users

List all users (admin only).

POST /api/admin/users

Create a user.

DELETE /api/admin/users/{name}

Delete a user.

PATCH /api/admin/users/{name}

Update user settings.

GET /api/admin/settings

Get server settings.

POST /api/admin/settings

Update server settings.

OAuth 2.1

GET /.well-known/oauth-protected-resource

GET /.well-known/oauth-authorization-server

POST /oauth/register

GET /oauth/authorize

POST /oauth/token

MCP

POST /mcp

MCP Streamable HTTP endpoint (JSON-RPC 2.0). Used by Claude.ai web and mobile interfaces.