◎ Discry Score
airbyte.com
infrastructure · API
B
0 / 100
DISCOVERY0
COMPREHENSION0
Category leader: 98 (A)
Discry your API →
INFRASTRUCTURE · RANK #27 OF 68

Airbyte is Good to agents.

Discry independently scored how well an AI agent can discover and understand the Airbyte 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 · 81/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.Pass
llms-full.txtA full-text bundle agents can load in one request.Pass
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 · 76/100
Task-oriented descriptionsEndpoints described by what they accomplish, not just their shape.Partial
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.Partial
Naming consistencyConsistent, predictable naming across endpoints.Partial
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.Pass

What we found

  • An agent landing on any API reference page is explicitly redirected to reference.airbyte.com/llms.txt by a banner on every page, and every endpoint doc is served as clean markdown (.md with text/markdown content type) — among the most deliberately agent-discoverable API references scanned.
  • Error recovery is genuinely agent-usable: errors are RFC 7807 JSON with title/detail/type, and the Error Messages page gives actionable fixes per code (401: verify Bearer header format; 409: only one sync can run at a time, retry later; 422: payload details included). The API landing page even instructs clients to retry a 401 exactly once after refreshing the token.
  • A valid OpenAPI 3.1.0 spec for api.airbyte.com exists but is buried in the airbytehq/airbyte-platform GitHub repo (airbyte-api/server-api/src/main/openapi/api.yaml) and is not linked from the docs — an agent must already know to search GitHub for it.
  • No rate-limit documentation exists for api.airbyte.com — an agent discovers throttling only by failing, which is ironic given Airbyte's own connector-builder ships sophisticated rate-limit (API budget) tooling for the APIs it ingests.
  • Airbyte publishes three llms.txt files of wildly different quality: reference.airbyte.com's is exemplary (API-focused, every endpoint as .md with descriptions), airbyte.com's is a curated 19.5KB index, but docs.airbyte.com's is a 526KB site-wide dump (~130K tokens) that would flood any agent context window that fetches it.

What to change

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

  1. 01Publish the OpenAPI spec at a stable, documented URL (e.g. api.airbyte.com/openapi.json) and link it from reference.airbyte.com — the spec already exists and is maintained; it is just undiscoverable.
  2. 02Document rate limits for api.airbyte.com: the limits themselves, the response behavior when throttled, and any rate-limit headers agents should read.
  3. 03Replace docs.airbyte.com/llms.txt (526KB auto-generated dump) with a curated, right-sized index modeled on the airbyte.com and reference.airbyte.com versions.
  4. 04Add descriptions to the many bare CRUD entries in the API reference (e.g. 'Create a workspace', 'Update a permission' carry no task context an agent can match against its goal).
  5. 05Add an AGENTS.md to airbytehq/airbyte and publish .well-known/mcp.json — Airbyte already ships an official MCP server, so declaring it at the domain root is a near-free discovery win.

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.

OAuth2 client credentials (Application client_id/secret exchanged at /v1/applications/token)Bearer access token (short-lived: 3 min Cloud, 24 h Enterprise)✓ Error format documented✕ Rate limits documented✓ Pagination documented✕ Idempotency documented

Auth and error behavior are documented to an agent-usable standard: RFC 7807 machine-parseable JSON errors with per-error recovery steps, explicit token-expiry handling (cache, validate, retry a 401 exactly once), and next/previous pagination links shown in list responses and the OpenAPI spec. Rate limits and idempotency are not documented anywhere for api.airbyte.com.

See your own Discry Score.

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

Discry your API — free