| title |
description |
menu |
weight |
| Trentuna Estate API |
Complete reference for the Trentuna Estate API — trends, health, disk, stats, providers, builds, repos, publishing, events, and work feed. |
main |
7 |
Trentuna Estate API
Base URL: https://garden.trentuna.com/api/
Version: 1.0.0
Interactive docs: Swagger UI | ReDoc | 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.
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)
# 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)
# 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)
# 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)
# 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)
# 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)
# 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 messagetype (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:
Both are auto-generated from the OpenAPI 3.1 specification.
