# Particle API

> Podcast intelligence — podcasts, episodes, transcripts, guests, chart rankings, advertising, listener ratings, and political-bias and brand-suitability analytics — alongside company and people data and a topic taxonomy, exposed as one connected knowledge graph through a REST API and an MCP server.
REST API: `https://api.particle.pro`, data endpoints under `/v1/`. MCP server: `https://mcp.particle.pro`, Streamable HTTP. Setting a client up: https://api.particle.pro/agents.md. Page index of the documentation: https://docs.particle.pro/llms.txt.

## Authentication

- **API key.** `X-API-Key: pp_…` (or `Authorization: Bearer pp_…`) on REST requests that require authentication (the free endpoints below take none; the alert landing endpoints return more to a member's key), and on MCP for headless agents. A signed-in person creates keys at https://platform.particle.pro/tokens; each is shown once. A missing, mistyped, revoked, or expired key returns 401 `api_key_required`.
- **OAuth 2.1 (MCP, interactive clients).** Point the client at `https://mcp.particle.pro`; it registers, opens the browser for approval, and refreshes tokens itself. Access tokens are bound to the MCP server and are not accepted by the REST API. Recipe: https://api.particle.pro/auth.md
- **x402 (no account).** A keyless request to a billable endpoint returns `402` with the USDC payment terms (Base) in `PAYMENT-REQUIRED`; sign the transfer and retry with `PAYMENT-SIGNATURE`. The prices below are per call; a request that fails is never charged. https://docs.particle.pro/x402.md
- **MPP (no account).** When `WWW-Authenticate: Payment` is advertised, use an MPP EVM charge client to pay the same USDC price on Base with `Authorization: Payment`; the receipt is in `Payment-Receipt`. Send one payment protocol per request. https://docs.particle.pro/mpp.md
## Instructions for LLM agents

- **Pick the right surface.** Building an agent loop (Claude Code, Cursor, Codex, ChatGPT, a custom MCP client)? Use the MCP server at `https://mcp.particle.pro` — slug-first inputs, bundled responses, markdown output. Building a service (server-to-server, scheduled jobs)? Use the REST API at `https://api.particle.pro` with an API key — typed JSON, OpenAPI schema. Building a frontend? Route calls through your own backend so the API key stays server-side — never embed keys in browser or mobile code. Connecting a client for someone? Follow `https://api.particle.pro/agents.md`. The endpoint and tool map with per-call prices is `https://api.particle.pro/llms.txt`.
- **No API key? Pay per request.** Every billable REST endpoint and `POST /mcp` accept an x402 USDC micropayment (Base) in place of a credential: a keyless call returns `402` with the payment requirements in the `PAYMENT-REQUIRED` header; sign the transfer and retry with `PAYMENT-SIGNATURE`, and the receipt comes back in `PAYMENT-RESPONSE`. Each REST call and each MCP `tools/call` costs its per-call price, a whole number of cents from $0.01 (MCP `initialize` and `tools/list` are free, and `particle_catalog` lists every tool with its price); a request whose every call fails is never charged, while a batch with any successful call settles in full. Free endpoints stay free; alerts and enterprise surfaces still need an account. Sending any credential — even an invalid one — takes the normal auth path instead. Discovery: `/.well-known/x402.json` on api.particle.pro and mcp.particle.pro lists the payable endpoints and terms, and every payable MCP tool with its per-call price under `mcp.tools`; the `/.well-known/x402` manifest on each host lists that host's own resources, so only the MCP host's carries the per-tool list; every payable operation in https://api.particle.pro/openapi.json carries `x-payment-info` and a `402` response; each 402 carries a Bazaar declaration, so the endpoints are searchable in the Coinbase x402 Bazaar. See https://docs.particle.pro/x402.md.
- **Tools are lean by default and expand.** Most MCP tools return a minimal payload and opt into richer sections via an `include` array (e.g. a company's people, products, and competitors; a person's roles and podcast appearances) or a `mode`/`format` switch — a tool does far more than its name implies. Check the tool's input schema before assuming a capability is missing.
- **Responses form a graph; slugs are edges.** A slug a tool returns (person, company, podcast, episode, publisher, guest) is a valid input to the other tools. Resolve a free-text name once (`particle_entity_resolve`, `particle_person_resolve`, `particle_company_resolve`, `particle_podcast_resolve`), then traverse: company → its people → a person's podcast appearances → that episode's transcript and the entities named in it. Never guess or fabricate a slug — resolve it. 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.
- **Choose search by intent.** `particle_podcast_search_transcripts` finds dialogue *about* a topic (semantic, keyword, or hybrid; relevant clips arrive inline on matches). `particle_podcast_find_mentions` finds lines *naming* a resolved entity — a person, company, or any other resolvable slug (places, organizations, events, concepts) — its default `format="summary"` previews the first ~10 mention lines per episode for scanning; call back with `format="detail"` and an `episode_slug` for an episode's complete mention set with context. Both take `format="compact"` for screening many results (a fan-out over companies, themes, or dates) before reading any: a compact search match is its identity rows, segment id, relevance score, and the segment's one-line description, with no dialogue; a compact mentions episode is its mention count, the strings the entity was mentioned as, and the segments carrying the mentions, with no lines. Cite by segment id and read only the survivors. `particle_podcast_list_episodes` is filter-driven episode discovery (podcast, person, company, language, date, duration). Don't put an entity name in `semantic_search` — that's a topic field; resolve the name and pass it as a `person_slug`/`company_slug`/`entity_slug` filter, or use `particle_podcast_find_mentions`. For "how often over time" questions, use `particle_podcast_get_episode_timeseries` instead of paging search or mentions once per period. For "shows like this show", use `particle_podcast_list_related` (add `include: ["basis"]` for the reasons) or `include: ["related"]` on `particle_podcast_resolve` — not a topic or semantic search; for "who else covered this episode", `particle_podcast_list_related_episodes` or `include: ["related"]` on `particle_podcast_get_episode`. For where a guest could appear next, use `include: ["recommended_podcasts"]` on `particle_podcast_get_guest`; for who a show could book, `include: ["recommended_guests"]` on `particle_podcast_resolve`; for advertisers a show could pitch, `include: ["recommended_sponsors"]` on `particle_podcast_resolve` (premium). Within a search, `semantic_search` carries the idea (a sentence, paraphrase-tolerant) while `keyword_search` carries words that must be literally spoken — every word must occur in the same passage, so keep it to one or two exact tokens and never put a sentence there; `keyword_match="ranked"` relaxes it to a relevance hint. Add filters only after a broad query shows the topic has coverage: when filters empty a search, the error names the parameter responsible and the retry to make, so act on it rather than re-issuing variations.
- **Not every episode is transcribed.** Episodes carry `transcript_status`. A show's older episodes, discovered in its feed but not transcribed, are its back catalogue: `particle_podcast_list_episodes` lists them only when you pass `transcript_status` with `podcast_slug`, and they read `requestable`, or `queued` once someone has requested the transcript. An episode without a transcript has no speakers, entities, segments or clips, so its empty lists say nothing about who was on it or what it covered — and counts over a show's episodes cover only its transcribed ones. `include: ["coverage"]` on `particle_podcast_resolve` says how many of a show's episodes exist and how many are transcribed, by year.
- **Most tools are read-only; the `particle_alert_*` tools are the writable exception.** They create and manage alerts that each watch a single entity for podcast mentions or speaker appearances, and they act on the one project your credential is scoped to — no project parameter, no way to reach another project's alerts. Resolve a name to a slug, optionally preview match frequency with `particle_alert_preview`, then `particle_alert_create` to start watching it. When a name has no slug, or its entity has no podcast coverage, watch the phrase instead: `kind: "KEYWORD_MENTION"` with `keyword` in place of `entities`, and a `description` saying what the phrase means. Alerts accept a persistent `filters` object on create and update — narrow what gets surfaced by language, relevance (`EVERYTHING`|`RELEVANT`), source popularity (`ANY`|`POPULAR`), and (for `PODCAST_SPEAKER` alerts) `speaker_roles`. `particle_alert_create`/`particle_alert_update` mutate and `particle_alert_delete` is a destructive soft delete.
- **Discovery is free; execution is metered.** Discovery methods (`initialize`, `tools/list`, `resources/list`, `resources/read`, `prompts/list`, `ping`) and tools marked free are intentionally served without authentication; every metered `tools/call` requires an OAuth bearer, a `pp_` API key, or an x402 payment. A bare connection advertises the default categories, but every public tool is callable by name. `particle_catalog` (free) lists every category and tool with expand options, plus full input schemas per category; opt-in categories advertise on `tools/list` via the MCP URL, e.g. `?include=podcast_advertising,podcast_publishers,podcast_ratings,podcast_bias,podcast_suitability` (use these canonical tokens — unknown values are silently ignored).
- **Errors course-correct.** Tool errors lead with a stable `**Error code:** <slug>` line and a suggestion naming the next call (404 → re-resolve the slug; 400/422 → check the schema via `particle_catalog`). REST errors are RFC 9457 `application/problem+json` with a stable `error_code` and, when there is a self-service fix, a `resolve` object naming the action, URL, method, and endpoint; a 404 on a slug means re-resolve it, a 422 names the parameter at fault, and a 429 carries `Retry-After`. Follow the suggestion instead of blind-retrying, and never retry-loop an `internal_error`.
- **Reading these docs?** Append `.md` to any docs URL for raw markdown (e.g. `https://docs.particle.pro/mcp/overview.md`), fetch the entire corpus from `https://docs.particle.pro/llms-full.txt`, or start from the page index at `https://docs.particle.pro/llms.txt`.

- **Render selected evidence only when a visual helps.** After retrieving Particle data, call `particle_radar_render_cards` directly with a title and up to six episode, podcast, company, or person cards. Use only evidence and canonical HTTPS source URLs returned by the data tools; do not invent links or pass credentials. The opt-in `radar` category (also in `include=all`) is free presentation, with no data fetch or storage. The renderer owns an MCP Apps UI resource and returns structured cards plus a complete Markdown fallback. Other data tools keep their existing output formats; `particle_call` provides the renderer's text fallback only.
## REST endpoints

Grouped by resource. Each line: the documentation page, the operation, the pricing tier, and the keyless x402/MPP price where the endpoint is payable per request; keyed calls meter to the organization's plan instead. Base URL `https://api.particle.pro`. Schema: https://api.particle.pro/openapi.json.

### Podcasts

- [List and search podcasts](https://docs.particle.pro/api-reference/podcasts/list-and-search-podcasts): `GET /v1/podcasts` — standard tier, x402/MPP $0.01 per call
- [Search podcasts](https://docs.particle.pro/api-reference/podcasts/search-podcasts): `GET /v1/podcasts/search` — standard tier, x402/MPP $0.01 per call
- [List podcast topics](https://docs.particle.pro/api-reference/podcasts/list-podcast-topics): `GET /v1/podcasts/topics` — standard tier, x402/MPP $0.03 per call
- [Look up podcasts by external platform identifier](https://docs.particle.pro/api-reference/podcasts/look-up-podcasts-by-external-platform-identifier): `GET /v1/podcasts/lookup` — standard tier, x402/MPP $0.01 per call
- [Get a podcast](https://docs.particle.pro/api-reference/podcasts/get-a-podcast): `GET /v1/podcasts/{id}` — standard tier, x402/MPP $0.01 per call
- [List episodes for a podcast](https://docs.particle.pro/api-reference/podcasts/list-episodes-for-a-podcast): `GET /v1/podcasts/{id}/episodes` — standard tier, x402/MPP $0.03 per call
- [List entity mentions in a podcast](https://docs.particle.pro/api-reference/podcasts/list-entity-mentions-in-a-podcast): `GET /v1/podcasts/{id}/mentions` — standard tier, x402/MPP $0.03 per call
- [Get podcast advertising profile](https://docs.particle.pro/api-reference/podcasts/get-podcast-advertising-profile): `GET /v1/podcasts/{id}/advertising` — premium tier, x402/MPP $0.03 per call
- [List sponsors a podcast could pitch](https://docs.particle.pro/api-reference/podcasts/list-sponsors-a-podcast-could-pitch): `GET /v1/podcasts/{id}/recommendations/sponsors` — premium tier, x402/MPP $0.03 per call
- [Get a podcast's format profile](https://docs.particle.pro/api-reference/podcasts/get-a-podcasts-format-profile): `GET /v1/podcasts/{id}/format` — standard tier, x402/MPP $0.03 per call
- [List related podcasts](https://docs.particle.pro/api-reference/podcasts/list-related-podcasts): `GET /v1/podcasts/{id}/related` — standard tier, x402/MPP $0.03 per call
- [Get a podcast's latest bias analysis](https://docs.particle.pro/api-reference/podcasts/get-a-podcasts-latest-bias-analysis): `GET /v1/podcasts/{id}/bias` — standard tier, x402/MPP $0.03 per call
- [Get a podcast's latest brand suitability assessment](https://docs.particle.pro/api-reference/podcasts/get-a-podcasts-latest-brand-suitability-assessment): `GET /v1/podcasts/{id}/suitability` — premium tier, x402/MPP $0.04 per call
- [List a podcast's third-party platform presences](https://docs.particle.pro/api-reference/podcasts/list-a-podcasts-third-party-platform-presences): `GET /v1/podcasts/{id}/external-links` — standard tier, x402/MPP $0.04 per call
- [Download the show archive](https://docs.particle.pro/api-reference/podcasts/download-the-show-archive): `GET /v1/podcasts/archive/download` — by arrangement; access is granted per organization
- [Get podcast catalog statistics](https://docs.particle.pro/api-reference/podcasts/get-podcast-catalog-statistics): `GET /v1/podcasts/stats` — free, no credential needed
### Podcast Episodes

- [List episodes](https://docs.particle.pro/api-reference/podcast-episodes/list-episodes): `GET /v1/podcasts/episodes` — standard tier, x402/MPP $0.01 per call
- [Poll the episode feed](https://docs.particle.pro/api-reference/podcast-episodes/poll-the-episode-feed): `GET /v1/podcasts/episodes/feed` — standard tier, x402/MPP $0.01 per call
- [Get episode timeseries](https://docs.particle.pro/api-reference/podcast-episodes/get-episode-timeseries): `GET /v1/podcasts/episodes/timeseries` — standard tier, x402/MPP $0.01 per call
- [Look up episodes by external identifier](https://docs.particle.pro/api-reference/podcast-episodes/look-up-episodes-by-external-identifier): `GET /v1/podcasts/episodes/lookup` — standard tier, x402/MPP $0.01 per call
- [Get an episode](https://docs.particle.pro/api-reference/podcast-episodes/get-an-episode): `GET /v1/podcasts/episodes/{id}` — standard tier, x402/MPP $0.01 per call
- [List speakers in an episode](https://docs.particle.pro/api-reference/podcast-episodes/list-speakers-in-an-episode): `GET /v1/podcasts/episodes/{id}/speakers` — standard tier, x402/MPP $0.03 per call
- [List entities in an episode](https://docs.particle.pro/api-reference/podcast-episodes/list-entities-in-an-episode): `GET /v1/podcasts/episodes/{id}/entities` — standard tier, x402/MPP $0.03 per call
- [List topics for an episode](https://docs.particle.pro/api-reference/podcast-episodes/list-topics-for-an-episode): `GET /v1/podcasts/episodes/{id}/topics` — standard tier, x402/MPP $0.03 per call
- [List related episodes](https://docs.particle.pro/api-reference/podcast-episodes/list-related-episodes): `GET /v1/podcasts/episodes/{id}/related` — standard tier, x402/MPP $0.03 per call
- [List ads in an episode](https://docs.particle.pro/api-reference/podcast-episodes/list-ads-in-an-episode): `GET /v1/podcasts/episodes/{id}/ads` — premium tier, x402/MPP $0.03 per call
- [Stream episodes](https://docs.particle.pro/api-reference/podcast-episodes/stream-episodes): `GET /v1/podcasts/episodes/stream` — Enterprise plan
- [Stream episodes (POST)](https://docs.particle.pro/api-reference/podcast-episodes/stream-episodes-post): `POST /v1/podcasts/episodes/stream` — Enterprise plan
- [List the episode archive](https://docs.particle.pro/api-reference/podcast-episodes/list-the-episode-archive): `GET /v1/podcasts/episodes/archive` — by arrangement; access is granted per organization
- [Download the episode archive](https://docs.particle.pro/api-reference/podcast-episodes/download-the-episode-archive): `GET /v1/podcasts/episodes/archive/download` — by arrangement; access is granted per organization
- [Replay the episode archive](https://docs.particle.pro/api-reference/podcast-episodes/replay-the-episode-archive): `GET /v1/podcasts/episodes/archive/stream` — by arrangement; access is granted per organization
### Podcast Episode Search

- [Search podcast episode content](https://docs.particle.pro/api-reference/podcast-episode-search/search-podcast-episode-content): `GET /v1/podcasts/episodes/search` — standard tier, x402/MPP $0.03 per call
- [Get mention timeseries](https://docs.particle.pro/api-reference/podcast-episode-search/get-mention-timeseries): `GET /v1/podcasts/mentions/timeseries` — standard tier, x402/MPP $0.04 per call
- [Search podcast dialogue for entity mentions](https://docs.particle.pro/api-reference/podcast-episode-search/search-podcast-dialogue-for-entity-mentions): `GET /v1/podcasts/mentions` — standard tier, x402/MPP $0.04 per call
### Podcast Transcripts

- [Get episode transcript](https://docs.particle.pro/api-reference/podcast-transcripts/get-episode-transcript): `GET /v1/podcasts/episodes/{id}/transcript` — standard tier, x402/MPP $0.03 per call
- [Get word-level transcript](https://docs.particle.pro/api-reference/podcast-transcripts/get-word-level-transcript): `GET /v1/podcasts/episodes/{id}/transcript/words` — standard tier, x402/MPP $0.03 per call
- [Get a transcript excerpt around a moment](https://docs.particle.pro/api-reference/podcast-transcripts/get-a-transcript-excerpt-around-a-moment): `GET /v1/podcasts/episodes/{id}/transcript/preview` — standard tier, x402/MPP $0.01 per call
- [Get segment transcript](https://docs.particle.pro/api-reference/podcast-transcripts/get-segment-transcript): `GET /v1/podcasts/segments/{id}/transcript` — standard tier, x402/MPP $0.03 per call
- [Get clip transcript](https://docs.particle.pro/api-reference/podcast-transcripts/get-clip-transcript): `GET /v1/podcasts/clips/{id}/transcript` — standard tier, x402/MPP $0.03 per call
- [Get entity mentions in transcript](https://docs.particle.pro/api-reference/podcast-transcripts/get-entity-mentions-in-transcript): `GET /v1/podcasts/episodes/{id}/transcript/mentions` — standard tier, x402/MPP $0.03 per call
### Podcast Segments

- [List segments](https://docs.particle.pro/api-reference/podcast-segments/list-segments): `GET /v1/podcasts/segments` — standard tier, x402/MPP $0.01 per call
- [Get a segment](https://docs.particle.pro/api-reference/podcast-segments/get-a-segment): `GET /v1/podcasts/segments/{id}` — standard tier, x402/MPP $0.01 per call
- [List segments for an episode](https://docs.particle.pro/api-reference/podcast-segments/list-segments-for-an-episode): `GET /v1/podcasts/episodes/{id}/segments` — standard tier, x402/MPP $0.03 per call
### Podcast Clips

- [List clips](https://docs.particle.pro/api-reference/podcast-clips/list-clips): `GET /v1/podcasts/clips` — standard tier, x402/MPP $0.03 per call
- [Get a clip](https://docs.particle.pro/api-reference/podcast-clips/get-a-clip): `GET /v1/podcasts/clips/{id}` — standard tier, x402/MPP $0.03 per call
- [List clips for an episode](https://docs.particle.pro/api-reference/podcast-clips/list-clips-for-an-episode): `GET /v1/podcasts/episodes/{id}/clips` — standard tier, x402/MPP $0.01 per call
### Podcast Guests

- [List podcast guests](https://docs.particle.pro/api-reference/podcast-guests/list-podcast-guests): `GET /v1/podcasts/guests` — standard tier, x402/MPP $0.03 per call
- [Get a podcast guest profile](https://docs.particle.pro/api-reference/podcast-guests/get-a-podcast-guest-profile): `GET /v1/podcasts/guests/{id}` — standard tier, x402/MPP $0.03 per call
- [List appearances for a podcast guest](https://docs.particle.pro/api-reference/podcast-guests/list-appearances-for-a-podcast-guest): `GET /v1/podcasts/guests/{id}/appearances` — standard tier, x402/MPP $0.03 per call
- [List podcasts a guest has appeared on](https://docs.particle.pro/api-reference/podcast-guests/list-podcasts-a-guest-has-appeared-on): `GET /v1/podcasts/guests/{id}/podcasts` — standard tier, x402/MPP $0.04 per call
- [List the guest roster for a podcast](https://docs.particle.pro/api-reference/podcast-guests/list-the-guest-roster-for-a-podcast): `GET /v1/podcasts/{id}/guests` — standard tier, x402/MPP $0.03 per call
- [List podcasts a guest could plausibly appear on next](https://docs.particle.pro/api-reference/podcast-guests/list-podcasts-a-guest-could-plausibly-appear-on-next): `GET /v1/podcasts/guests/{id}/recommendations/podcasts` — standard tier, x402/MPP $0.03 per call
- [List guests a podcast could plausibly book](https://docs.particle.pro/api-reference/podcast-guests/list-guests-a-podcast-could-plausibly-book): `GET /v1/podcasts/{id}/recommendations/guests` — standard tier, x402/MPP $0.03 per call
- [List trending podcast guests](https://docs.particle.pro/api-reference/podcast-guests/list-trending-podcast-guests): `GET /v1/podcasts/guests/trends` — standard tier, x402/MPP $0.04 per call
- [Get a guest's brand-suitability exposure profile](https://docs.particle.pro/api-reference/podcast-guests/get-a-guests-brand-suitability-exposure-profile): `GET /v1/podcasts/guests/{id}/suitability` — standard tier, x402/MPP $0.04 per call
### Podcast Rankings

- [List podcast rankings](https://docs.particle.pro/api-reference/podcast-rankings/list-podcast-rankings): `GET /v1/podcasts/rankings` — premium tier, x402/MPP $0.03 per call
- [List current rankings for a podcast](https://docs.particle.pro/api-reference/podcast-rankings/list-current-rankings-for-a-podcast): `GET /v1/podcasts/{id}/rankings` — premium tier, x402/MPP $0.03 per call
- [Summarize a podcast's chart presence](https://docs.particle.pro/api-reference/podcast-rankings/summarize-a-podcasts-chart-presence): `GET /v1/podcasts/{id}/rankings/summary` — premium tier, x402/MPP $0.03 per call
- [List ranking sources](https://docs.particle.pro/api-reference/podcast-rankings/list-ranking-sources): `GET /v1/podcasts/rankings/sources` — standard tier, x402/MPP $0.01 per call
- [List ranking countries](https://docs.particle.pro/api-reference/podcast-rankings/list-ranking-countries): `GET /v1/podcasts/rankings/countries` — standard tier, x402/MPP $0.01 per call
- [List ranking categories](https://docs.particle.pro/api-reference/podcast-rankings/list-ranking-categories): `GET /v1/podcasts/rankings/categories` — standard tier, x402/MPP $0.01 per call
- [Get chart slot history](https://docs.particle.pro/api-reference/podcast-rankings/get-chart-slot-history): `GET /v1/podcasts/rankings/history` — premium tier, x402/MPP $0.04 per call
- [Get historical rankings for a podcast](https://docs.particle.pro/api-reference/podcast-rankings/get-historical-rankings-for-a-podcast): `GET /v1/podcasts/{id}/rankings/history` — premium tier, x402/MPP $0.04 per call
- [List ranking movers](https://docs.particle.pro/api-reference/podcast-rankings/list-ranking-movers): `GET /v1/podcasts/rankings/movers` — premium tier, x402/MPP $0.04 per call
### Podcast Ratings

- [List ratings for a podcast](https://docs.particle.pro/api-reference/podcast-ratings/list-ratings-for-a-podcast): `GET /v1/podcasts/{id}/ratings` — standard tier, x402/MPP $0.01 per call
- [Summarize a podcast's ratings](https://docs.particle.pro/api-reference/podcast-ratings/summarize-a-podcasts-ratings): `GET /v1/podcasts/{id}/ratings/summary` — standard tier, x402/MPP $0.03 per call
### Podcast Advertising

- [Get publisher advertising profile](https://docs.particle.pro/api-reference/podcast-advertising/get-publisher-advertising-profile): `GET /v1/podcasts/publishers/{id}/advertising` — premium tier, x402/MPP $0.03 per call
- [List sponsors for a publisher](https://docs.particle.pro/api-reference/podcast-advertising/list-sponsors-for-a-publisher): `GET /v1/podcasts/publishers/{id}/advertising/sponsors` — premium tier, x402/MPP $0.04 per call
- [List publisher's podcasts ranked by ad volume](https://docs.particle.pro/api-reference/podcast-advertising/list-publishers-podcasts-ranked-by-ad-volume): `GET /v1/podcasts/publishers/{id}/advertising/podcasts` — premium tier, x402/MPP $0.03 per call
- [List sponsors](https://docs.particle.pro/api-reference/podcast-advertising/list-sponsors): `GET /v1/podcasts/advertising/sponsors` — premium tier, x402/MPP $0.03 per call
- [List trending sponsors](https://docs.particle.pro/api-reference/podcast-advertising/list-trending-sponsors): `GET /v1/podcasts/advertising/sponsors/trends` — premium tier, x402/MPP $0.04 per call
- [Get a sponsor](https://docs.particle.pro/api-reference/podcast-advertising/get-a-sponsor): `GET /v1/podcasts/advertising/sponsors/{id}` — premium tier, x402/MPP $0.03 per call
- [List podcasts for a sponsor](https://docs.particle.pro/api-reference/podcast-advertising/list-podcasts-for-a-sponsor): `GET /v1/podcasts/advertising/sponsors/{id}/podcasts` — premium tier, x402/MPP $0.03 per call
- [List sponsors advertising on a podcast](https://docs.particle.pro/api-reference/podcast-advertising/list-sponsors-advertising-on-a-podcast): `GET /v1/podcasts/{id}/advertising/sponsors` — premium tier, x402/MPP $0.04 per call
- [List ad segments for a sponsor](https://docs.particle.pro/api-reference/podcast-advertising/list-ad-segments-for-a-sponsor): `GET /v1/podcasts/advertising/sponsors/{id}/segments` — premium tier, x402/MPP $0.03 per call
- [Get advertising leaderboard](https://docs.particle.pro/api-reference/podcast-advertising/get-advertising-leaderboard): `GET /v1/podcasts/advertising/leaderboard` — premium tier, x402/MPP $0.04 per call
- [Get advertising leaderboard preview](https://docs.particle.pro/api-reference/podcast-advertising/get-advertising-leaderboard-preview): `GET /v1/podcasts/advertising/leaderboard/preview` — standard tier, x402/MPP $0.01 per call
- [Get advertising timeseries](https://docs.particle.pro/api-reference/podcast-advertising/get-advertising-timeseries): `GET /v1/podcasts/advertising/timeseries` — premium tier, x402/MPP $0.04 per call
- [Get sponsor co-occurrence](https://docs.particle.pro/api-reference/podcast-advertising/get-sponsor-co-occurrence): `GET /v1/podcasts/advertising/co-occurrence` — premium tier, x402/MPP $0.04 per call
- [List publishers for a sponsor](https://docs.particle.pro/api-reference/podcast-advertising/list-publishers-for-a-sponsor): `GET /v1/podcasts/advertising/sponsors/{id}/publishers` — premium tier, x402/MPP $0.03 per call
- [Get publisher advertising leaderboard](https://docs.particle.pro/api-reference/podcast-advertising/get-publisher-advertising-leaderboard): `GET /v1/podcasts/advertising/publishers/leaderboard` — premium tier, x402/MPP $0.04 per call
### Podcast Publishers

- [List podcast publishers](https://docs.particle.pro/api-reference/podcast-publishers/list-podcast-publishers): `GET /v1/podcasts/publishers` — standard tier, x402/MPP $0.03 per call
- [Get a podcast publisher](https://docs.particle.pro/api-reference/podcast-publishers/get-a-podcast-publisher): `GET /v1/podcasts/publishers/{id}` — standard tier, x402/MPP $0.03 per call
- [List podcasts for a publisher](https://docs.particle.pro/api-reference/podcast-publishers/list-podcasts-for-a-publisher): `GET /v1/podcasts/publishers/{id}/podcasts` — standard tier, x402/MPP $0.04 per call
- [Get a publisher's brand suitability profile](https://docs.particle.pro/api-reference/podcast-publishers/get-a-publishers-brand-suitability-profile): `GET /v1/podcasts/publishers/{id}/suitability` — premium tier, x402/MPP $0.04 per call
- [List a publisher's podcasts with their suitability verdicts](https://docs.particle.pro/api-reference/podcast-publishers/list-a-publishers-podcasts-with-their-suitability-verdicts): `GET /v1/podcasts/publishers/{id}/suitability/podcasts` — premium tier, x402/MPP $0.03 per call
### Podcast Bias

- [Get publisher political bias profile](https://docs.particle.pro/api-reference/podcast-bias/get-publisher-political-bias-profile): `GET /v1/podcasts/publishers/{id}/bias` — premium tier, x402/MPP $0.03 per call
- [List analyzed podcasts for a publisher](https://docs.particle.pro/api-reference/podcast-bias/list-analyzed-podcasts-for-a-publisher): `GET /v1/podcasts/publishers/{id}/bias/podcasts` — premium tier, x402/MPP $0.03 per call
- [Rank publishers by political bias metric](https://docs.particle.pro/api-reference/podcast-bias/rank-publishers-by-political-bias-metric): `GET /v1/podcasts/bias/publishers/leaderboard` — premium tier, x402/MPP $0.04 per call
- [List publishers with podcasts in a bias bucket](https://docs.particle.pro/api-reference/podcast-bias/list-publishers-with-podcasts-in-a-bias-bucket): `GET /v1/podcasts/bias/{result}/publishers` — premium tier, x402/MPP $0.03 per call
### Podcast Brand Suitability

- [Get a cross-publisher suitability leaderboard](https://docs.particle.pro/api-reference/podcast-brand-suitability/get-a-cross-publisher-suitability-leaderboard): `GET /v1/podcasts/suitability/publishers/leaderboard` — premium tier, x402/MPP $0.04 per call
- [Get publishers ranked by exposure to a brand-safety category](https://docs.particle.pro/api-reference/podcast-brand-suitability/get-publishers-ranked-by-exposure-to-a-brand-safety-category): `GET /v1/podcasts/suitability/categories/{code}/publishers` — premium tier, x402/MPP $0.04 per call
### Entities

- [List entities](https://docs.particle.pro/api-reference/entities/list-entities): `GET /v1/entities` — standard tier, x402/MPP $0.01 per call
- [Search entities](https://docs.particle.pro/api-reference/entities/search-entities): `GET /v1/entities/search` — standard tier, x402/MPP $0.01 per call
- [Look up people and companies by external identifier](https://docs.particle.pro/api-reference/entities/look-up-people-and-companies-by-external-identifier): `GET /v1/entities/lookup` — standard tier, x402/MPP $0.01 per call
- [List entity types](https://docs.particle.pro/api-reference/entities/list-entity-types): `GET /v1/entities/types` — standard tier, x402/MPP $0.01 per call
- [Get an entity](https://docs.particle.pro/api-reference/entities/get-an-entity): `GET /v1/entities/{id}` — standard tier, x402/MPP $0.01 per call
### People

- [Get a Person](https://docs.particle.pro/api-reference/people/get-a-person): `GET /v1/people/{id}` — standard tier, x402/MPP $0.01 per call
- [List a Person's external profiles](https://docs.particle.pro/api-reference/people/list-a-persons-external-profiles): `GET /v1/people/{slug}/external-links` — standard tier, x402/MPP $0.04 per call
### Companies

- [List companies](https://docs.particle.pro/api-reference/companies/list-companies): `GET /v1/companies` — standard tier, x402/MPP $0.01 per call
- [Get a company](https://docs.particle.pro/api-reference/companies/get-a-company): `GET /v1/companies/{id}` — standard tier, x402/MPP $0.01 per call
- [List a company's external profiles](https://docs.particle.pro/api-reference/companies/list-a-companys-external-profiles): `GET /v1/companies/{id}/external-links` — standard tier, x402/MPP $0.04 per call
- [List company products](https://docs.particle.pro/api-reference/companies/list-company-products): `GET /v1/companies/{id}/products` — standard tier, x402/MPP $0.03 per call
- [Get company advertising profile](https://docs.particle.pro/api-reference/companies/get-company-advertising-profile): `GET /v1/companies/{id}/podcast/advertising` — premium tier, x402/MPP $0.03 per call
- [List podcasts carrying company advertising](https://docs.particle.pro/api-reference/companies/list-podcasts-carrying-company-advertising): `GET /v1/companies/{id}/podcast/advertising/podcasts` — premium tier, x402/MPP $0.03 per call
- [List podcasts a company could advertise on next](https://docs.particle.pro/api-reference/companies/list-podcasts-a-company-could-advertise-on-next): `GET /v1/companies/{id}/podcast/recommendations` — premium tier, x402/MPP $0.03 per call
- [List company podcast advertising placements](https://docs.particle.pro/api-reference/companies/list-company-podcast-advertising-placements): `GET /v1/companies/{id}/podcast/advertising/placements` — premium tier, x402/MPP $0.03 per call
- [List company competitors](https://docs.particle.pro/api-reference/companies/list-company-competitors): `GET /v1/companies/{id}/competitors` — premium tier, x402/MPP $0.03 per call
- [List company people](https://docs.particle.pro/api-reference/companies/list-company-people): `GET /v1/companies/{id}/people` — standard tier, x402/MPP $0.03 per call
### Topics

- [List topics](https://docs.particle.pro/api-reference/topics/list-topics): `GET /v1/topics` — standard tier, x402/MPP $0.01 per call
- [Get a topic](https://docs.particle.pro/api-reference/topics/get-a-topic): `GET /v1/topics/{id}` — standard tier, x402/MPP $0.01 per call
### Alerts

- [Create an alert](https://docs.particle.pro/api-reference/alerts/create-an-alert): `POST /v1/projects/{projectId}/alerts` — standard tier, included with plans that carry the feature
- [List alerts](https://docs.particle.pro/api-reference/alerts/list-alerts): `GET /v1/projects/{projectId}/alerts` — standard tier, included with plans that carry the feature
- [Get an alert](https://docs.particle.pro/api-reference/alerts/get-an-alert): `GET /v1/alerts/{id}` — standard tier, included with plans that carry the feature
- [Update an alert](https://docs.particle.pro/api-reference/alerts/update-an-alert): `PATCH /v1/alerts/{id}` — standard tier, included with plans that carry the feature
- [Delete an alert](https://docs.particle.pro/api-reference/alerts/delete-an-alert): `DELETE /v1/alerts/{id}` — standard tier, included with plans that carry the feature
- [Send a test webhook](https://docs.particle.pro/api-reference/alerts/send-a-test-webhook): `POST /v1/alerts/{id}/test-webhook` — standard tier, included with plans that carry the feature
- [List matches for an alert](https://docs.particle.pro/api-reference/alerts/list-matches-for-an-alert): `GET /v1/alerts/{id}/matches` — standard tier, included with plans that carry the feature
- [List deliveries for an alert](https://docs.particle.pro/api-reference/alerts/list-deliveries-for-an-alert): `GET /v1/alerts/{id}/deliveries` — standard tier, included with plans that carry the feature
- [Get a single alert delivery](https://docs.particle.pro/api-reference/alerts/get-a-single-alert-delivery): `GET /v1/alerts/deliveries/{id}` — free, no credential needed
- [Get the exact JSON a webhook delivery POSTed](https://docs.particle.pro/api-reference/alerts/get-the-exact-json-a-webhook-delivery-posted): `GET /v1/alerts/deliveries/{id}/webhook-payload` — free, no credential needed
- [Get a single alert match](https://docs.particle.pro/api-reference/alerts/get-a-single-alert-match): `GET /v1/alerts/matches/{id}` — free, no credential needed
- [Preview match frequency for an alert before creating it](https://docs.particle.pro/api-reference/alerts/preview-match-frequency-for-an-alert-before-creating-it): `POST /v1/projects/{projectId}/alerts/preview` — standard tier, included with plans that carry the feature
- [Get the status and result of an alert preview](https://docs.particle.pro/api-reference/alerts/get-the-status-and-result-of-an-alert-preview): `GET /v1/alerts/preview/{previewId}` — standard tier, included with plans that carry the feature
- [Preview alert disable action](https://docs.particle.pro/api-reference/alerts/preview-alert-disable-action): `GET /v1/alerts/disable` — free, no credential needed
- [Disable an alert via email-footer token](https://docs.particle.pro/api-reference/alerts/disable-an-alert-via-email-footer-token): `POST /v1/alerts/disable` — free, no credential needed
### Webhook Connections

- [Create a webhook connection](https://docs.particle.pro/api-reference/webhook-connections/create-a-webhook-connection): `POST /v1/projects/{projectId}/webhooks/connections` — standard tier, included with plans that carry the feature
- [List webhook connections for a project](https://docs.particle.pro/api-reference/webhook-connections/list-webhook-connections-for-a-project): `GET /v1/projects/{projectId}/webhooks/connections` — standard tier, included with plans that carry the feature
- [Get a webhook connection](https://docs.particle.pro/api-reference/webhook-connections/get-a-webhook-connection): `GET /v1/projects/{projectId}/webhooks/connections/{id}` — standard tier, included with plans that carry the feature
- [Delete a webhook connection](https://docs.particle.pro/api-reference/webhook-connections/delete-a-webhook-connection): `DELETE /v1/projects/{projectId}/webhooks/connections/{id}` — standard tier, included with plans that carry the feature
- [Rotate a webhook connection's signing secret](https://docs.particle.pro/api-reference/webhook-connections/rotate-a-webhook-connections-signing-secret): `POST /v1/projects/{projectId}/webhooks/connections/{id}/secret/rotate` — standard tier, included with plans that carry the feature
### Slack Connections

- [Initiate a Slack workspace OAuth install](https://docs.particle.pro/api-reference/slack-connections/initiate-a-slack-workspace-oauth-install): `POST /v1/projects/{projectId}/slack/connections/initiate` — standard tier, included with plans that carry the feature
- [Complete a Slack workspace OAuth install](https://docs.particle.pro/api-reference/slack-connections/complete-a-slack-workspace-oauth-install): `GET /v1/slack/connections/callback` — free, no credential needed
- [List Slack connections for a project](https://docs.particle.pro/api-reference/slack-connections/list-slack-connections-for-a-project): `GET /v1/projects/{projectId}/slack/connections` — standard tier, included with plans that carry the feature
- [List channels for a Slack connection](https://docs.particle.pro/api-reference/slack-connections/list-channels-for-a-slack-connection): `GET /v1/projects/{projectId}/slack/connections/{id}/channels` — standard tier, included with plans that carry the feature
- [Delete a Slack connection](https://docs.particle.pro/api-reference/slack-connections/delete-a-slack-connection): `DELETE /v1/projects/{projectId}/slack/connections/{id}` — standard tier, included with plans that carry the feature
### Embed

- [Get clip embed](https://docs.particle.pro/api-reference/embed/get-clip-embed): `GET /v1/embed/clips/{id}` — free, no credential needed
- [Get clip embed transcript](https://docs.particle.pro/api-reference/embed/get-clip-embed-transcript): `GET /v1/embed/clips/{id}/transcript` — free, no credential needed
- [Get episode embed code](https://docs.particle.pro/api-reference/embed/get-episode-embed-code): `GET /v1/embed/episodes/{episode_id}/code` — free, no credential needed
### Entity Charts

- [List entity charts](https://docs.particle.pro/api-reference/entity-charts/list-entity-charts): `GET /v1/podcasts/entities/charts` — standard tier, x402/MPP $0.10 per call
- [Get an entity chart](https://docs.particle.pro/api-reference/entity-charts/get-an-entity-chart): `GET /v1/podcasts/entities/charts/{category}` — standard tier, x402/MPP $0.10 per call
## MCP tools

Flat `particle_*` names; every public tool is callable by name even when `tools/list` did not advertise it. Default categories advertise on a bare connection; opt-in categories advertise with `?include=<category>` on the MCP URL. Each line: the documentation page, what the tool does, its tier, and the keyless x402/MPP price per `tools/call`. `initialize` and `tools/list` are free.

### system (always on)

- [`particle_call`](https://docs.particle.pro/mcp/tools/system/call): Dispatch any public Particle tool by name — free to call; a keyless call pays the dispatched tool's x402/MPP price; writes; destructive
- [`particle_catalog`](https://docs.particle.pro/mcp/tools/system/catalog): Browse the full Particle tool catalog — free
### podcasts (default)

- [`particle_podcast_find_mentions`](https://docs.particle.pro/mcp/tools/podcasts/podcast-find-mentions): Find dialogue lines where a specific person or company is named in podcast transcripts — standard tier, x402/MPP $0.04 per call
- [`particle_podcast_get_episode`](https://docs.particle.pro/mcp/tools/podcasts/podcast-get-episode): Return a bundled overview of one podcast episode: title, podcast, speakers (with entity slugs), top mentioned entities, and segment/clip counts — standard tier, x402/MPP $0.01 per call
- [`particle_podcast_get_episode_timeseries`](https://docs.particle.pro/mcp/tools/podcasts/podcast-get-episode-timeseries): Time-bucketed episode counts — the purpose-built answer to "how often is X discussed over time" — standard tier, x402/MPP $0.01 per call
- [`particle_podcast_list_clips`](https://docs.particle.pro/mcp/tools/podcasts/podcast-list-clips): Browse AI-extracted highlight clips across the catalog, ranked by engagement potential — the shareable moments — standard tier, x402/MPP $0.01 per call
- [`particle_podcast_list_episodes`](https://docs.particle.pro/mcp/tools/podcasts/podcast-list-episodes): List episodes across the catalog with rich filters: by podcast, person, company, language, date range, duration, or transcript availability — standard tier, x402/MPP $0.01 per call
- [`particle_podcast_list_related`](https://docs.particle.pro/mcp/tools/podcasts/podcast-list-related): List the shows most related to a podcast, best first — "shows like this show" — standard tier, x402/MPP $0.01 per call
- [`particle_podcast_list_related_episodes`](https://docs.particle.pro/mcp/tools/podcasts/podcast-list-related-episodes): Episodes from OTHER shows that cover the same story or subject as a given episode, best first — a live nearest-neighbour search over episode content, reranked on shared salient entities, shared topics and a shared news story — standard tier, x402/MPP $0.01 per call
- [`particle_podcast_resolve`](https://docs.particle.pro/mcp/tools/podcasts/podcast-resolve): Find a podcast by free-text title, exact slug, iTunes ID, or RSS feed URL — standard tier, x402/MPP $0.01 per call
- [`particle_podcast_search_transcripts`](https://docs.particle.pro/mcp/tools/podcasts/podcast-search-transcripts): Search the podcast catalog by what is said in episodes — by meaning (`semantic_search`), by exact phrase (`keyword_search`), or both at once (hybrid ranking) — standard tier, x402/MPP $0.04 per call
### people (default)

- [`particle_entity_get`](https://docs.particle.pro/mcp/tools/people/entity-get): One knowledge-graph entity's profile: name, kind, description, and Wikipedia link — standard tier, x402/MPP $0.01 per call
- [`particle_entity_resolve`](https://docs.particle.pro/mcp/tools/people/entity-resolve): Resolve any named thing — person, company, place, or other entity — by free-text name in one union search — standard tier, x402/MPP $0.01 per call
- [`particle_person_get`](https://docs.particle.pro/mcp/tools/people/person-get): Return a person's profile: name, current role, and bio, keyed by the canonical person slug from `particle_person_resolve` — standard tier, x402/MPP $0.01 per call
- [`particle_person_resolve`](https://docs.particle.pro/mcp/tools/people/person-resolve): Resolve a person by free-text name — standard tier, x402/MPP $0.01 per call
### companies (default)

- [`particle_company_get`](https://docs.particle.pro/mcp/tools/companies/company-get): Return a bundled profile for one company: identifiers (slug, ticker, domain, CIK, QID, linked entity), name, and description — standard tier, x402/MPP $0.01 per call
- [`particle_company_resolve`](https://docs.particle.pro/mcp/tools/companies/company-resolve): Resolve a company by free-text name, ticker, SEC CIK, Wikidata QID, or domain — standard tier, x402/MPP $0.01 per call
### topics (default)

- [`particle_topic_browse`](https://docs.particle.pro/mcp/tools/topics/topic-browse): Navigate the topic taxonomy — standard tier, x402/MPP $0.01 per call
### podcast_rankings (default)

- [`particle_podcast_get_rankings`](https://docs.particle.pro/mcp/tools/podcast_rankings/podcast-get-rankings): Podcast chart rankings from Apple Podcasts and Spotify, in four modes: — premium tier, x402/MPP $0.03 per call
### podcast_guests (default)

- [`particle_podcast_get_guest`](https://docs.particle.pro/mcp/tools/podcast_guests/podcast-get-guest): A guest's podcast-appearance profile: lifetime stats (appearances, distinct podcasts, first/last appearance) plus their most frequent podcasts — standard tier, x402/MPP $0.01 per call
- [`particle_podcast_list_guests`](https://docs.particle.pro/mcp/tools/podcast_guests/podcast-list-guests): Browse podcast guests across the catalog, in two opinionated modes: — standard tier, x402/MPP $0.01 per call
### podcast_advertising (opt-in: `?include=podcast_advertising`)

- [`particle_company_get_podcast_ad_presence`](https://docs.particle.pro/mcp/tools/podcast_advertising/company-get-podcast-ad-presence): Sponsor-side ad analytics for one company: total ads, distinct podcasts and episodes reached, host-read vs pre-recorded breakdown, and the most recent ad placements with podcast attribution — premium tier, x402/MPP $0.03 per call
- [`particle_podcast_get_ad_trends`](https://docs.particle.pro/mcp/tools/podcast_advertising/podcast-get-ad-trends): Podcast advertising momentum, in two modes: — premium tier, x402/MPP $0.04 per call
- [`particle_podcast_get_episode_ads`](https://docs.particle.pro/mcp/tools/podcast_advertising/podcast-get-episode-ads): Every detected ad read inside one episode: sponsor, advertised product, promotional offer, read type (host-read vs pre-recorded), placement (pre/mid/post-roll), and the exact start/end offsets in seconds — premium tier, x402/MPP $0.03 per call
- [`particle_podcast_get_sponsor_leaderboard`](https://docs.particle.pro/mcp/tools/podcast_advertising/podcast-get-sponsor-leaderboard): Ranked advertising leaderboards across the podcast catalog, in two modes: — premium tier, x402/MPP $0.04 per call
- [`particle_podcast_get_sponsors`](https://docs.particle.pro/mcp/tools/podcast_advertising/podcast-get-sponsors): Top sponsors for a single podcast plus aggregate ad stats: total ads, unique sponsors, episodes with ads, average ads per episode, and host-read vs pre-recorded breakdown — premium tier, x402/MPP $0.03 per call
### podcast_publishers (opt-in: `?include=podcast_publishers`)

- [`particle_podcast_get_publisher`](https://docs.particle.pro/mcp/tools/podcast_publishers/podcast-get-publisher): A podcast publisher's profile: name, slug, and catalog size — standard tier, x402/MPP $0.01 per call
### podcast_ratings (opt-in: `?include=podcast_ratings`)

- [`particle_podcast_get_ratings`](https://docs.particle.pro/mcp/tools/podcast_ratings/podcast-get-ratings): Listener-review ratings for one podcast: the aggregate summary (average stars, rating count, per-platform breakdown, and an LLM-generated sentiment narrative when available) plus the most recent individual reviews — standard tier, x402/MPP $0.01 per call
### podcast_bias (opt-in: `?include=podcast_bias`)

- [`particle_podcast_get_bias_leaderboard`](https://docs.particle.pro/mcp/tools/podcast_bias/podcast-get-bias-leaderboard): Rank podcast publishers by political-bias metrics across their analyzed catalogs: most left/right leaning (average lean score), most political (share of political shows), most diverse / most monolithic (lean spread), or most analyzed (coverage) — premium tier, x402/MPP $0.04 per call
- [`particle_podcast_list_bias_publishers`](https://docs.particle.pro/mcp/tools/podcast_bias/podcast-list-bias-publishers): Which publishers have the most podcasts in one political-bias bucket (e — premium tier, x402/MPP $0.03 per call
### podcast_suitability (opt-in: `?include=podcast_suitability`)

- [`particle_podcast_get_suitability_leaderboard`](https://docs.particle.pro/mcp/tools/podcast_suitability/podcast-get-suitability-leaderboard): Rank podcast publishers by IAB/GARM brand-suitability composition across their analyzed catalogs: safest (highest SAFE share), riskiest (highest UNSAFE share), most_placeable (highest SAFE+LIMITED share — the broadly buyable slice), or most_analyzed (coverage) — premium tier, x402/MPP $0.04 per call
- [`particle_podcast_list_suitability_category_publishers`](https://docs.particle.pro/mcp/tools/podcast_suitability/podcast-list-suitability-category-publishers): Which publishers' catalogs are most (or least) exposed to one IAB/GARM brand-safety category — e — premium tier, x402/MPP $0.04 per call
### alerts (default)

- [`particle_alert_create`](https://docs.particle.pro/mcp/tools/alerts/alert-create): Create an alert that watches a single entity and sets up recurring email delivery to external recipients whenever it is mentioned on a podcast episode (kind=ENTITY_MENTION) or appears as a speaker (kind=PODCAST_SPEAKER) — standard tier, included with plans that carry alerts; writes; destructive
- [`particle_alert_delete`](https://docs.particle.pro/mcp/tools/alerts/alert-delete): Delete an alert — standard tier, included with plans that carry alerts; writes; destructive
- [`particle_alert_get`](https://docs.particle.pro/mcp/tools/alerts/alert-get): Fetch a single alert's full configuration — title, kind, cadence, watched entities (with names), notification emails, and any active filters (languages, relevance, source_popularity, speaker_roles) — standard tier, included with plans that carry alerts
- [`particle_alert_list`](https://docs.particle.pro/mcp/tools/alerts/alert-list): List the alerts in your project, newest first — standard tier, included with plans that carry alerts
- [`particle_alert_list_matches`](https://docs.particle.pro/mcp/tools/alerts/alert-list-matches): List the matches an alert has caught, newest first — the payoff of an alert — standard tier, included with plans that carry alerts
- [`particle_alert_preview`](https://docs.particle.pro/mcp/tools/alerts/alert-preview): Preview how often an alert would fire BEFORE creating it — standard tier, included with plans that carry alerts
- [`particle_alert_update`](https://docs.particle.pro/mcp/tools/alerts/alert-update): Update an existing alert — standard tier, included with plans that carry alerts; writes; destructive
### radar (opt-in: `?include=radar`)

- [`particle_radar_render_cards`](https://docs.particle.pro/mcp/tools/radar/radar-render-cards): Display a small selection of Particle research results as embedded Radar cards — free
## Conventions

The defaults most endpoints share. Where an operation differs, its schema in the OpenAPI document is authoritative and each line above links to its page.

- **IDs and slugs.** Podcast, episode, publisher, company, person, entity, and topic `{id}` parameters accept the canonical id or the slug; podcast ids also accept a numeric Apple collection id, and company ids also accept a domain. Everything else (segments, clips, alerts, matches, deliveries, connections) takes the id a response returned. 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. Resolve free text first: `GET /v1/entities/search?q=` (each result carries `mentions.podcast_episodes`, the number of episodes tagged with it; a `company` result's id or domain goes in `company_id`), `GET /v1/podcasts/search?q=`, `GET /v1/companies?q=`; `GET /v1/entities` lists and filters and takes no `q`. Platform ids (Apple, Spotify, YouTube, RSS feed URLs, episode guids) resolve deterministically through `GET /v1/podcasts/lookup` and `GET /v1/podcasts/episodes/lookup`.
- **Optional parameters.** Omit what you do not need. A placeholder value (`x`, `-`, `__omit__`) is a real filter value and fails validation or matches nothing. Each concept has one parameter name; `q` is the free-text query wherever one exists.
- **Pagination.** List responses are `{data, has_more, cursor}`. Pass `cursor` back to continue; `limit` is usually 1 to 100 with a default of 25, and `cursor` is absent on the last page. Some lists cap lower (a company's advertised podcasts at 24) and some episode sub-resources (segments, speakers, entities, topics) return everything when `limit` is omitted. Cursors are opaque and specific to the endpoint that issued them.
- **Expansion.** Detail endpoints are lean; `include=` adds sections where the schema lists them (an episode's `segments`, `clips`, `transcript`, `topics`, `entities`; a company's `people`, `products`, `competitors`; a podcast's `related`).
- **Time.** Timestamps are ISO 8601 in UTC. Positions inside audio are decimal seconds (`start_seconds`, `end_seconds`). Date filters (`since`, `until`, `published_after`, `published_before`) usually accept a date or a timestamp, with a bare date covering the whole day; a few analytics endpoints, such as publisher bias, require a full timestamp, and their schema says so.
- **Language.** `language` is an ISO 639-1 code matched on the primary subtag, so `fr` covers `fr-CA`.
- **Rate limit.** 10,000 requests per minute per organization, shared across its keys and projects. `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` accompany rate-limited responses; a 429 (`rate_limit_exceeded`) carries `Retry-After`.
- **Errors.** RFC 9457 `application/problem+json` with a stable `error_code` and, when there is a self-service fix, a `resolve` object (`action`, `url`, `method`, `endpoint`). Catalog: https://docs.particle.pro/errors/overview.md
- **Retries.** Read `error_code` before retrying. A 429 carries `Retry-After`; wait that long. Back off exponentially on a 5xx. Never resend a 4xx unchanged: a 422 names the parameter or endpoint to fix, a 404 on a slug means resolve it again, and a 402 other than `payment_required` names a billing state that a retry cannot change.
- **Metering.** Each request, and each MCP `tools/call`, is one metered unit. `particle_catalog`, MCP `initialize` and `tools/list`, and the free endpoints above cost nothing. Every response carries `X-Trace-ID`; quote it when contacting support.
## Resources

- Agent setup playbook: https://api.particle.pro/agents.md
- Credential recipe for agents (auth.md): https://api.particle.pro/auth.md
- OpenAPI 3.1 document: https://api.particle.pro/openapi.json
- MPP discovery: https://api.particle.pro/openapi.json (REST) and https://mcp.particle.pro/openapi.json (MCP when MPP is enabled). Read x-service-info and x-payment-info.offers; amount=null means the runtime challenge supplies the price.
- x402 manifest and endpoint list: https://api.particle.pro/.well-known/x402 and https://api.particle.pro/.well-known/x402.json
- Documentation: https://docs.particle.pro (append `.md` to any page for raw markdown; index at https://docs.particle.pro/llms.txt; full corpus at https://docs.particle.pro/llms-full.txt)
- Changelogs: https://docs.particle.pro/changelog.md (REST) and https://docs.particle.pro/mcp/changelog.md (MCP)
- Status: https://status.particle.pro. Support: api@particle.pro