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

## Instructions for LLM agents

These conventions are load-bearing, and a page index alone hides them:

- **Pick the right surface.** Building an agent loop (Claude Code, Cursor, ChatGPT, 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.
- **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.
- **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 person or company — 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. `particle_podcast_list_episodes` is filter-driven episode discovery (podcast, person, company, language, date, duration).
- **Discovery is free; execution is metered.** 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`). 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`), or fetch the entire corpus from `llms-full.txt` (linked under Optional below).

## MCP server

- [MCP overview](https://docs.particle.pro/mcp/overview.md): Endpoint, one-click and manual client setup, what's in the box, MCP vs REST
- [MCP quickstart](https://docs.particle.pro/mcp/quickstart.md): Per-client install (Claude Code, Claude Desktop, Cursor, VS Code, ChatGPT) and a sanity-check call
- [Tool sets & discovery](https://docs.particle.pro/mcp/tool-sets.md): Exposure categories, the `?include=`/`?exclude=` selectors, and the always-callable contract
- [Tool reference](https://docs.particle.pro/mcp/tools/overview.md): Every tool grouped by category, each linking to a per-tool page with inputs, output shape, and examples
- [Authentication](https://docs.particle.pro/mcp/authentication.md): OAuth 2.1 end-to-end — discovery, dynamic client registration, PKCE, refresh, revocation, connection management
- [Agent authentication (auth.md)](https://docs.particle.pro/auth.md): The agent-onboarding recipe — two-hop discovery, credential decision tree, registration, and revocation; also served at https://api.particle.pro/auth.md and https://mcp.particle.pro/auth.md
- [MCP errors](https://docs.particle.pro/mcp/errors.md): The three failure layers (HTTP 401, HTTP problem+json, tool `isError`) and how agents should react

## REST API

- [Welcome](https://docs.particle.pro/index.md): What Particle API covers and where to start
- [Quickstart](https://docs.particle.pro/quickstart.md): API keys and first REST calls
- [Concepts](https://docs.particle.pro/concepts.md): Core domain objects and the identifiers that connect them
- [API reference introduction](https://docs.particle.pro/api-reference/introduction.md): Base URL, auth headers, and the OpenAPI-driven endpoint reference
- [Errors](https://docs.particle.pro/errors/overview.md): RFC 9457 problem details, the `error_code` catalog, and structured `resolve` guidance

## Guides

- [Podcasts](https://docs.particle.pro/podcasts/overview.md): Episodes, transcripts, search, segments and clips, mentions, guests, rankings, ratings, advertising, bias, and suitability
- [Companies](https://docs.particle.pro/companies/overview.md): Company profiles, identifiers, and product hierarchies
- [Knowledge graph entities](https://docs.particle.pro/knowledge-graph/entities.md): People, organizations, and places behind the slugs
- [Topics](https://docs.particle.pro/knowledge-graph/topics.md): The hierarchical topic taxonomy

## Optional

- [Full documentation corpus](https://docs.particle.pro/llms-full.txt): Every documentation page inlined as one markdown file
- [OpenAPI specification](https://docs.particle.pro/openapi.json): Machine-readable REST schema