Importing

pikopod import examplepay --spec ./openapi.json

sandbox examplepay registered (sbx_41d959476a09e5f9, 4 endpoints)
serve it with `pikopod up` → http://127.0.0.1:4600/examplepay/...
test credential (send it the way the spec's auth scheme expects, e.g. the Authorization header):
  pikopod_sbx_test_8eb1bc48ceb2fcd6ab7ba33c12f314189b3e51502ea32156

The name becomes the route: /examplepay/ on the sandbox listener. It may not contain slashes or whitespace.

Formats

--spec takes a local path or an http(s) URL to:

Format	Notes
OpenAPI 3.0 and 3.1	JSON or YAML. Same-repository relative `$ref`s resolve for local files.
Swagger 2.0
Postman collection v2	Collection-level auth, documented examples and `:param` segments are understood.
GraphQL schema	Up to 5 MiB.
A documentation page	See Importing from a docs URL.

Documents up to 32 MiB are accepted. Remote and absolute $refs are refused; see Multi-file specs.

Provenance

Every field in the imported contract carries where it came from: EXPLICIT (stated in the source) or DERIVED (a deterministic transformation of it). A contract a model wrote from documentation carries LLM_EXTRACTED and imports as DRAFT. The levels never merge, so extracted behaviour is never presented as documented behaviour.

Seeds and credentials

The seed drives every synthesised value, every webhook delivery id, and the issued test credential. It is random by default. Pin one for reproducible transcripts:

pikopod import examplepay --spec ./openapi.json --seed ci-fixed

The credential is printed at import and by pikopod sandbox list. Send it the way the spec’s auth scheme expects: a bearer token in Authorization, an API key header, or basic auth. A request without it is refused as the spec declares.

Linking to an upstream

When an agent upstream of the same name exists in pikopod.yaml, the sandbox is linked automatically. --upstream <name> links explicitly. A linked upstream’s traffic can refine the contract and feed the recordings tier. See Contract and Recordings tier.

Webhooks at import

--webhook-url sets the sink deliveries POST to. --webhooks <file> attaches an envelope and event bindings. See Webhooks.

Keeping the spec you imported

pikopod import examplepay --spec https://api.examplepay.com/openapi.json --emit-spec specs/examplepay.json

Writes the document the import used, fetched or extracted, so it can be reviewed and committed. Import from the file from then on.

Updating

pikopod import examplepay --update
pikopod import examplepay --update --spec ./openapi.v2.json

Re-imports from the recorded source, or a new one, and prints the declared changes it accepts, using the same checks as spec-diff. The webhook envelope and every event binding the new spec still declares are kept, and the spec watcher’s pin is reset. Restart pikopod up to serve the updated contract.

Where it lives

The registry is <data_dir>/sandboxes.json, and the normalized contract is <data_dir>/apis/<name>.ir.json. See Data directory.

Getting started

Gate: catch declared changes in CI

Sandbox: rehearse failures

Scenarios

Observe: the agent

Reproduce and fix

Operations

Project

Formats

Provenance

Seeds and credentials

Linking to an upstream

Webhooks at import

Keeping the spec you imported

Updating

Where it lives

​Formats

​Provenance

​Seeds and credentials

​Linking to an upstream

​Webhooks at import

​Keeping the spec you imported

​Updating

​Where it lives

Formats

Provenance

Seeds and credentials

Linking to an upstream

Webhooks at import

Keeping the spec you imported

Updating

Where it lives