◎ Discry Score
contentful.com
cms · API
D
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 96 (A)
Discry your API →
CMS · RANK #11 OF 13

Contentful is Poor to agents.

Discry independently scored how well an AI agent can discover and understand the Contentful 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 · 29/100
OpenAPI specA machine-readable OpenAPI/Swagger spec agents can parse.Fail
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.Pass

Comprehension

55% of score · 72/100
Task-oriented descriptionsEndpoints described by what they accomplish, not just their shape.Pass
Realistic examplesRunnable, real-world request/response examples.Partial
Multi-step workflowsDocs that chain calls into complete jobs an agent can follow.Partial
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.Fail

What we found

  • Contentful has zero agent discovery infrastructure: no llms.txt, no OpenAPI spec, no .well-known/mcp.json, no AGENTS.md — despite being an API-first CMS platform that should be maximally accessible to agents
  • Rate limit documentation is well-implemented with specific numbers (55 req/s), response headers (X-Contentful-RateLimit-Reset, X-Contentful-RateLimit-Second-Limit), and clear recovery guidance — agents can self-throttle effectively
  • The API reference documentation is well-structured with nested sections but requires navigating 5+ separate API references (CDA, CMA, Preview, Images, GraphQL) with no unified summary or orientation layer
  • An official Contentful MCP server exists and is listed on PulseMCP and Glama, but there's no .well-known/mcp.json to connect it to the documentation domain
  • Documentation is only available as HTML — no markdown mirrors, no content negotiation, no llms-full.txt — an agent must scrape and convert pages

What to change

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

  1. 01Add llms.txt at contentful.com/llms.txt with structured links covering all 5 APIs (CDA, CMA, Preview, Images, GraphQL) — this single file would dramatically improve agent orientation
  2. 02Publish OpenAPI specs for the REST APIs (CDA and CMA) — as an API-first platform, this should be a priority
  3. 03Add .well-known/mcp.json pointing to the official contentful-mcp-server with tool declarations
  4. 04Create a unified API overview page that summarizes all 5 APIs in <5000 tokens for quick agent orientation (currently requires navigating many pages)
  5. 05Add AGENTS.md to the contentful/contentful.js and contentful/contentful-management.js repos with SDK integration context for coding agents

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.

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

OAuth2 bearer tokens and API keys (CDA tokens, CMA tokens). Rate limit of 55 requests/second for CDA (higher on paid plans). X-Contentful-RateLimit-* headers provided. 429 responses with X-Contentful-RateLimit-Reset header. Collection pagination with skip/limit and cursor-based pagination. JSON error responses with sys.type: 'Error'. Multiple APIs: Content Delivery, Content Management, Preview, Images, GraphQL.

See your own Discry Score.

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

Discry your API — free