josh/Catalyst
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 16 Wiki Activity

docs: move API reference to docs/api.md and add Jobs endpoints

Browse Source 
Extracts the REST API section from README.md into a dedicated
docs/api.md. Adds documentation for the four Jobs endpoints
(GET/PUT /api/jobs, GET /api/jobs/:id, POST /api/jobs/:id/run)
which existed in code but were not yet documented.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
josh
2026-07-04 20:15:07 -04:00
committed by josh
co-authored by Claude Sonnet 4.6
parent 5b3edbdfe5
commit 7f6ce42d9a
2 changed files with 284 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+1 -170
View File
@@ -37,176 +37,7 @@ Open [http://localhost:3000](http://localhost:3000).
## REST API
All endpoints are under `/api`. Request and response bodies are JSON.
### Instances
#### `GET /api/instances`
Returns all instances sorted by name. All query parameters are optional.
| Parameter | Type | Description |
|---|---|---|
| `search` | string | Partial match on `name`, `vmid`, or `stack` |
| `state` | string | Exact match: `deployed`, `testing`, `degraded` |
| `stack` | string | Exact match: `production`, `development` |
```
GET /api/instances?search=plex&state=deployed
```
```json
[
{
"vmid": 117,
"name": "plex",
"state": "deployed",
"stack": "production",
"tailscale_ip": "100.64.0.1",
"atlas": 1, "argus": 1, "semaphore": 0,
"patchmon": 1, "tailscale": 1, "andromeda": 0,
"hardware_acceleration": 1,
"created_at": "2024-01-15T10:30:00",
"updated_at": "2024-03-10T14:22:00"
}
]
```
---
#### `GET /api/instances/stacks`
Returns a sorted array of distinct stack names present in the registry.
```
GET /api/instances/stacks
→ ["development", "production"]
```
---
#### `GET /api/instances/:vmid`
Returns a single instance by VMID.
| Status | Condition |
|---|---|
| `200` | Instance found |
| `400` | VMID is not a valid integer |
| `404` | No instance with that VMID |
---
#### `GET /api/instances/:vmid/history`
Returns the audit log for an instance — newest events first.
| Status | Condition |
|---|---|
| `200` | History returned (may be empty array) |
| `400` | VMID is not a valid integer |
| `404` | No instance with that VMID |
```json
[
{
"id": 3,
"vmid": 117,
"field": "state",
"old_value": "testing",
"new_value": "deployed",
"changed_at": "2024-03-10T14:22:00"
},
{
"id": 1,
"vmid": 117,
"field": "created",
"old_value": null,
"new_value": null,
"changed_at": "2024-01-15T10:30:00"
}
]
```
---
#### `POST /api/instances`
Creates a new instance. Returns the created record.
| Status | Condition |
|---|---|
| `201` | Created successfully |
| `400` | Validation error — see `errors` array in response |
| `409` | VMID already exists |
**Request body:**
| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | |
| `vmid` | integer | yes | Must be > 0 and unique |
| `state` | string | yes | `deployed`, `testing`, or `degraded` |
| `stack` | string | yes | `production` or `development` |
| `tailscale_ip` | string | no | Valid IPv4 or empty string |
| `atlas` | 0\|1 | no | |
| `argus` | 0\|1 | no | |
| `semaphore` | 0\|1 | no | |
| `patchmon` | 0\|1 | no | |
| `tailscale` | 0\|1 | no | |
| `andromeda` | 0\|1 | no | |
| `hardware_acceleration` | 0\|1 | no | |
---
#### `PUT /api/instances/:vmid`
Replaces all fields on an existing instance. Accepts the same body shape as `POST`. The `vmid` in the body may differ from the URL — this is how you change a VMID.
| Status | Condition |
|---|---|
| `200` | Updated successfully |
| `400` | Validation error |
| `404` | No instance with that VMID |
| `409` | New VMID conflicts with an existing instance |
---
#### `DELETE /api/instances/:vmid`
Deletes an instance. Only instances on the `development` stack may be deleted.
| Status | Condition |
|---|---|
| `204` | Deleted successfully |
| `400` | VMID is not a valid integer |
| `404` | No instance with that VMID |
| `422` | Instance is on the `production` stack |
---
### Backup
#### `GET /api/export`
Downloads a JSON backup of all instances as a file attachment.
```json
{
"version": 1,
"exported_at": "2024-03-10T14:22:00.000Z",
"instances": [ ... ]
}
```
#### `POST /api/import`
Replaces all instances from a JSON backup. Validates every row before committing — if any row is invalid the entire import is rejected.
| Status | Condition |
|---|---|
| `200` | Import successful — returns `{ "imported": N }` |
| `400` | Body missing `instances` array, or validation errors |
See **[docs/api.md](docs/api.md)** for the full API reference.
---