# Zatanna API Reverser

> Given a file of captured HTTP request/response traffic, reverse-engineers the undocumented API and emits a valid OpenAPI 3.0 spec. Use this skill when you have browser HAR exports, proxy captures, or any set of raw HTTP pairs and need a clean, machine-readable API contract without access to the original source code or docs.

- Skill: `riteshkew/zatanna-api-reverser` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add riteshkew/zatanna-api-reverser`
- Raw SKILL.md: https://api.skillmd.com/api/skills/riteshkew/zatanna-api-reverser/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: riteshkew (https://skillmd.com/u/riteshkew)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/riteshkew/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:

```bash
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:

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