AssemblyAI is Agent-Ready to agents.
Discry independently scored how well an AI agent can discover and understand the AssemblyAI 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 · 93/100Comprehension
55% of score · 96/100What we found
- An agent integrating AssemblyAI lands in near-ideal conditions: a well-structured root llms.txt explicitly instructs agents to append `.md` to any docs URL for clean Markdown, points to a docs MCP server (https://assemblyai.com/docs/mcp), and links an official installable coding-agent skill (npx skills add AssemblyAI/assemblyai-skill).
- A publicly accessible OpenAPI 3.1.0 spec (/openapi.yaml and /docs/openapi.json) covers all REST endpoints with task-oriented summaries, realistic UUID/value examples, and a documented Retry-After header on 429s — an agent can generate a correct client without guesswork.
- robots.txt allows all crawlers (only /.well-known and playground transcripts disallowed), and a multi-sitemap setup (including a dedicated docs sitemap) lists every API-reference page — so an agent can both discover and fully enumerate the API.
- Markdown is first-class everywhere: every endpoint page, a docs llms-full.txt, and section-level llms.txt indexes mean an agent never has to parse JS-rendered HTML. Naming is consistently snake_case (audio_url, speaker_labels, transcript_id) across the spec.
- The one structural gap is no /.well-known/mcp.json at the apex domain — AssemblyAI exposes its MCP server via docs path and registries instead, so a strict well-known probe fails despite genuine MCP availability.
What to change
Prioritized by impact on discoverability. You (or your docs platform) deploy these — Discry never touches your API.
- 01Serve /.well-known/mcp.json at the apex domain (currently 404) declaring the existing docs MCP server and its tools, so agents that probe the conventional discovery path find it without reading llms.txt first.
- 02Mirror llms-full.txt to the apex root (https://www.assemblyai.com/llms-full.txt currently 404; only /docs/llms-full.txt exists) so agents hitting the conventional root path get the full corpus directly.
- 03Strengthen 4xx error-recovery guidance in the API reference: for 400 Bad Request, document which parameter failed and valid values (the worked retry guide today mainly covers 5xx server errors), so an agent can self-correct on validation failures without trial-and-error.
- 04Make core transcription rate/concurrency limits explicit alongside the LLM Gateway limits (currently the only numerically documented limits), so an agent can pace batch submissions proactively rather than reacting to 429s.
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.
Execution characteristics are thoroughly documented in both prose and the OpenAPI 3.1.0 spec. Errors return machine-parseable JSON ({"error": "..."}) with an HTTP code table; a 429 includes a Retry-After header and a dedicated retry-server-error guide. List endpoints support pagination. No idempotency-key mechanism is documented (the async submit/poll model makes it largely unnecessary).