> ## 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.
# Introduction
> Particle API reference — base URL, authentication, and machine-readable specs.
export const DashboardLink = ({children}) => {
return {children};
};
## Base URL
All API endpoints are served from:
```
https://api.particle.pro
```
## Authentication
Every endpoint that returns user data requires an API key. Two header forms are accepted; `X-API-Key` is recommended.
### `X-API-Key` header (recommended)
```bash theme={"dark"}
curl https://api.particle.pro/v1/podcasts \
-H "X-API-Key: $PARTICLE_API_KEY"
```
### `Authorization: Bearer` header
Equivalent in every way; useful when you're routing through middleware that already understands bearer tokens.
```bash theme={"dark"}
curl https://api.particle.pro/v1/podcasts \
-H "Authorization: Bearer $PARTICLE_API_KEY"
```
The `/v1/embed/*` endpoints are public and intentionally do not require authentication.
## Get an API key
1. Sign up or log in at the API Dashboard
2. Create an organization and project
3. Open the project's **API Keys** section
4. Click **Create API Key** and copy the key — it won't be shown again
## Machine-readable resources
For automated integrations and AI-assisted development:
| Resource | URL | Use it for |
| --------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OpenAPI document | [`api.particle.pro/openapi.json`](https://api.particle.pro/openapi.json) | Code generation, schema validation, contract testing. Every payable operation carries its x402 payment terms. |
| Endpoint and tool map | [`api.particle.pro/llms.txt`](https://api.particle.pro/llms.txt) | Every public endpoint and MCP tool with its documentation page and per-call price, plus the conventions below, in one file an agent can read before its first call. |
| Agent setup playbook | [`api.particle.pro/agents.md`](https://api.particle.pro/agents.md) | Connecting a client over MCP, the REST API, or x402 and running a first query. Also the [Agent onboarding](/agents) page. |
| Credential recipe | [`api.particle.pro/auth.md`](https://api.particle.pro/auth.md) | How an agent obtains and uses a credential, or pays per request. Also the [Agent authentication](/auth) page. |
| x402 manifest | [`api.particle.pro/.well-known/x402`](https://api.particle.pro/.well-known/x402) | The payable endpoints and payment terms for keyless agents. |
| Docs page index | [`docs.particle.pro/llms.txt`](https://docs.particle.pro/llms.txt) | Every documentation page with its description. Append `.md` to any page URL for raw markdown. |
| Full docs corpus | [`docs.particle.pro/llms-full.txt`](https://docs.particle.pro/llms-full.txt) | Every guide inlined as one file for deep retrieval. |
The playbook, the map, and the credential recipe are served at the root of `mcp.particle.pro` too. The OpenAPI document is generated from the server source on every release and the endpoint reference that follows is rendered from it; it is the authoritative reference for endpoint structure. For individual field semantics, defer to the live API response when the two disagree.
## Client libraries
Generate a typed client in any language from the OpenAPI document (`curl -fsS https://api.particle.pro/openapi.json -o particle-openapi.json`) with [openapi-generator](https://openapi-generator.tech), [Stainless](https://www.stainless.com), or your stack's equivalent; the [quickstart](/quickstart) shows every call with `curl`, `fetch`, and `httpx` directly. Agents get a ready-made client over [MCP](/mcp/overview). Keyless agents paying per request use the x402 client libraries listed on [Pay per request with x402](/x402).
## Conventions
The defaults most endpoints share; where an operation differs, its schema in the reference below is authoritative. [Concepts](/concepts) expands on each.
| Convention | Rule |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Identifiers | Podcast, episode, publisher, company, person, entity, and topic `{id}` parameters accept the canonical id or the slug; everything else (segments, clips, alerts, matches, deliveries, connections) takes the id a response returned. Podcast ids also accept a numeric Apple collection id; company ids also accept a domain. 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 with `GET /v1/entities/search?q=`, `GET /v1/podcasts/search?q=`, and `GET /v1/companies?q=`; resolve platform ids (Apple, Spotify, YouTube, RSS feed URLs, episode guids) with `GET /v1/podcasts/lookup` and `GET /v1/podcasts/episodes/lookup`. |
| Optional parameters | Omit a parameter you do not need. A placeholder value (`x`, `-`, `__omit__`) is a real filter value and either fails validation or matches nothing. Each concept has one parameter name; `q` is the free-text query wherever one exists. |
| 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. See [Handle errors and retries](/recipes/handle-errors). |
| 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 return everything when `limit` is omitted. Cursors are opaque and specific to the endpoint that issued them. |
| Expansion | Detail responses are lean; `include=` adds sections (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: `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. A missing, mistyped, revoked, or expired key returns `401 api_key_required`. See the [error catalog](/errors/overview). |
| Metering | Each request is one metered unit; the free endpoints (`/v1/podcasts/stats`, `/v1/embed/*`) cost nothing. Every response carries `X-Trace-ID`; quote it when contacting support. |
| Compatibility | The API grows additively under `/v1`: new fields, parameters, and endpoints never break an existing call. Breaking changes are announced ahead of time in the [changelog](/changelog). |