task t_cd38ed5d: publish Trentuna Estate API docs to garden — hugo page + static openapi.json + menu entry
This commit is contained in:
parent
5703e606d0
commit
a46cce7fea
GPG key ID:
6EB37F7E6190AF1C
3 changed files with 269 additions and 1 deletions
263
content/api-docs/_index.md
Normal file
263
content/api-docs/_index.md
Normal file
|
|
@ -0,0 +1,263 @@
|
||||||
|
---
|
||||||
|
title: "Trentuna Estate API"
|
||||||
|
description: "Complete reference for the Trentuna Estate API — trends, health, disk, stats, providers, builds, repos, publishing, events, and work feed."
|
||||||
|
menu: "main"
|
||||||
|
weight: 7
|
||||||
|
---
|
||||||
|
|
||||||
|
# Trentuna Estate API
|
||||||
|
|
||||||
|
> **Base URL:** `https://garden.trentuna.com/api/`
|
||||||
|
> **Version:** 1.0.0
|
||||||
|
> **Interactive docs:** [Swagger UI](/api/docs) | [ReDoc](/api/redoc) | [OpenAPI JSON](/api/openapi.json)
|
||||||
|
|
||||||
|
The Trentuna Estate API provides operational data for the Trentuna estate — trends, health, disk usage, stats, providers, builds, state, repositories, publishing, and events. It powers the garden dashboard at [garden.trentuna.com](https://garden.trentuna.com/).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Authentication
|
||||||
|
|
||||||
|
Routes marked with **🔒** require authentication. Routes marked with **🟢** are public.
|
||||||
|
|
||||||
|
Authentication methods:
|
||||||
|
|
||||||
|
| Method | Header / Parameter |
|
||||||
|
|--------|-------------------|
|
||||||
|
| API Key (header) | `X-API-Key: <your_key>` |
|
||||||
|
| Bearer Token | `Authorization: Bearer <your_token>` |
|
||||||
|
| API Key (query) | `?api_key=<your_key>` |
|
||||||
|
|
||||||
|
Public routes are suitable for monitoring, load balancers, and the garden dashboard.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Route Reference
|
||||||
|
|
||||||
|
### System Health (Public)
|
||||||
|
|
||||||
|
| Method | Route | Description |
|
||||||
|
|--------|-------|-------------|
|
||||||
|
| 🟢 GET | `/` | Root endpoint with API metadata |
|
||||||
|
| 🟢 GET | `/healthz` | Kubernetes-style health check (always 200 while running) |
|
||||||
|
| 🟢 GET | `/health` | Live system health — status, uptime, version, disk usage |
|
||||||
|
| 🟢 GET | `/status` | Simple HTML status page |
|
||||||
|
|
||||||
|
### Trends
|
||||||
|
|
||||||
|
| Method | Route | Description | Parameters |
|
||||||
|
|--------|-------|-------------|------------|
|
||||||
|
| 🔒 GET | `/trends` | Get the latest N trend data points from the trends JSONL file | `limit` (query, int, default: 100, max: 1000) |
|
||||||
|
| 🔒 GET | `/trends/latest` | Get the single most recent trend data point | — |
|
||||||
|
|
||||||
|
Trends are stored as JSONL (one JSON object per line) in the estate data directory.
|
||||||
|
|
||||||
|
### Disk
|
||||||
|
|
||||||
|
| Method | Route | Description |
|
||||||
|
|--------|-------|-------------|
|
||||||
|
| 🔒 GET | `/disk` | Get disk snapshot data from disk-snapshot.log |
|
||||||
|
| 🔒 GET | `/disk/latest` | Get the most recent disk snapshot |
|
||||||
|
|
||||||
|
### Health Pulse
|
||||||
|
|
||||||
|
| Method | Route | Description |
|
||||||
|
|--------|-------|-------------|
|
||||||
|
| 🔒 GET | `/health/pulse` | Get health pulse entries from health-pulse.log |
|
||||||
|
| 🔒 GET | `/health/pulse/status` | Get overall health status string |
|
||||||
|
|
||||||
|
### Estate
|
||||||
|
|
||||||
|
| Method | Route | Description |
|
||||||
|
|--------|-------|-------------|
|
||||||
|
| 🟢 GET | `/estate/agents` | Known agent nodes with live telemetry (from work feed + runtime environment) |
|
||||||
|
| 🟢 GET | `/estate/logs` | Recent activity log from the kanban work completion feed (supports `?limit=` query param, default: 20) |
|
||||||
|
| 🟢 GET | `/estate/status` | System status + uptime for the garden estate node card |
|
||||||
|
|
||||||
|
### Builds
|
||||||
|
|
||||||
|
| Method | Route | Description | Parameters |
|
||||||
|
|--------|-------|-------------|------------|
|
||||||
|
| 🔒 GET | `/builds` | Get build digest for the last N days | `days` (query, int, default: 7) |
|
||||||
|
| 🔒 GET | `/builds/recent` | Get recent build digest (last 7 days) | — |
|
||||||
|
|
||||||
|
### Events
|
||||||
|
|
||||||
|
| Method | Route | Description | Parameters |
|
||||||
|
|--------|-------|-------------|------------|
|
||||||
|
| 🔒 GET | `/events` | Get recent estate events from heartbeat and scoreboard files | `limit` (query, int, default: 50) |
|
||||||
|
|
||||||
|
### State
|
||||||
|
|
||||||
|
| Method | Route | Description | Parameters |
|
||||||
|
|--------|-------|-------------|------------|
|
||||||
|
| 🔒 GET | `/state` | Get all estate state files | — |
|
||||||
|
| 🔒 GET | `/state/{file_name}` | Get a specific state file by name (scoreboard, heartbeat, estate_map) | `max_chars` (query, int, default: 5000) |
|
||||||
|
|
||||||
|
### Stats
|
||||||
|
|
||||||
|
| Method | Route | Description |
|
||||||
|
|--------|-------|-------------|
|
||||||
|
| 🔒 GET | `/stats` | Get site statistics from update-site-stats.sh |
|
||||||
|
|
||||||
|
### Providers
|
||||||
|
|
||||||
|
| Method | Route | Description |
|
||||||
|
|--------|-------|-------------|
|
||||||
|
| 🔒 GET | `/providers` | Get LLM provider reachability status |
|
||||||
|
|
||||||
|
### Repos
|
||||||
|
|
||||||
|
| Method | Route | Description |
|
||||||
|
|--------|-------|-------------|
|
||||||
|
| 🔒 GET | `/repos` | Get repos from Forgejo and REPO_LEDGER.md |
|
||||||
|
|
||||||
|
### Forgejo Proxy
|
||||||
|
|
||||||
|
| Method | Route | Description | Parameters |
|
||||||
|
|--------|-------|-------------|------------|
|
||||||
|
| 🔒 GET | `/forgejo-proxy/repos` | List all Forgejo repos (enriched) | — |
|
||||||
|
| 🔒 GET | `/forgejo-proxy/issues/{owner}/{repo}` | Get issues for a specific Forgejo repo | `state` (query, default: "open"), `limit` (query, int, default: 20) |
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
|
||||||
|
| Method | Route | Description |
|
||||||
|
|--------|-------|-------------|
|
||||||
|
| 🔒 GET | `/summary` | Aggregate summary across all data sources |
|
||||||
|
|
||||||
|
### Garden
|
||||||
|
|
||||||
|
| Method | Route | Description |
|
||||||
|
|--------|-------|-------------|
|
||||||
|
| 🟢 GET | `/api/garden` | Main garden feed — writings, expressive forms, estate pulse, identity |
|
||||||
|
|
||||||
|
### Publishing
|
||||||
|
|
||||||
|
| Method | Route | Description | Parameters |
|
||||||
|
|--------|-------|-------------|------------|
|
||||||
|
| 🟢 GET | `/publishing/latest` | Public feed — latest published pieces, newest first | `limit` (query, int, default: 10) |
|
||||||
|
| 🟢 GET | `/publishing/{entry_id}` | Get a single published entry by ID | — |
|
||||||
|
| 🟢 GET | `/publishing/by-site/{site}` | Filter published entries by target site | — |
|
||||||
|
| 🟢 GET | `/publishing/by-type/{content_type}` | Filter published entries by content type | — |
|
||||||
|
| 🔒 POST | `/publishing/register` | Register a newly published piece of content | Required: title, slug, content_type, target_site |
|
||||||
|
|
||||||
|
### Work Feed
|
||||||
|
|
||||||
|
| Method | Route | Description | Parameters |
|
||||||
|
|--------|-------|-------------|------------|
|
||||||
|
| 🟢 GET | `/work/feed` | Public feed — recent kanban task completions, newest first | `limit` (query, int, default: 20), `board` (query, slug filter) |
|
||||||
|
| 🟢 GET | `/hq/work` | Public HTML page showing the live kanban completion feed | — |
|
||||||
|
| 🔒 POST | `/work/complete` | Record a kanban task completion | Required: task_id, board, assignee, title. Optional: commit_sha, output_url, summary |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Example Workflows
|
||||||
|
|
||||||
|
### 1. Monitor estate health (public, no auth needed)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check if API is alive
|
||||||
|
curl https://garden.trentuna.com/api/healthz
|
||||||
|
|
||||||
|
# Get full health report
|
||||||
|
curl https://garden.trentuna.com/api/health
|
||||||
|
|
||||||
|
# View HTML status page
|
||||||
|
curl https://garden.trentuna.com/api/status
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Explore trends (authenticated)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Get last 50 trend data points
|
||||||
|
curl -H "X-API-Key: your-key" \
|
||||||
|
https://garden.trentuna.com/api/trends?limit=50
|
||||||
|
|
||||||
|
# Get the latest data point
|
||||||
|
curl -H "X-API-Key: your-key" \
|
||||||
|
https://garden.trentuna.com/api/trends/latest
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Check recent agent activity (public)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# List active agents
|
||||||
|
curl https://garden.trentuna.com/api/estate/agents
|
||||||
|
|
||||||
|
# View recent activity log (20 entries)
|
||||||
|
curl https://garden.trentuna.com/api/estate/logs?limit=20
|
||||||
|
|
||||||
|
# Check estate status
|
||||||
|
curl https://garden.trentuna.com/api/estate/status
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. View builds and repos (authenticated)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Recent builds (last 14 days)
|
||||||
|
curl -H "X-API-Key: your-key" \
|
||||||
|
https://garden.trentuna.com/api/builds?days=14
|
||||||
|
|
||||||
|
# All repos
|
||||||
|
curl -H "X-API-Key: your-key" \
|
||||||
|
https://garden.trentuna.com/api/repos
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Publishing feed (public)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Latest 5 published pieces
|
||||||
|
curl https://garden.trentuna.com/api/publishing/latest?limit=5
|
||||||
|
|
||||||
|
# Get a specific entry
|
||||||
|
curl https://garden.trentuna.com/api/publishing/abc123
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Work completion feed (public)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Recent work completions
|
||||||
|
curl https://garden.trentuna.com/api/work/feed?limit=10
|
||||||
|
|
||||||
|
# Filter by board
|
||||||
|
curl "https://garden.trentuna.com/api/work/feed?board=a-team"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Schema Definitions
|
||||||
|
|
||||||
|
The API uses two schema types for request validation:
|
||||||
|
|
||||||
|
### HTTPValidationError
|
||||||
|
|
||||||
|
Returned when request validation fails (HTTP 422). Contains:
|
||||||
|
- `detail` (array): List of individual validation errors
|
||||||
|
|
||||||
|
### ValidationError
|
||||||
|
|
||||||
|
Each item in the validation error detail array:
|
||||||
|
- `loc` (array): Location of the error (e.g. `["body", "title"]`)
|
||||||
|
- `msg` (string): Human-readable error message
|
||||||
|
- `type` (string): Error type code
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error Codes
|
||||||
|
|
||||||
|
| HTTP Status | Description |
|
||||||
|
|-------------|-------------|
|
||||||
|
| 200 | Success |
|
||||||
|
| 404 | Not Found — the requested resource doesn't exist |
|
||||||
|
| 422 | Validation Error — request parameters are invalid |
|
||||||
|
| 403 | Forbidden — missing or invalid API key |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Interactive Documentation
|
||||||
|
|
||||||
|
The API provides two interactive documentation interfaces:
|
||||||
|
|
||||||
|
- **Swagger UI**: [garden.trentuna.com/api/docs](/api/docs) — Interactive API explorer with "Try it out" functionality
|
||||||
|
- **ReDoc**: [garden.trentuna.com/api/redoc](/api/redoc) — Clean, scrollable reference documentation
|
||||||
|
|
||||||
|
Both are auto-generated from the [OpenAPI 3.1 specification](/api/openapi.json).
|
||||||
|
|
@ -34,10 +34,14 @@ theme = 'asw-hugo'
|
||||||
name = "tags"
|
name = "tags"
|
||||||
url = "/tags/"
|
url = "/tags/"
|
||||||
weight = 6
|
weight = 6
|
||||||
|
[[menus.main]]
|
||||||
|
name = "api-docs"
|
||||||
|
url = "/api-docs/"
|
||||||
|
weight = 7
|
||||||
[[menus.main]]
|
[[menus.main]]
|
||||||
name = "trentuna"
|
name = "trentuna"
|
||||||
url = "https://trentuna.com/"
|
url = "https://trentuna.com/"
|
||||||
weight = 7
|
weight = 8
|
||||||
|
|
||||||
[markup.goldmark.renderer]
|
[markup.goldmark.renderer]
|
||||||
unsafe = true
|
unsafe = true
|
||||||
|
|
|
||||||
1
static/api/openapi.json
Normal file
1
static/api/openapi.json
Normal file
File diff suppressed because one or more lines are too long
Loading…
Add table
Add a link
Reference in a new issue