◎ Discry Score
perplexity.com
ai · API
A
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 99 (A)
Discry your API →
AI · RANK #17 OF 43

Perplexity is Agent-Ready to agents.

Discry independently scored how well an AI agent can discover and understand the Perplexity API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.

Discry your API — freeView the docs ↗

SCORED UNDER RUBRIC 1.2 · A full re-launch under Discry Score 2.5 — a new behavioral instrument, not comparable to these scores — is in progress.

Discovery

45% of score · 83/100
OpenAPI specA machine-readable OpenAPI/Swagger spec agents can parse.Pass
llms.txtAn llms.txt index that points agents to the docs that matter.Pass
llms.txt qualityThe llms.txt is focused, current, and well under the size budget.Pass
llms-full.txtA full-text bundle agents can load in one request.Pass
AGENTS.mdAn AGENTS.md that tells coding agents how to build on the API.Fail
.well-known/mcp.jsonA discoverable MCP manifest at a well-known path.Partial
MCP registryThe API is listed in a public MCP registry.Pass
robots.txt AI directivesrobots.txt allows (or explicitly guides) AI crawlers.Pass
SitemapA sitemap so agents can enumerate the docs surface.Pass

Comprehension

55% of score · 100/100
Task-oriented descriptionsEndpoints described by what they accomplish, not just their shape.Pass
Realistic examplesRunnable, real-world request/response examples.Pass
Multi-step workflowsDocs that chain calls into complete jobs an agent can follow.Pass
Error-recovery guidanceDocumented failure modes and how to recover from them.Pass
Answer-first formatThe answer leads; preamble does not bury it.Pass
Capability boundariesClear limits — what the API can and cannot do.Pass
Naming consistencyConsistent, predictable naming across endpoints.Pass
Heading hierarchyClean heading structure agents can navigate.Pass
Markdown docsDocs available as clean markdown, not JS-rendered HTML only.Pass
Token efficiencyDocs are concise enough to fit an agent context window.Pass

What we found

  • An agent discovering Perplexity lands on a best-in-class footprint: a clean API-focused llms.txt, a 3.6MB llms-full.txt, every doc page available as raw .md, an official OpenAPI 3.1 spec at /openapi.json, and a hosted Docs MCP server. Discovery is nearly frictionless.
  • robots.txt uses the newer Content-Signal directive explicitly granting ai-train=yes, search=yes, and ai-input=yes — Perplexity actively invites agent/AI consumption rather than merely tolerating it.
  • Documentation is genuinely agent-usable: task-oriented endpoint descriptions, multi-language copy-pasteable examples (Python/TypeScript/curl), and — rare — explicit error-recovery guidance (429 -> exponential backoff + jitter, 5xx -> retry + log X-Request-ID, dedicated SDK error-handling guide). An agent hitting an error is told what to DO, not just the code.
  • The one real discovery gap: no AGENTS.md exists in any perplexityai GitHub repo (api-cookbook, search_evals), so a coding agent cloning their cookbook gets no agent-specific orientation file.
  • .well-known/mcp.json resolves to a live hosted Docs MCP server (auth=none) but only as a server pointer without inline tool declarations — functional for discovery, minimal for introspection.

What to change

Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.

  1. 01Add an AGENTS.md to flagship repos (api-cookbook, search_evals). This is the quickest remaining discovery win and would push the discovery dimension toward an A.
  2. 02Enrich .well-known/mcp.json with inline tool declarations and explicit auth metadata so agents can introspect capabilities without a round-trip to the server endpoint.
  3. 03Document idempotency keys for the agent/chat write endpoints so agents can safely retry on transient failures without risking duplicate side effects.
  4. 04Keep the /openapi.json spec in lockstep with the docs and link to it prominently from the API reference — it is present and high quality, and it should be promoted as the canonical machine-readable contract.

Execution coverage · INFORMATIONAL, UNSCORED

Whether an agent can actually complete a call and recover from errors is the deeper Audit layer — documented here, but not part of the Discry Score.

Bearer API keyOrg-scoped analytics API key✓ Error format documented✓ Rate limits documented✓ Pagination documented✕ Idempotency documented

Execution characteristics are documented well. Auth is Bearer API key (with programmatic token generate/revoke endpoints and a separate org-scoped analytics key). Errors are documented with HTTP status codes and an HTTPValidationError schema in the OpenAPI spec. Rate limits use a leaky-bucket model tied to usage tiers, with the X-Request-ID header called out for support. Cursor-based pagination (next_page/has_more) is documented for analytics endpoints. No idempotency-key mechanism is documented.

See your own Discry Score.

Drop your API docs URL. See what an agent sees — in 60 seconds, free.

Discry your API — free