Seed a Mock Library

The empty-library problem

The recorded path works the moment traffic flows. Seeding covers the gap before it does. A seeded mock is the same shape as a recorded one — once it's in the library, the serving cascade, fidelity scoring, and drift detection can't tell a seeded mock from a recorded one. The only difference is provenance: each seeded row carries a source tag of seed_har, seed_postman, or seed_openapi.

Seeding from the dashboard

The operator dashboard has a drag-drop seeding page. Drop a file, pick the target service, pick a format, and commit. When the file parses as JSON the format is auto-detected from its top-level shape; YAML specs are picked manually. The steps:

An Advanced options drawer exposes the per-format knobs (deduplication, and the OpenAPI-only 2xx only and prepend basePath toggles). The defaults match the API's server-side defaults, so committing without opening the drawer gives you the canonical run.

The seeding endpoint

The dashboard is a thin client over a single control-plane endpoint. Format is a path parameter so the URL is self-descriptive in logs:

POST /v1/seed/{format}?service_id=<id>&dedup=true
# format ∈ { har, postman, openapi }

The endpoint is authenticated like every other control-plane call — pass the X-API-Key header. The body can be sent three ways: a multipart file=field (the dashboard's drag-drop path), an application/json body with the parsed payload inline, or raw bytes (application/yaml / application/octet-stream) for a YAML or binary upload.

# Seed a service's library from a HAR export
curl -X POST 'http://localhost:8000/v1/seed/har?service_id=svc-payments' \
  -H "X-API-Key: $GHOST_API_KEY" \
  -F 'file=@session.har'

# Seed from an OpenAPI spec, keeping only 2xx responses
curl -X POST 'http://localhost:8000/v1/seed/openapi?service_id=svc-payments&success_only=true' \
  -H "X-API-Key: $GHOST_API_KEY" \
  -H 'Content-Type: application/yaml' \
  --data-binary @openapi.yaml

The response reports what was persisted: the count added, how many duplicates were dropped, parser warnings, and up to five sample routes:

{
  "format":      "har",
  "count":       42,
  "deduped":     5,
  "service_id":  "svc-payments",
  "warnings":    ["skipped 2 WebSocket frames (out of scope for HTTP mocking)"],
  "errors":      [],
  "sample_uris": ["GET /v1/charges", "POST /v1/charges", "GET /v1/customers/{id}"]
}

Per-format options

All three formats share service_id (required) and dedup. The rest are format-specific query knobs — passing a HAR-only knob to an OpenAPI import is simply ignored.

What happens on import

Each parser normalises its input into the canonical mock row shape, the rows are deduplicated, persisted, and the proxy is signalled to reload:

Once the import lands, switch the proxy to MOCK mode and the seeded mocks serve immediately through the same match cascade as recorded traffic — exact match first, AI generation only as a last resort, never on the request hot path.

Errors and warnings

The endpoint validates at the boundary and fails loudly. Two failure classes:

Warnings are non-fatal and surface in the warnings array of a successful response — skipped WebSocket frames in a HAR (captured for observability, never replayed), an arbitrary oneOf branch chosen in an OpenAPI spec without a discriminator, an external $refthat wasn't chased, and the like. The import succeeds; the warnings tell you what was approximated or dropped.

A note on the data you import

Seeded mocks are subject to the same handling as recorded traffic. A floor of credential-bearing headers (Authorization, cookies, API keys, and the rest of the enterprise security-header set) is stripped before anything is written to disk. Bodies are kept verbatim on the local replay library so replay fidelity is exact, and PII in bodies is scrubbed when rows are written to the Postgres store and on any export.