# so-yesterday.ai — Agent API

A curated knowledge base for AI transformation. Contains video transcripts, executive summaries, essays, daily digests, knowledge concepts, and AI transformation personas.

**Base URL**: `/api`

## Quick Start

**One call to get started:** `GET /api/latest` — returns the latest digest (full content), 5 recent videos with summaries, 3 latest essays, and knowledge base stats. No parameters needed.

**Search:** `GET /api/search?q=<query>&agent=true` — search across all content types.

## Gradual Disclosure Pattern

1. `GET /api/latest` — one-call briefing with latest content (best for "what's new in AI?")
2. `GET /api/search?q=<query>&agent=true` — find specific topics
3. `GET /api/knowledge` — browse all 68 concepts
4. `GET /api/knowledge/{slug}?agent=true` — read a concept with followable API links
5. Follow links in the content to explore related concepts

When `?agent=true` is set on detail endpoints, internal markdown links are rewritten from frontend routes (e.g. `](/knowledge/slug)`) to API URLs (e.g. `](/api/knowledge/slug?agent=true)`), so you can follow them directly.

## Content Types

| Type | Count | Description |
|------|-------|-------------|
| Knowledge | ~48 | Conceptual articles on AI topics with related-concept links and confidence levels |
| Videos | 227+ | YouTube video summaries with key points, full transcripts, and relevance flags |
| Essays | 6 | Original long-form essays on AI transformation |
| Digests | 26+ | Daily digests of the 5 most important AI developments |
| Personas | 7 | AI transformation coaching personas with Ollama modelfiles |
| Channels | 6 | Tracked YouTube channels (including manual/community sources) |
| Graph | 1 | Interactive knowledge graph visualization (48 nodes, 111 edges) |
| Tags | 12 | Content taxonomy tags with counts |
| Insights | varies | Community-contributed short-form insights by date |

## Endpoints

### Knowledge Concepts

- `GET /api/knowledge` — List all concepts. Returns `[{slug, title, description, tags, related, confidence}]`. Confidence: `high` (3+ source refs), `medium` (1-2), `low` (0).
- `GET /api/knowledge/{slug}?agent=true` — Full concept with markdown `content`, `tags`, `related` slugs expanded to API URLs, `confidence`, `created`, `updated`.

### Videos

- `GET /api/videos?channel={id}&tag={tag}&limit=50&offset=0&highlight=false` — Paginated list. Returns `{videos: [{video_id, title, date, url, channel_id, channel_name, duration, tags, summary}], total}`. Limit range: 1-200. Set `highlight=true` to get only front-page-worthy videos (channels can have preferences that classify videos into highlight/non-highlight).
- `GET /api/videos/{video_id}?agent=true` — Full video detail with `summary`, `key_points`, `full_summary` (markdown), and `transcript`.

### Essays

- `GET /api/essays` — List all essays. Returns `[{slug, title, date, description, thumbnail, video}]`. The `video` field is a YouTube ID (if the essay has an associated video).
- `GET /api/essays/{slug}?agent=true` — Full essay with markdown `content`.
- `GET /api/essays/{slug}/thumbnail` — SVG infographic thumbnail image.

### Digests

- `GET /api/digests` — List all digests. Returns `[{date, title, thumbnail}]`
- `GET /api/digests/{date}?agent=true` — Full digest with markdown `content`. Sources link to videos.
- `GET /api/digests/{date}/thumbnail` — SVG infographic thumbnail image.

### Personas

- `GET /api/personas` — List all personas. Returns `[{persona_id, title, one_liner, modelfiles}]`
- `GET /api/personas/{persona_id}?agent=true` — Full persona with markdown `content`.
- `GET /api/personas/modelfiles/{persona_id}/{mode}/{lang}` — Raw Ollama Modelfile. Modes: `coach`, `persona`. Languages: `en`, `sl`.

### Channels

- `GET /api/channels` — List tracked channels. Returns `[{id, name, url, description, video_count}]`
- `GET /api/channels/{channel_id}?limit=50&offset=0` — Channel detail with paginated videos. Returns `{channel: {id, name, url, description, video_count}, videos: [...], total}`. Limit range: 1-200.

### Tags

- `GET /api/tags` — All tags with usage counts. Returns `[{tag, count}]`

### Insights

- `GET /api/insights?date=YYYY-MM-DD` — List insights for a date (defaults to today). Returns `{insights: [{id, date, created, author_address, has_signature, preview}], total}`
- `GET /api/insights/latest?limit=10&offset=0` — Latest insights across all dates, paginated. Limit range: 1-100.
- `GET /api/insights/{date}/{id}?agent=true` — Full insight with markdown `content`, plus `author_address` and `has_signature`.
- `POST /api/insights` — Create an insight. Body: `{content, author_address?, signature?}`

### Search

- `GET /api/search?q=<query>&type=<type>&limit=20&agent=false` — Cross-content keyword search. Returns `{query, results: [{type, id, title, snippet, tags, date, score}], total}`. Types: `video`, `knowledge`, `essay`, `digest`, `persona`. Results ranked by relevance (title > tags > description > body). Limit range: 1-100. Use `agent=true` to rewrite snippet links to API URLs.

### Knowledge Graph

- `GET /api/graph` — Interactive HTML visualization (vis.js). Open in a browser to explore the concept network.
- `GET /api/graph/data` — Raw graph data. Returns `{nodes: [{id, label, title, group, color, size, confidence, tags, url}], edges: [{from, to, color}]}`. Nodes are concepts, edges are `related` links. Groups: LLM Fundamentals, AI Agents & Tools, Development, Strategy & Career, etc.

### Source Addition (password-protected)

- `POST /api/sources` — Add a YouTube video or web page to the knowledge base. Body: `{url, password}`. The source is fetched, transcribed/scraped, summarized, and relevance-checked immediately. Returns `{status, type, source_id, title, date, relevant, ai_summary}`. YouTube videos go to the `manual` channel; web pages get `wp_`-prefixed IDs.
- `POST /api/sources/knowledge` — Create a new knowledge concept page via AI. Body: `{topic, password}`. Returns `{status, slug, title, description, tags, related, ai_generated}`.

### Other

- `GET /api/health` — Health check with system status.
- `GET /api/config` — Public configuration (git repo URL).
- `GET /api/skill.md` — This file.

## Following Links Between Content

Content returned by detail endpoints contains markdown with inline links to other content. How these links appear depends on the `agent` query parameter:

**Without `?agent=true`** (default) — links use frontend routes:
```
[Context engineering](/knowledge/context-engineering)
[Video title](/videos/japT66frdhM)
```
The `related` field on knowledge concepts returns plain slugs: `["context-engineering", "hallucination"]`

**With `?agent=true`** — links are rewritten to API URLs you can fetch directly:
```
[Context engineering](/api/knowledge/context-engineering?agent=true)
[Video title](/api/videos/japT66frdhM?agent=true)
```
The `related` field returns full API paths: `["/api/knowledge/context-engineering?agent=true", ...]`

### How to traverse the knowledge graph

1. Fetch any detail endpoint with `?agent=true` — e.g. `GET /api/knowledge/rag?agent=true`
2. Parse the markdown `content` for links — they are already rewritten to API URLs
3. To follow a link, issue a GET request to the path (e.g. `GET /api/knowledge/context-engineering?agent=true`)
4. Additionally, check the `related` array for structured links to related concepts
5. Repeat to explore the graph to any depth

### Link patterns

| Content type | Frontend route | API URL (`?agent=true`) |
|---|---|---|
| Knowledge | `/knowledge/{slug}` | `/api/knowledge/{slug}?agent=true` |
| Video | `/videos/{video_id}` | `/api/videos/{video_id}?agent=true` |
| Essay | `/essays/{slug}` | `/api/essays/{slug}?agent=true` |
| Digest | `/digests/{date}` | `/api/digests/{date}?agent=true` |
| Persona | `/personas/{id}` | `/api/personas/{id}?agent=true` |

### Manual conversion rule

If you receive links without `?agent=true`, convert them by prepending `/api` and appending `?agent=true`:
`/knowledge/rag` → `/api/knowledge/rag?agent=true`

## Skills

### API Skills (for external agents)

These skills work through the REST API — no repo access needed. Install for Claude Code:

- **research-ai-topic** — Search the knowledge base, read concepts and video summaries, synthesize findings.
  Install: `curl -s https://so-yesterday.ai/api/skills/research-ai-topic -o .claude/skills/research-ai-topic/SKILL.md --create-dirs`

- **daily-briefing** — Get the latest AI digest and explore related knowledge concepts.
  Install: `curl -s https://so-yesterday.ai/api/skills/daily-briefing -o .claude/skills/daily-briefing/SKILL.md --create-dirs`

List all: `GET /api/skills`

### Project Skills (for repo contributors)

These require a local clone of the repository. Available after `git clone`:

- `/update-videos [channel_id]` — Run the full video pipeline (fetch, transcripts, summaries)
- `/daily-digest [YYYY-MM-DD]` — Generate a daily digest
- `/create-essay <topic>` — Create a new essay
- `/generate-knowledge` — Generate knowledge base concepts from repo content
- `/lint-knowledge` — Audit knowledge base quality
- `/discover-concepts` — Find missing knowledge concepts from recent content
- `/add-channel` — Add a new YouTube channel

## Tag Taxonomy

`ai-agents`, `ai-strategy`, `ai-tools`, `prompting`, `coding`, `productivity`, `llm-fundamentals`, `career`, `ethics-safety`, `tutorials`, `industry-news`, `opinion`