REST API

Basepod server REST API reference.

Base URL

https://your-server.com/api

Authentication

Most endpoints require authentication via Bearer token.

curl -H "Authorization: Bearer <token>" https://your-server.com/api/apps

Get a token by logging in:

curl -X POST https://your-server.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password": "your-password"}'

Health

GET /api/health

Check server health.

curl https://your-server.com/api/health

Response:

{
  "status": "ok",
  "podman": "connected"
}

Apps

GET /api/apps

List all apps.

curl -H "Authorization: Bearer <token>" https://your-server.com/api/apps

Response:

{
  "apps": [
    {
      "id": "abc123",
      "name": "myapp",
      "status": "running",
      "domain": "myapp.example.com",
      "image": "nginx:latest",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "total": 1
}

POST /api/apps

Create a new app.

curl -X POST https://your-server.com/api/apps \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myapp",
    "image": "nginx:latest",
    "port": 80
  }'

Request body:

Field	Type	Required	Description
name	string	yes	App name
image	string	no	Docker image
port	int	no	Container port
domain	string	no	Custom domain
env	object	no	Environment variables

GET /api/apps/:name

Get app details.

curl -H "Authorization: Bearer <token>" https://your-server.com/api/apps/myapp

DELETE /api/apps/:name

Delete an app.

curl -X DELETE -H "Authorization: Bearer <token>" https://your-server.com/api/apps/myapp

POST /api/apps/:name/deploy

Deploy an app with image or git.

curl -X POST https://your-server.com/api/apps/myapp/deploy \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"image": "nginx:latest"}'

POST /api/apps/:name/start

Start a stopped app.

curl -X POST -H "Authorization: Bearer <token>" https://your-server.com/api/apps/myapp/start

POST /api/apps/:name/stop

Stop a running app.

curl -X POST -H "Authorization: Bearer <token>" https://your-server.com/api/apps/myapp/stop

POST /api/apps/:name/restart

Restart an app.

curl -X POST -H "Authorization: Bearer <token>" https://your-server.com/api/apps/myapp/restart

GET /api/apps/:name/logs

Get app logs.

curl -H "Authorization: Bearer <token>" "https://your-server.com/api/apps/myapp/logs?tail=100"

Query params:

Param	Default	Description
tail	100	Number of lines

Source Deploy

POST /api/deploy

Deploy from source tarball.

curl -X POST https://your-server.com/api/deploy \
  -H "Authorization: Bearer <token>" \
  -F "config={\"name\":\"myapp\",\"port\":3000}" \
  -F "source=@source.tar.gz"

Templates

GET /api/templates

List available templates.

curl https://your-server.com/api/templates

POST /api/apps/from-template

Deploy from template.

curl -X POST https://your-server.com/api/apps/from-template \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "postgres",
    "name": "mydb"
  }'

System

GET /api/system/info

Get server information.

curl -H "Authorization: Bearer <token>" https://your-server.com/api/system/info

GET /api/system/config

Get server configuration.

curl -H "Authorization: Bearer <token>" https://your-server.com/api/system/config

MLX (LLM)

GET /api/mlx/models

List MLX models.

curl -H "Authorization: Bearer <token>" https://your-server.com/api/mlx/models

POST /api/mlx/models/:id/download

Download a model.

curl -X POST -H "Authorization: Bearer <token>" https://your-server.com/api/mlx/models/llama-3.2-3b/download

POST /api/mlx/start

Start a model.

curl -X POST https://your-server.com/api/mlx/start \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"model": "mlx-community/Llama-3.2-3B-Instruct-4bit"}'

POST /api/mlx/stop

Stop the running model.

curl -X POST -H "Authorization: Bearer <token>" https://your-server.com/api/mlx/stop

Error Responses

All errors return:

{
  "error": "Error message"
}

HTTP status codes:

Code	Description
400	Bad request
401	Unauthorized
404	Not found
500	Server error