IDs and slugs
Most endpoints with an{id} path parameter accept either:
- The canonical opaque ID (e.g.
17PzxG1t12xznofor Sam Altman,3CensCwu5G2oKCFgPrNf89for Nvidia), or - A human-readable slug (e.g.
sam-altman,nvidia,pivot,the-joe-rogan-experience).
entity_slug: "nvidia"), you can pass it directly to any other endpoint without first looking up the canonical ID.
Slugs are short handles Particle assigns, not names slugified: 20VC is the-twenty-minute-vc, Lenny’s Podcast is lennys, All-In is all-in. Take them from responses; a constructed slug returns 404, and trying other spellings never resolves it. A podcast slug is not an episode id: list the show’s episodes to get one. To turn a name into a slug, use the search endpoints below; each returns the slug alongside the match.
/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:cursor value back as a query parameter:
limit with the cursor: it continues the request that produced it, and changing a filter starts a new walk without one. 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.
/v1/embed/*) intentionally do not require authentication so the responses can be used as public iframe payloads, and GET /v1/podcasts/stats is open so anyone can read the catalog size.
A missing, mistyped, revoked, or expired key all return the same 401 with error_code: "api_key_required", so on a 401 check the header name (X-API-Key) and the key itself at platform.particle.pro/tokens rather than looking for a more specific code.
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.
Quickstart walks through several of these patterns end-to-end.
Errors
Errors follow RFC 9457 (Problem Details for HTTP APIs). Every error response isapplication/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
Every organization may make 10,000 requests per minute across all of its API keys and projects, on every plan. Rate-limited responses carryX-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (seconds until the window resets). A request over the limit returns HTTP 429 with error_code: "rate_limit_exceeded" and a Retry-After header; wait that long and retry. See rate_limit_exceeded.