# PodHood developer & agent guide

> How to read, search, and cite any podcast library hosted on PodHood — over REST, MCP, or plain Markdown. All read access to published content is public and needs no authentication.

## When to use PodHood

Reach for a PodHood library when you need to:

- **Answer a question from a podcast's actual content** — search a show's episodes and transcripts and get back ranked, timestamped quotes with citation URLs.
- **Find the exact moment something was said** — results deep-link to the second, on the episode's own page.
- **Read an episode as text** — every episode page has a Markdown companion: append `.md` to its URL.
- **Browse a show's catalog programmatically** — list episodes with facet filters (topic, person, company, product, year).

Each podcast has its own library at `https://<channel>.podhood.com` (or the show's custom domain). The apex `llms.txt` lists public channels; each channel host serves its own `llms.txt` with an episode index.

## MCP (Model Context Protocol)

Every channel exposes an anonymous, read-only MCP server over Streamable HTTP:

```
https://<channel>.podhood.com/mcp
```

It provides one tool, `search`: Natural-language search over the channel's published episodes and transcripts. Returns ranked episodes and grounded, timestamped quotes, each with a citation URL to the exact moment. Optional parameters: `topK`, `maxSegmentsPerEpisode`, `includeText`, `fast`, `episodeIds`.

Connect it to Claude, ChatGPT, Cursor, or any other MCP client — the library's Ask dialog includes install recipes for 30+ clients.

## REST API

No API key is required for published content. Responses are JSON; errors are JSON with an `error` message. The full schema is in the [OpenAPI spec](https://podhood.com/openapi.json).

/api/v1 is the documented, stable surface (the unversioned /api/* paths remain as aliases). A breaking change ships as /api/v2, with Deprecation and Sunset headers served on the retiring version before removal. Every documented endpoint is a read-only GET over already-published public data — idempotent, safe to retry, and with nothing to sandbox because no documented call can mutate state. Errors are always JSON, never HTML.

### Search a channel

```
GET https://podhood.com/api/v1/channels/{slug}/search?query=...
```

Hybrid (semantic + keyword) search over published episodes. Optional params: `fast=true` (keyword-only, cheaper), facet filters (`topicIds`, `personIds`, `entityIds`, `episodeIds` — comma-separated ids — plus `collectionId`, `year`).

```sh
curl "https://podhood.com/api/v1/channels/{slug}/search?query=pricing%20strategy"
```

### Browse a channel's episodes

```
GET https://podhood.com/api/v1/channels/{slug}/episodes
```

Keyset-paginated list of published episodes; pass back `nextCursor` as `cursor` for the next page. Accepts the same facet filters plus `sort`.

### Episode resources

```
GET https://podhood.com/api/v1/episodes/{episodeId}/transcript
GET https://podhood.com/api/v1/episodes/{episodeId}/chapters
GET https://podhood.com/api/v1/episodes/{episodeId}/related
```

Published episodes are anonymously readable; unpublished ones 404.

## Machine-readable surfaces

- [llms.txt](https://podhood.com/llms.txt) — platform index; every channel host serves its own
- [OpenAPI spec](https://podhood.com/openapi.json)
- [Pricing (Markdown)](https://podhood.com/pricing.md)
- `sitemap.xml` and `robots.txt` on every host; AI crawlers are welcome
- Append `.md` to any episode or marketing page URL for a Markdown twin
- Episode pages carry Schema.org JSON-LD: `PodcastEpisode`, chapters and key moments as deep-linkable `Clip` nodes, speakers, and entities