◎ Discry Score
klaviyo.com
communication · API
C
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 98 (A)
Discry your API →
COMMUNICATION · RANK #17 OF 24

Klaviyo is Needs Work to agents.

Discry independently scored how well an AI agent can discover and understand the Klaviyo 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 · 43/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.Fail
llms.txt qualityThe llms.txt is focused, current, and well under the size budget.Fail
llms-full.txtA full-text bundle agents can load in one request.Fail
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.Fail
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.Fail

Comprehension

55% of score · 90/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.Partial
Token efficiencyDocs are concise enough to fit an agent context window.Partial

What we found

  • An agent that reaches Klaviyo's docs finds near-reference-grade comprehension: task-oriented endpoint summaries, copy-pasteable examples in five languages (cURL/Node/Ruby/PHP/Python), a full status-code table, and explicit retry guidance (exponential backoff + jitter, honor Retry-After).
  • Discovery infrastructure is the weak spot — an agent probing standard paths gets 404s for llms.txt and sitemap.xml, and soft-404 homepage HTML for llms-full.txt and .well-known/mcp.json, so there is no machine-readable entry point that summarizes the API.
  • The single strongest discovery signal is a first-class, versioned OpenAPI spec published on GitHub (github.com/klaviyo/openapi) with downloadable JSON, per-category and per-endpoint slices — the same source that powers the docs and SDKs.
  • Klaviyo ships an official remote + local MCP server (documented at developers.klaviyo.com/en/docs/klaviyo_mcp_server) and is surfaced across MCP registries, so an agent searching for a Klaviyo tool integration will find a maintained one.
  • robots.txt allows all crawlers (including AI bots), but no AGENTS.md exists in the primary API/SDK repos, leaving coding agents without repo-level guidance.

What to change

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

  1. 01Publish an llms.txt at developers.klaviyo.com/llms.txt with a titled, API-focused summary and links to the overview, auth, rate-limits, and top endpoint pages — the highest-leverage quick win, currently a 404.
  2. 02Return a real 404 (or serve the actual files) for /llms-full.txt and /.well-known/mcp.json instead of soft-404 homepage HTML, and add an llms-full.txt with concatenated markdown of the core guides.
  3. 03Expose a sitemap.xml at the docs root that lists reference and guide pages so crawlers and agents can enumerate documentation coverage (currently 404).
  4. 04Add an AGENTS.md to the primary API/SDK repos (klaviyo/openapi and the language SDKs) with build/test/usage context for coding agents.
  5. 05Document idempotency-key support (or explicitly state its absence) so agents can safely retry write operations after network failures.

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.

private_keyoauth2public_key✓ Error format documented✓ Rate limits documented✓ Pagination documented✕ Idempotency documented

Execution characteristics are thoroughly documented: three auth methods (private key, OAuth for server-side, public key for client-side), a JSON:API error envelope with id/status/code/title/detail/source fields, tiered rate limits (XS-XL burst/steady windows) with RateLimit-* and Retry-After headers, and cursor-based pagination. Idempotency keys are not documented.

See your own Discry Score.

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

Discry your API — free