Skip to main content
When --spec points at an HTML page rather than a spec, pikopod climbs a ladder. The first line of output names the rung that succeeded.

​
The ladder

Rungs 1 to 4 are deterministic and need no key. Only if all four miss does pikopod reach rung 5, and with no key configured it stops and tells you so rather than degrading quietly.

​
What each page may contribute

When the site publishes an llms.txt index, every indexed page is classed by its URL before any budget applies, and the class decides what the model may take from it: Reference and webhook pages are never dropped by the index cap; only context pages are capped, at 64. An endpoint the model wrote from a context page alone is dropped after extraction and named in the output, so a “supported channels” guide cannot invent a call the reference never documents. When a site has no reference pages at all, every page may define endpoints. Every extracted operation carries x-pikopod-source, the page it came from. After the batched extraction, any reference page that mentions an HTTP method but ended up on no operation is sent to the model again on its own, up to twelve pages per import, and the output says how many were retried and how many came back with an endpoint:
A reference page that still yields nothing is a page the model could not read as an endpoint. The count tells you the spec is short by that much before you serve it. Example bodies shown in the documentation become example values in the spec, on the media type and on the fields, so the sandbox answers with the provider’s own sample values instead of synthesised ones. The model is told to emit every documented auth scheme by its exact header or mechanism, per-operation security where operations differ, and required non-auth headers as header parameters. A servers entry pointing at the documentation site itself is discarded; the base URL that matters is the upstream target in pikopod.yaml. The linked-document rungs deliberately have no same-host restriction, because documentation sites legitimately host their spec on another domain. If your threat model includes SSRF from an untrusted docs page, fetch the spec yourself and pass a local path. See Security.

​
A model-written contract is a draft

Extracted fields are simulated, so the sandbox is useful at all for a provider that ships no spec, but the guess is carried, labelled, and outranked:
  • Marked DRAFT in pikopod sandbox list.
  • Capped below ERR in any spec diff.
  • Never unlock readable enum values in recordings.
  • Cannot bind a failure archetype without an explicit --bind. scenario list prints the line to use. See Binding.
  • Lose to observed traffic whenever the two disagree.
If some indexed pages did not fit the extraction budget, they are listed, so you know the spec is partial.

​
Make the facts yours

The extracted spec is written with an x-pikopod-origin: llm-extracted marker. Review it, add x-pikopod-trigger to each webhook event or bind them in a webhooks sidecar, commit it, and import from the file from then on, with no model in the loop:
It re-imports as DRAFT until you delete the marker line, which says the facts are now yours.

​
Webhooks from a docs import

A documentation page rarely says which API call fires which event. Bind them without re-importing:
See Webhooks.