instacart is Needs Work to agents.
Discry independently scored how well an AI agent can discover and understand the instacart API from what’s public — not whether it’s usable. Below: every signal we checked, what’s costing the score, and what to change.
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 · 40/100Comprehension
55% of score · 84/100What we found
- Instacart runs its own official, documented MCP server (mcp.instacart.com/mcp) with a dedicated tutorial exposing create-recipe and create-shopping-list tools — an agent can connect and act without writing any direct API integration, which is a top-tier agent-readiness signal.
- Every documentation page ships a clean .md twin (e.g. /api/overview.md), giving agents lossless markdown for LLM consumption without needing to scrape JS-rendered HTML.
- Error handling is unusually agent-friendly: a machine-parseable JSON error schema returns an error code plus a meta.key that names the exact bad parameter, and each error row prescribes a corrective action ('Ensure the access token is valid, then retry') — an agent can self-correct rather than guess.
- Discovery is the weak dimension: no publicly downloadable OpenAPI spec (the API is partner-gated behind a 30-40 day approval), no AGENTS.md, no llms-full.txt, and no .well-known/mcp.json — an agent cannot machine-load the surface, only read prose.
- The primary www.instacart.com domain hard-blocks every crawler (User-Agent: * / Disallow: /, plus explicit Meta-AI blocks); only the docs subdomain is open, so an agent discovering Instacart via its brand homepage hits a wall.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Publish a downloadable OpenAPI 3.x spec (and/or Postman collection) at a stable, un-gated docs URL — this is the single highest-impact discovery fix (weight 5) and would let agents generate typed clients instead of hand-reading endpoint tables.
- 02Slim the llms.txt or ship a companion llms-full.txt: the current llms.txt is ~174KB (~43K tokens) spanning ads, ads_manager, connect, and the dev platform — split out an API-focused, right-sized (<50KB) index so agents aren't forced to ingest the entire marketing/ads corpus.
- 03Add an AGENTS.md (and a .well-known/mcp.json pointing at the official MCP server) so coding agents and MCP clients can auto-discover the integration surface programmatically.
- 04Publish explicit numeric rate-limit thresholds and Retry-After header semantics rather than only 'contact your Instacart representative' — agents need concrete backoff values to behave correctly under 429.
- 05Add multi-language code examples (Python, JavaScript/Node) alongside the current curl-only samples and replace placeholder values like 'http://example.com' with realistic ones, so examples are copy-pasteable across the languages the docs already advertise (Java, Python).
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.
Auth is clearly documented (API key as a Bearer token for the Developer Platform API; client-ID/secret OAuth access tokens for Connect APIs). Errors use a machine-parseable two-format JSON schema (single + multiple) with an error.code, a human message, and a meta.key pinpointing the offending parameter, plus per-endpoint error tables and retry guidance. Rate limiting is acknowledged via a documented 429 with retry advice but no published numeric thresholds; pagination and idempotency keys are not documented for the core endpoints.