# 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](/content/docs/data/index.html) 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.