Concepts

This page is the cheat sheet every other guide refers back to. Skim it once, then look up specifics as needed.

IDs and slugs

Most endpoints with an {id} path parameter accept either:

The canonical opaque ID (e.g. 17PzxG1t12xzno for Sam Altman, 3CensCwu5G2oKCFgPrNf89 for Nvidia), or
A human-readable slug (e.g. sam-altman, nvidia, pivot, the-joe-rogan-experience).

Use whichever you have. If you receive an entity slug from one response (entity_slug: "nvidia"), you can pass it directly to any other endpoint without first looking up the canonical ID.

# Both of these resolve to the same entity:
curl ".../v1/entities/sam-altman"        -H "X-API-Key: $PARTICLE_API_KEY"
curl ".../v1/entities/17PzxG1t12xzno"    -H "X-API-Key: $PARTICLE_API_KEY"

Companies are richer: /v1/companies/{id} resolves slug, domain, and canonical ID directly. To look up by ticker, CIK, or QID, use the corresponding query filter on GET /v1/companies (?ticker=…, ?cik=…, ?qid=…) and pass the returned slug, domain, or ID through the singular endpoint. See Companies → Identifiers. Podcasts accept one extra form: every podcast {id} slot (and the podcast_id filter on list endpoints) also resolves a numeric Apple/iTunes collection ID directly (e.g. 1535809341) — so a client that already holds an iTunes ID can call any podcast endpoint without a prior lookup. To resolve a Spotify show ID, YouTube channel ID, RSS feed URL, or other platform identifier, use GET /v1/podcasts/lookup.

Cursor pagination

List endpoints share a single response envelope:

{
  "data": [ /* … */ ],
  "has_more": true,
  "cursor": "r.4gfFC7"
}

To fetch the next page, pass the cursor value back as a query parameter:

curl ".../v1/podcasts?cursor=r.4gfFC7" \
  -H "X-API-Key: $PARTICLE_API_KEY"

Cursors are opaque — treat them as strings, do not parse or construct them, and do not assume any ordering of values across versions. The default page size is endpoint-specific (often 25); use limit to override (typically up to 100).

Authentication

Two header forms are accepted; X-API-Key is recommended.

# Recommended
curl -H "X-API-Key: $PARTICLE_API_KEY" "https://api.particle.pro/v1/podcasts"

# Equivalent
curl -H "Authorization: Bearer $PARTICLE_API_KEY" "https://api.particle.pro/v1/podcasts"

Embed endpoints (/v1/embed/*) intentionally do not require authentication so the responses can be used as public iframe payloads.

Pricing weight

Every endpoint is available on every account — there is no tier lock. Endpoints are priced differently, though: heavier endpoints (full transcripts, transcript mentions, advertising analytics, cross-podcast clip search, competitor lookups) consume more credits per call than lighter ones (entity, topic, and podcast metadata; episode lookups and sub-resources; clip listings; embed). The OpenAPI tag on every operation declares the pricing class — tier:standard or tier:premium. Treat it as a hint about cost, not a hint about access. Your usage dashboard breaks down spend by endpoint so you can see where credits are going.

Choosing the right endpoint

The API exposes overlapping ways to find content. Pick by what you actually need.

You want…	Use	Notes
A podcast (show) by name	`GET /v1/podcasts/search?q=…`	Forgiving ranked name search with a `match_quality` signal per result. For a known Apple/Spotify/YouTube ID, use `/v1/podcasts/lookup` instead.
Dialogue matching the meaning of a query, paraphrase-tolerant	`GET /v1/podcasts/episodes/search?semantic_search=…`	Vector similarity. Express the topic the way you’d describe it; speakers may use different vocabulary.
Dialogue containing exact tokens or phrases	`GET /v1/podcasts/episodes/search?keyword_search=…`	BM25. Use for proper nouns, tickers, drug names, product codes.
Every dialogue line where a person or company is mentioned	`GET /v1/podcasts/mentions?entity_id=…`	Episode-grouped mention windows with `is_mention` flags. Use for the read-everything-about-X workflow.
Combine ranked search with an entity scope	`GET /v1/podcasts/episodes/search?semantic_search=…&entity_id=…`	Ranked candidates filtered to episodes where the entity appears.
Episode-level filtering by entity, topic, language, or date	`GET /v1/podcasts/episodes?entity_id=…`	Standard list, supports rich filters. Use when you don’t need dialogue.
All entities mentioned in one episode	`GET /v1/podcasts/episodes/{id}/transcript/mentions`	Per-episode rollup with surrounding-context windows.
Salience rollup of an entity across one podcast’s episodes	`GET /v1/podcasts/{id}/mentions`	Episode-level aggregate within one podcast.
AI-segmented structural sections of an episode	`GET /v1/podcasts/episodes/{id}/segments`	Intros, ads, topic discussions, interviews.
Browse highlight clips ranked by engagement	`GET /v1/podcasts/clips`	Curated highlights. Clips matching dialogue content come back inside `/v1/podcasts/episodes/search` results.
Who advertises on which podcasts	`GET /v1/companies/{id}/podcast/advertising` and `/v1/podcasts/advertising/leaderboard`	Sponsor-side analytics.

Quickstart walks through several of these patterns end-to-end.

Errors

Errors follow RFC 9457 (Problem Details for HTTP APIs). Every error response is application/problem+json with at minimum status, title, and detail, plus a stable error_code for programmatic branching and an optional resolve object pointing at how to fix the issue. See Errors → Overview for the full envelope, the catalog of error codes, and patterns for handling them in UI clients and agents.

Rate limits

Rate-limited responses return HTTP 429 with error_code: "rate_limit_exceeded". Back off and retry — the response includes guidance in detail. See rate_limit_exceeded.

Getting started

Podcasts

Companies

Knowledge graph

Alerts

Errors

IDs and slugs

Authentication

Pricing weight

Choosing the right endpoint

Errors

Rate limits

​IDs and slugs

​Cursor pagination

​Authentication

​Pricing weight

​Choosing the right endpoint

​Errors

​Rate limits

IDs and slugs

Cursor pagination

Authentication

Pricing weight

Choosing the right endpoint

Errors

Rate limits