Skip to main content
Plenty of good APIs never publish an OpenAPI file. The docs are fine; the machine-readable artifact just doesn’t exist, so there is nothing for a tool generator to read. gecko from-docs is the on-ramp: it reads the doc site and hands the comprehension engine a draft OpenAPI.

​
What it does

  1. Fetch the doc page — SSRF-validated (private / loopback / link-local ranges and non-HTTP schemes are refused, every redirect re-checked). The bytes are parsed and discarded: Gecko is control-plane only, it never stores the doc.
  2. Recover candidate operations from the page’s structure — headings, code blocks, and parameter tables, in document order — into a draft OpenAPI 3.1. JSON-RPC methods are modeled honestly (one operation per method; the envelope carried on x-jsonrpc-*).
  3. Comprehend the draft through the same engine as any spec → question-shaped, first-call-correct agent tools.

​
It’s an assistive draft, not zero-touch

from-docs is honest about its uncertainty. Every field it couldn’t pin down from the docs is flagged with x-review and a confidence level in the draft spec — so a human (or an agent) confirms those before going live. It gets the surface and shape right; you confirm the ambiguous edges, then run gecko test <draft> to prove the calls before you ship.

​
JS-heavy doc sites

Static docs work out of the box with the built-in reader — no extra dependencies. For doc sites that render their navigation with JavaScript, from-docs tells you when it recovered only a few operations and points you at the agent-browser driver in spikes/docs_reader, which renders the JS nav before extracting.

​
Why this matters

Every other page here starts from a spec. This is the step before that. An API with no OpenAPI file isn’t a worse API — it just has nothing an agent can read mechanically. from-docs produces that artifact, marks what it could not pin down, and never invents an endpoint to fill a gap. From there the rest of the pipeline is identical.