---
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).