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.

Available to MCP agents as particle_topic_browse.

Browse the taxonomy

Top-level topics:

curl

curl "https://api.particle.pro/v1/topics?limit=10" \
  -H "X-API-Key: $PARTICLE_API_KEY"

Response (truncated)

{
  "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:

curl

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

Response (truncated)

{
  "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" }
    // …
  ]
}

Find a topic by name

Pass q to search topic names instead of walking the tree. Exact names come first, then names that start with q, then names that contain it, each ranked by story coverage:

curl "https://api.particle.pro/v1/topics?q=artificial%20intelligence&limit=5" \
  -H "X-API-Key: $PARTICLE_API_KEY"

The same name often appears under several parents (Artificial Intelligence sits under Technology, Business and more), so read each result’s ancestry before picking one. To search within one branch, add parent_id (or ancestry_path_prefix): the search then covers that topic’s descendants, not only its direct children.

• q needs at least 2 characters and cannot be combined with ancestry_path. A 2-character q (such as AI) matches exact names and names that start with it; matching names that merely contain q needs at least one word of 3 or more characters (ai ml matches exact names and prefixes only).
• Name search covers topics with at least 5 story clusters. The long tail of single-story topics is still reachable by browsing with parent_id.
• Search pages reach the top 200 matches. Narrow q or add parent_id to go further.

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

curl

curl "https://api.particle.pro/v1/topics/4FZ4EFh" \
  -H "X-API-Key: $PARTICLE_API_KEY"

Response

{
  "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:

curl

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

See Episodes → Topics for the integrated discovery flow.

Related

• Entities — the people, organizations, and places counterpart to topics
• Episodes — filter by topic, then drill into transcripts and clips