Perplexity Agent API Citations: Normalize the Source Contract Before Migrating
Normalize numbered and source-typed Agent API citations into one internal source contract before migrating from legacy Sonar or MCP-backed workflows.
Published August 9, 2026: Perplexity’s Agent API research presets now emit inline citations with different forms. The fast preset uses numbered citations such as [1]; low, medium, and high use source-typed forms such as [web:1] for claims grounded in tool results or supplied source artifacts.
A migration that stores the rendered answer but assumes every marker is a plain integer can lose the source type, break link resolution, or misattribute tool evidence. The durable fix is to normalize citations at the API boundary and keep display formatting separate from the source ledger.
What changed in the Agent API
Perplexity’s July 2026 changelog says search-backed presets include inline citations. After a successful tool call, the low, medium, and high presets include at least one citation in the final answer. The changelog also says MCP Server 1.0 moved its model-backed tools from legacy Sonar models to Agent API presets while retaining tool names and response shapes.
Those two facts create different migration surfaces. Existing MCP clients may continue to receive familiar tool responses, while direct Agent API consumers must handle the preset’s citation grammar and source artifacts. Removed parameters such as strip_thinking and reasoning_effort are ignored by the updated MCP tools; they should still be removed from owned schemas rather than left as misleading configuration.
Define an internal source contract
| Field | Purpose | Example |
|---|---|---|
| provider | API that produced the citation | perplexity |
| source_type | Web, tool, supplied artifact, or unknown | web |
| source_index | Provider-local position | 1 |
| url | Resolved canonical source when available | https://example.com/source |
| title | Human-readable source label | Source title |
| claim_span | Answer text supported by the marker | Character or node range |
| raw_marker | Original provider notation | [web:1] |
Do not use the rendered marker as the database key. [1] and [web:1] can refer to different namespaces, and a future source type may introduce another form. Preserve the raw response and response version for debugging.
Build migration fixtures before switching traffic
- Capture representative legacy responses and Agent API responses.
- Include fast, low, medium, and high presets.
- Test zero tools, one successful tool, multiple tools, and tool failure.
- Include repeated source indices across different types.
- Resolve markers to source cards and reject missing references.
- Render accessible links without changing the stored contract.
- Compare citation count, source count, unresolved markers, and answer text.
A citation’s presence proves that the response associates a claim with a source artifact under that run. It does not prove source quality, factual correctness, or a stable consumer-search ranking. Apply the citation-ready passage test and open the cited source during evaluation.
Release and monitoring checks
Run the old and new paths in parallel for a bounded sample. Log parser failures, unresolved citations, source-type distribution, duplicated URLs, missing titles, and answer-to-source mismatches. Do not compare only average citation counts; a parser that duplicates markers can look like an improvement.
Version the adapter by provider and API contract. Keep application code dependent on the normalized object, not on Perplexity-specific bracket syntax. This also makes changes such as You.com’s removal of the authors field easier to contain within one adapter.
After the cutover, retain replayable fixtures and a rollback path. Changelog monitoring should have an owner because presets and schemas can change independently of the application release.
Ask a question or join the discussion