Concepts

Cross-cutting conventions: IDs, pagination, errors, pricing weight, and choosing the right endpoint.

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
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.