Importing from a docs URL

When the provider ships no spec, point —spec at their documentation page.

pikopod import examplepay --spec https://docs.examplepay.test

documentation page → spec via well-known-spec (https://docs.examplepay.test/openapi.json)
sandbox examplepay registered (sbx_41d959476a09e5f9, 4 endpoints)

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

Rung	Method	What it does
1	postman-documenter	Follows a link from the page to a published Postman collection.
2	spec-link	Follows a link from the page to an OpenAPI, Swagger or GraphQL document.
3	readme-embedded	Reads a spec embedded in the page itself, or one hop into the site’s own reference index.
4	well-known-spec	Probes the site’s well-known spec paths and its llms.txt index.
5	llm-extracted	Only with your own model key. Assembles up to 240 KB of the site’s prose and asks your model to write an OpenAPI document from it.

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.

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

documentation page → spec via llm-extracted (https://docs.examplepay.test (+6 pages, 3/3 batches))
note: this contract was EXTRACTED BY YOUR LLM from prose — it imports as DRAFT with LLM_EXTRACTED provenance; `pikopod sandbox list` shows the marking

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

pikopod import examplepay --spec https://docs.examplepay.test --emit-spec specs/examplepay.yaml

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:

pikopod import examplepay --update --spec specs/examplepay.yaml

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:

pikopod sandbox webhooks examplepay examplepay-webhooks.yaml

See Webhooks.