> ## Documentation Index
> Fetch the complete documentation index at: https://docs.particle.pro/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={"dark"}
# 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](/companies/overview#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`](/podcasts/lookup).

## Cursor pagination

List endpoints share a single response envelope:

```json theme={"dark"}
{
  "data": [ /* … */ ],
  "has_more": true,
  "cursor": "r.4gfFC7"
}
```

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

```bash theme={"dark"}
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.

```bash theme={"dark"}
# 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](/quickstart) walks through several of these patterns end-to-end.

## Errors

Errors follow [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) (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](/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`](/errors/rate_limit_exceeded).