◎ Discry Score
bigcommerce.com
commerce · API
B
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 95 (A)
Discry your API →
COMMERCE · RANK #5 OF 21

BigCommerce is Good to agents.

Discry independently scored how well an AI agent can discover and understand the BigCommerce 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 · 71/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.Partial
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 · 88/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.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.Partial

What we found

  • BigCommerce is notably agent-aware: docs include a banner for AI agents pointing to /llms.txt and .md page variants, showing deliberate investment in agent discoverability
  • The developer llms.txt at ~350KB far exceeds the ideal 50KB threshold, making it impractical for single-context-window agent consumption despite being well-structured
  • OpenAPI specs are publicly maintained on GitHub (bigcommerce/api-specs) in OAS 3+ format, making programmatic API discovery straightforward
  • Rate limit documentation includes actionable recovery guidance with code examples and specific header names, enabling agents to self-correct on 429 errors
  • Third-party MCP servers exist on Glama and PulseMCP, but BigCommerce has no official MCP server or .well-known/mcp.json

What to change

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

  1. 01Create a focused llms.txt under 50KB covering core API capabilities (catalog, orders, customers) — the current 350KB developer file is too large for agent context windows
  2. 02Add llms-full.txt as the comprehensive version, keeping llms.txt as the concise index
  3. 03Publish .well-known/mcp.json pointing to an official or recommended MCP server
  4. 04Add AGENTS.md to the bigcommerce/api-specs GitHub repository with context for coding agents building integrations
  5. 05Replace placeholder values ({{TOKEN}}, {{STORE_HASH}}) in code examples with realistic-looking sample values to improve agent copy-paste reliability

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.

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

OAuth-based API accounts with store-level, app-level, and account-level credentials. Rate limits documented per plan (150-450 requests per 30-second window) with specific header names. JSON error responses. Cursor and page-based pagination documented. No idempotency key support documented.

See your own Discry Score.

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

Discry your API — free