Heap is Good to agents.
Discry independently scored how well an AI agent can discover and understand the Heap 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 · 60/100Comprehension
55% of score · 90/100What we found
- Heap is explicitly agent-aware: every reference page carries a banner telling AI agents to visit /llms.txt 'for an index of all pages formatted in Markdown and endpoints in OpenAPI,' and a real, well-structured llms.txt with per-endpoint descriptions exists — an agent landing anywhere is pointed straight at machine-readable docs.
- Every doc page is available as clean markdown (.md), and endpoint pages are answer-first with task-oriented descriptions ('Use this API to send custom events to Heap server-side') and realistic multi-language examples (alice@example.com, real event names) — an agent can understand and call the Track API from a single page.
- The Track endpoint documents its boundaries inline — 30 requests/30s per identity, mutually-exclusive identity/user_id, reserved property keys, character caps, and a separate EU datacenter endpoint — so an agent learns the limits before it fails rather than after.
- Despite the docs being OpenAPI-backed, an agent cannot find a downloadable OpenAPI spec at any standard path, finds no AGENTS.md in any of Heap's 65 GitHub repos, and finds no Heap analytics MCP server in any registry — the machine-contract and ready-made-tool surfaces are all missing.
- Error responses are documented only as bare 200/400 status codes with empty example bodies — an agent that receives a 400 gets no error body schema and no per-cause fix guidance, so it must guess which field was invalid.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Publish the OpenAPI spec at a stable public URL (e.g. /openapi.json) and link it from llms.txt. The reference is already OpenAPI-backed, so exposing the raw spec is a quick win on the highest-weighted discovery check.
- 02Document the 400 error response body: show the actual JSON error shape and map common causes (missing app_id, supplying both identity and user_id, oversized property values) to explicit fixes. This is the single biggest comprehension gap for agents.
- 03Add an AGENTS.md to the primary public repos (heap-js, the server-side client) so coding agents get setup and usage context — none of Heap's GitHub repos currently have one.
- 04Add a /.well-known/mcp.json or publish/list a Heap MCP server. There is currently no MCP discovery surface, so agent runtimes cannot auto-discover Heap as a callable tool.
- 05Consolidate the prerequisite -> identify -> track -> enrich flow into one end-to-end server-side workflow guide on developers.heap.io (today it is split across the dev docs and help.heap.io), so an agent can follow a single happy path including error handling.
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.
Server-side APIs are POST ingestion endpoints authenticated by an app_id (environment ID), with user deletion requiring an auth token. The Track endpoint documents a hard rate limit (30 requests / 30 seconds per identity per app_id) and supports an idempotency_key to dedupe events. Pagination is not applicable to these write-only endpoints. Error responses are shown only as bare 200/400 status codes with empty example bodies — no machine-parseable error body schema is documented.