HTTP API
Last updated
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
- 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 | starting after up; empty after removePod() |
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 |