# HTTP API

This page lists the API server endpoints, request formats, and table schema.

## Endpoints

The API server listens on `:8080` and responds with the string `ok` or `{"data": [...]}` on success; JSON binding errors return `400` and database errors return `500`, both with the error message as a string.

| Method | Path | Body | Description |
|---|---|---|---|
| `GET` | `/api/health` | — | Health check; returns `ok` |
| `GET` | `/api/pod/list` | — | List deployments with `dismiss = 0` |
| `POST` | `/api/pod/upsert` | `Pod` | Insert or update a deployment by `uid` and reset `dismiss = 0` |
| `POST` | `/api/pod/update/:uid` | `Pod` (uses only `status`, `dismiss`) | Update the given deployment |
| `POST` | `/api/pod/record/insert` | `Record` (uses `uid`, `content`, `hostname`, `ip`) | Insert an operation record by `uid` |

Unregistered paths fall through to `NoRoute`, which holds the request open without ever responding.

## Example

```bash
curl -X POST localhost:8080/api/pod/upsert \
  -d '{"uid":"t1","pod_id":"p","pod_name":"n","local_dir":"/a","remote_dir":"/b","status":"starting","replicas":1}'

curl localhost:8080/api/pod/list
```

## Pod Fields

| Field | Type | Description |
|---|---|---|
| `uid` | `string` | `md5("<MAC>@<local-absolute-path>")` or the `-u` value |
| `pod_id` | `string` | Podman Pod ID; the remote folder name when the lookup fails |
| `pod_name` | `string` | Podman Pod name; the remote folder name when the lookup fails |
| `local_dir` | `string` | Local project absolute path |
| `remote_dir` | `string` | `/home/podrun/<folder-name>_<first-8-hash-chars>` |
| `file` | `string` | Compose file passed via `-f` |
| `target` | `string` | Value of `--type`; **[Unfinished]** k3s is recorded only |
| `status` | `string` | The CLI writes `starting` |
| `hostname` | `string` | Hostname of the machine running the CLI |
| `ip` | `string` | First non-loopback IPv4 of the machine running the CLI |
| `replicas` | `int` | Always `1` |
| `created_at` / `updated_at` | `time` | Written by the database |
| `dismiss` | `int` | `0` active, `1` removed |

`pod_id` is stored in the table's `pod_uid` column.

## Tables

| Table | Purpose | Columns |
|---|---|---|
| `pods` | One row per deployment; `uid` and `pod_uid` are unique | `uid`, `pod_uid`, `pod_name`, `local_dir`, `remote_dir`, `file`, `target`, `status`, `hostname`, `ip`, `replicas`, `created_at`, `updated_at`, `dismiss` |
| `records` | Operation log; `pod_id` references `pods.id` (cascade on delete) | `pod_id`, `content`, `hostname`, `ip` |
| `domains` | **[Unfinished]** Reserved for the `domain` command | `pod_id`, `container_name`, `domain`, `created_at`, `updated_at`, `dismiss` |