Zatanna API Reverser

Workflow

When this skill triggers, follow these steps in order.

Step 1 — Locate the traffic file

Check whether the user has specified a traffic JSON path.

• If a path is provided, confirm the file exists and is readable.
• If no path is provided, ask: "Please provide the path to your captured traffic JSON. It must be an array of { method, url, status } objects, with optional requestBody and responseBody. See resources/traffic.json for a working example."
• If the user has a HAR file instead, explain that they should extract the entries array from HAR and map each entry to { method, url, requestBody, status, responseBody } before proceeding.

Step 2 — Describe what will be inferred

Before running the engine, tell the user what the analyzer will produce:

1. Path templating — numeric and UUID path segments are collapsed into typed {id} parameters (e.g. /users/123 → /users/{id}).
2. Query parameter discovery — all query string keys observed across all captured requests for each endpoint are collected.
3. Request body schema — JSON request bodies are introspected to produce an OpenAPI requestBody with inferred property types.
4. Response schema per status code — response bodies are introspected per HTTP status code to produce typed responses.
5. Server URL — extracted from the base URL of the first captured entry.

Step 3 — Run the engine

Execute the engine from the skill root:

node scripts/traffic-to-openapi.mjs <path-to-traffic.json>

The engine writes a complete OpenAPI 3.0.3 JSON document to stdout.

Capture stdout. If the process exits non-zero, surface the stderr message to the user and stop.

Step 4 — Report the discovered API

After the engine succeeds:

• State how many distinct path templates were discovered.
• List each path with its HTTP methods, path/query parameters, and response status codes.
• Highlight any endpoints where request body schemas were inferred.
• Note any endpoints with error responses (4xx/5xx) captured.

Output format

Discovered <N> endpoint(s) from <M> captured traffic entries.

| Path | Methods | Path Params | Query Params | Response Codes |
|------|---------|-------------|--------------|----------------|
| /api/users | GET, POST | — | — | 200, 201 |
| /api/users/{id} | GET | id (integer) | — | 200, 404 |

Then present the full OpenAPI JSON inside a fenced code block.

Step 5 — Suggest next steps

After delivering the spec:

• Recommend validating the generated spec with an OpenAPI linter (e.g. redocly lint or openapi-validator).
• Note any ambiguities: string IDs that look like slugs, missing authentication schemes, undocumented error shapes.
• Offer to generate a client SDK stub, mock server config, or Postman collection from the spec.

Example

See examples/input.md for the traffic scenario and examples/output.md for the OpenAPI spec produced by the engine.

Run the example yourself from the skill root:

cd skills/zatanna-api-reverser
bash examples/run.sh