> ## Documentation Index
> Fetch the complete documentation index at: https://docs.particle.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Topics

> Hierarchical topic taxonomy used to classify episodes.

Topics form a tree. Broad categories like `Politics` and `Business` contain subtopics like `politics/elections` and `business/technology`. Episodes are classified into topics automatically — fetch the taxonomy to power category navigation, route episodes to topic-specific feeds, or filter content by interest.

<Note>Available to MCP agents as [`particle_topic_browse`](/mcp/tools/topics/topic-browse).</Note>

## Browse the taxonomy

Top-level topics:

<CodeGroup>
  ```bash curl theme={"dark"}
  curl "https://api.particle.pro/v1/topics?limit=10" \
    -H "X-API-Key: $PARTICLE_API_KEY"
  ```

  ```js JavaScript theme={"dark"}
  const res = await fetch("https://api.particle.pro/v1/topics?limit=10", {
    headers: { "X-API-Key": process.env.PARTICLE_API_KEY },
  });
  const { data } = await res.json();
  ```
</CodeGroup>

```jsonc Response (truncated) theme={"dark"}
{
  "data": [
    { "id": "FMABRApV", "name": "Society",     "slug": "society",     "ancestry_path": "E-sJ7" },
    { "id": "4FZ5KFM",  "name": "Government",  "slug": "government",  "ancestry_path": "Qcqm_" },
    { "id": "4FaC4H9",  "name": "Business",    "slug": "business",    "ancestry_path": "gWDfW" },
    { "id": "4FZ4EFh",  "name": "Politics",    "slug": "politics",    "ancestry_path": "GtizK" },
    { "id": "4K6dD5X",  "name": "Media",       "slug": "media",       "ancestry_path": "cbYxV" }
    // …
  ]
}
```

The `ancestry_path` is an opaque hash-based path used for programmatic ancestor filtering. Slugs follow a `parent/child` convention for subtopics (e.g. `politics/elections`).

## Navigate the tree

Get direct children of a topic by passing `parent_id`:

```bash theme={"dark"}
# Subtopics under Politics
curl "https://api.particle.pro/v1/topics?parent_id=4FZ4EFh" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```jsonc Response (truncated) theme={"dark"}
{
  "data": [
    { "id": "4FZ4EFi",  "name": "International Relations", "slug": "politics/international-relations", "ancestry": "Politics" },
    { "id": "4FZ53X4",  "name": "Elections",               "slug": "politics/elections",               "ancestry": "Politics" },
    { "id": "FMEs52mJ", "name": "Political Parties",       "slug": "politics/political-parties",       "ancestry": "Politics" },
    { "id": "GIO2VHkb", "name": "Political Figures",       "slug": "politics/political-figures",       "ancestry": "Politics" }
    // …
  ]
}
```

## Get a single topic

The topic detail endpoint accepts any of three identifier forms in the path:

* The encoded `id` returned by the list endpoint (e.g. `4FZ4EFh`)
* The full `slug`, including multi-level slugs with `/` (e.g. `politics/elections`)
* The `ancestry_path` hash (e.g. `GtizK`, `Qcqm_`)

```bash theme={"dark"}
curl "https://api.particle.pro/v1/topics/4FZ4EFh" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

```jsonc Response theme={"dark"}
{
  "id": "4FZ4EFh",
  "name": "Politics",
  "slug": "politics",
  "ancestry_path": "GtizK",
  "total_children": 27601,
  "children": [
    { "id": "4FZ4EFi",  "name": "International Relations", "slug": "politics/international-relations", "ancestry": "Politics", "ancestry_path": "GtizKFabWL" },
    { "id": "4FZ53X4",  "name": "Elections",               "slug": "politics/elections",               "ancestry": "Politics", "ancestry_path": "GtizKFGV8r" }
    // … up to 100 entries, ordered by prominence
  ]
}
```

Response fields:

* `ancestors` — array of topic names from root to parent. Absent for root topics.
* `ancestry` — single human-readable breadcrumb string. Absent for root topics.
* `total_children` — total number of direct child topics. Always present (0 for leaves).
* `children` — the top direct children ordered by prominence (`url_cluster_count` descending, ties broken by name). Capped at 100; when `total_children` exceeds 100, paginate the full set via `/v1/topics?parent_id={id}`.

## Topics for an episode

Podcast episodes are classified into topics automatically. Fetch the topics for any episode:

```bash theme={"dark"}
curl "https://api.particle.pro/v1/podcasts/episodes/{episode_id}/topics" \
  -H "X-API-Key: $PARTICLE_API_KEY"
```

See [Episodes → Topics](/podcasts/episodes#topics) for the integrated discovery flow.

## Related

* [Entities](/knowledge-graph/entities) — the people, organizations, and places counterpart to topics
* [Episodes](/podcasts/episodes) — filter by topic, then drill into transcripts and clips