OpenAPI spec
An OpenAPI specification is a machine-readable description of a REST API — its endpoints, parameters, request and response schemas, and authentication schemes — written in JSON or YAML against the OpenAPI Specification standard. Because the format is standardized, tooling and AI agents can parse it to learn exactly what an API accepts and returns, without reading prose documentation.
For an AI agent, an OpenAPI spec is the closest thing to ground truth about an API. Agents and the frameworks around them convert spec operations directly into callable tool definitions: each path, parameter schema, and response shape becomes structure the model can act on. Prose documentation requires interpretation; a spec can be consumed mechanically.
The spec only helps if an agent can fetch it. A spec that lives behind a login, is served only through a JavaScript-rendered explorer, or sits at an unguessable URL is invisible to the plain HTTP fetches most agents perform. Publishing the spec at a stable public URL — and linking it from llms.txt or the docs homepage — turns it into a discovery signal rather than an internal artifact.
Spec quality compounds: schemas with descriptions, examples, and consistent operationIds generate better tool definitions, which means fewer malformed calls when an agent integrates unattended.
Discry's scan probes common public spec paths and follows any OpenAPI or Swagger links found in the API's llms.txt, then validates that what it finds actually parses as a spec. A publicly fetchable, valid spec passes the openApiSpec discovery check on the API's profile; a URL that resolves but fails to parse is recorded with the reason.
Checks: OpenAPI spec · how each is scored
What does an AI agent make of your API?
Find out in about a minute — no signup.
Discry your API — free