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).
|
||||
Loading…
Add table
Add a link
Reference in a new issue