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

# AGENTS

# Instructions for Coding Agents

This file provides guidance to coding agents working in this repository (`ppl-ai/api-docs` on GitHub).

## Agent Instruction Files

This repo uses `AGENTS.md` as the canonical agent instruction file. `CLAUDE.md` exists only as a compatibility alias for tooling that expects that filename.

* `AGENTS.md` is always the canonical source of truth for all coding agents.
* `CLAUDE.md` is a symlink to the sibling `AGENTS.md`; it must never carry instructions absent from it, and `AGENTS.md` must never be a symlink to `CLAUDE.md`.
* Skills are authored once under `.agents/skills/<name>/SKILL.md` (agent-agnostic, canonical). The `.claude/skills/<name>` entries are thin symlinks back to that tree — edit the `.agents/skills/` copy, never the symlink.

## What this is

The Perplexity API documentation site, built with [Mintlify](https://mintlify.com). Content is MDX with YAML frontmatter; there is almost no application code. The work is writing/editing docs pages, maintaining navigation, and keeping embedded code examples runnable.

## Skills — load these first

This repo ships project skills that contain the detailed working agreement. Load them before doing real work; they go deeper than this file:

* **`mintlify`** — technical reference: components, page patterns, design system (colors/typography), navigation structure, project conventions.
* **`mintlify-docs-rules`** — voice/writing standards, frontmatter requirements, git workflow, prohibitions.
* **`perplexity-api-platform`** — API/SDK reference for getting code examples correct (Gateway, Agent, Search, Sonar, Embeddings; always list APIs in this sidebar order). Has detailed references under `.agents/skills/perplexity-api-platform/references/`.

## Commands

```bash theme={null}
nvm use                    # Node 20 (pinned in .nvmrc; engine-strict blocks other versions)
pnpm install               # install dependencies
pnpm dev                   # Local preview (mintlify dev) at localhost:3000
pnpm build                 # mintlify build
pnpm generate-cookbook-nav  # Regenerate cookbook nav into config/navigation.json from docs/cookbook/
pnpm generate-cookbook-data # Regenerate the cookbook gallery data (snippets/cookbookData.jsx) from recipe frontmatter
pnpm check-cookbook-data    # Validate recipe tags (products required) + assert the data is fresh; writes nothing (CI/pre-commit gate)
pnpm sync-cookbook          # Run both cookbook generators (nav + gallery data)

# Code-example tests (these gate CI)
pnpm check                                                   # static checks on all docs (= sh scripts/check-examples.sh)
sh scripts/check-examples.sh --staged                        # static checks on staged docs/**/*.mdx only
python scripts/test_code_examples.py                         # Python syntax check (all docs)
python scripts/test_code_examples.py --live                  # run Python blocks against live API (needs PERPLEXITY_API_KEY)
python scripts/test_code_examples.py --file docs/sonar/quickstart.mdx   # single file
python scripts/test_code_examples.py --live --changed-blocks changed-code-blocks.txt # selected path:line blocks
node scripts/check_ts_examples.js                            # TypeScript type-check (all docs)
node scripts/check_ts_examples.js --live                     # run TS blocks live
node scripts/check_ts_examples.js --file docs/sonar/quickstart.mdx      # single file
python scripts/check_curl_examples.py                        # Bash syntax-check Perplexity API cURL blocks
python scripts/check_curl_examples.py --live                 # run cURL blocks live
python scripts/check_curl_examples.py --file docs/sonar/quickstart.mdx  # single file
```

Package manager is **pnpm** (`pnpm@10.32.1`). Mintlify's own CLI also offers `mint broken-links`, `mint validate`, and `mint rename` (use `mint rename` to move pages so references update).

## Code-example testing (important)

CI (`.github/workflows/test-examples.yml`) extracts fenced ` ```python `, ` ```typescript `, and Perplexity API cURL blocks from `docs/**/*.mdx` and tests them. Understand the mechanics so your examples actually pass:

* **Only recognized API examples are tested.** Python: `from perplexity` / `import perplexity` / `from openai` / `pplx_srch_sdk` (plus the legacy `pplx_sdk` import). TypeScript: `@perplexity-ai/perplexity_ai` or `openai`. cURL: Bash-family fences containing `curl` and an `https://api.perplexity.ai` URL. Other blocks are skipped.
* **Static checks** (Python `ast.parse`, TS type-check, cURL Bash syntax) run over the full docs corpus on every push/PR. **Live execution** runs the full corpus on pushes to `main` or manual `workflow_dispatch`; on same-repository PRs, it runs only newly added or changed code blocks. A prose-only PR runs no live jobs, and fork PRs cannot access the API secret so remain static-only. cURL live checks treat HTTP 4xx/5xx responses as failures.
* cURL blocks that create or revoke API keys, require placeholder response/file/sequence ids, or call the limited-preview Gateway API are syntax-checked but automatically skipped in live mode. Use `ci:skip-live` for other examples that are not safe or independently runnable.
* Install/env blocks (`pip install`, `npm install`, `export PERPLEXITY...`) are auto-skipped.
* Placeholder keys (`"YOUR_API_KEY"`, `"pplx-KEY"`) are auto-rewritten to read `PERPLEXITY_API_KEY` from env during live runs — so write examples with those placeholders, not real keys.
* To exclude a file or glob from testing, add it to **`.ci-test-skip`** (fnmatch patterns relative to repo root, e.g. `docs/cookbook/**`).
* **Per-block CI markers** — put an MDX comment on the line immediately before a fence to control that one block's live run (it is still statically checked):
  * `{/* ci:skip-live */}` — don't execute this block in `--live` mode. Last resort for examples that legitimately can't run standalone (placeholder ids, an SDK feature newer than the pinned version, or runs that may hang).
  * `{/* ci:timeout=<seconds> */}` — raise the live timeout for a correct-but-slow block (default 180s, max 600s). Use only when the example reliably completes; prefer a real fix first.
    The default per-block live timeout is **180s** and is symmetric across all three runners.

**`scripts/check-examples.sh`** is the deterministic entry point for these static checks (no `--live`) — same invocation for humans, CI, and Teammate, with no install step. Run `pnpm check` (all docs) or `sh scripts/check-examples.sh --staged` (staged `docs/**/*.mdx` only). An optional native git hook at **`.githooks/pre-commit`** runs the `--staged` check on commit; opt in once with `git config core.hooksPath .githooks` (no dependency, no `prepare`-script magic).

## Architecture / layout

* **`docs.json`** — site config (almond theme, GT Standard fonts, colors). Navigation and redirects are `$ref`'d out to `config/navigation.json` and `config/redirects.json` — edit those files, not inline.
* **`config/navigation.json`** — three tabs: **Docs**, **Cookbook**, **API Reference**. Structure is Tabs → Groups → nested Groups (max 2 levels of nesting per tab). New pages must be added here.
* **`docs/`** — the content, by API/area: `getting-started/`, `gateway/`, `agent-api/`, `search/`, `sonar/`, `embeddings/`, `sdk/`, `admin/`, `resources/`, `features/`, `cookbook/`. Images live in `docs/assets/images/`.
* **`api-reference/`** — endpoint pages backed by `openapi.json` (and `openapi-auth.json`). Regenerated from the OpenAPI spec, not hand-written prose.
* **`snippets/`** — reusable components imported into pages (`.jsx` for interactive, `.mdx` for content).
* **`styles.css`** — Figma-derived custom design system (custom callout colors, content width override). Theme-aware colors use CSS custom properties.
* **`scripts/`** — cookbook sync (`generate-cookbook-nav.js`, `generate-cookbook-data.js`, `process-cookbook.js`, `update-docs-json.js`) and the example test runners above.

### Cookbook is synced content

`docs/cookbook/` is synced from the external `api-cookbook` repository but committed here for reproducible builds. After changing cookbook files, run `pnpm generate-cookbook-nav` to rebuild its navigation in `config/navigation.json`. Cookbook code examples are excluded from CI testing (`docs/cookbook/**` in `.ci-test-skip`).

The cookbook gallery landing (`/docs/cookbook`) is driven by `snippets/cookbookData.jsx` — a generated module (recipes + facets + labels) consumed by `snippets/CookbookGallery.jsx`. It is built from each recipe's `products`/`categories` frontmatter tags by `pnpm generate-cookbook-data`; run it (or `pnpm sync-cookbook` for nav + data together) after editing those tags. The controlled vocabulary lives in `scripts/generate-cookbook-data.js`: `products` is **required** (≥1 value), `categories` is optional, and any out-of-vocab tag fails the build. `pnpm check-cookbook-data` (the `--check` flag) validates tags and asserts the committed data is fresh without writing — it gates CI (a dedicated `cookbook` workflow that checks out full git history) and the opt-in pre-commit hook. The data file must stay `.jsx` (not `.js`) — Mintlify loads a loose `.js` import as a classic script, so its `export` would be a syntax error.

### Redirects caution

This project has accumulated extensive redirects from past renames (`grounded-llm` → `agentic-research` → `agent-api`). When moving/renaming a page, add a redirect to `config/redirects.json` and **check for existing chains first** to avoid redirect-to-redirect hops.

## Conventions that bite if missed

* Every code feature shows **Python, TypeScript, cURL** in that order, in a `<CodeGroup>` with labels exactly `Python`, `Typescript`, `cURL`.
* cURL examples use `$PERPLEXITY_API_KEY` and pipe through `| jq`. SDK examples rely on the auto-detected env var (no key in the constructor).
* Internal links are root-relative without extension (`/docs/getting-started/quickstart`) — never absolute URLs.
* No H1 in body (frontmatter `title` is the H1); start sections at `##`.
* `title` and `description` frontmatter are required on every MDX page.
* SDK method mapping: Agent API → `client.responses.create()`, Search → `client.search.create()`, Sonar → `client.chat.completions.create()`. The Gateway API does not use the Perplexity SDK — it uses the **OpenAI SDK** (`client.chat.completions.create()`) with `base_url="https://api.perplexity.ai/router/v1"`, or the Anthropic SDK (`base_url=".../router"` without `/v1` since the SDK appends `/v1/messages`; stock `api_key` auth works) for `/messages`. Gateway examples importing `openai` are CI-tested, statically on PRs and live on pushes to main — write them to run standalone.