jatinag22/site-to-api

Record one browsing session of a website. Get the OpenAPI specs, request flows and typed client
a coding agent needs to build a wrapper for its internal API.
site-to-api is for developers who need to integrate with a website that has no public API,
usually with a coding agent writing the code. Use it only on sites you are allowed to use; it never
bypasses bot protection, captchas or access controls.
It records what a site's own pages do while you use it (or reads a HAR you already have), then
works out the endpoints, their schemas, the order requests happen in, which value feeds which
request, and what a session needs. It writes one folder: OpenAPI 3.1 and AsyncAPI 3.0 specs,
request flows, a short AGENT.md for your coding agent, excerpts of the site's own code, and a
typed TypeScript client with Zod validation.
No LLM runs inside the tool: the same capture gives byte-identical output, and your coding agent
does the reasoning on top of it. Each request input is traced to its origin, such as a CSRF token
in a meta tag, an ID from an earlier response, or a password encrypted in the browser by
encryptPassword() in the site's own src/auth/crypto.ts, recovered from its sourcemaps. Raw
captures stay in a gitignored folder; the handoff folder is redacted, and a leak check fails the
build if a secret learnt from the capture slipped through. Bot protection is recorded as "needs a
real browser"; probe measures what plain HTTP needs, and check reports when the API drifts.
## Quick start
Requires Node 22.12 or later.
sh
npm init -y # if this folder has no package.json yet
npm install -D site-to-api # the CLI, a development dependency
npx site-to-api init # config file, and a gitignore for raw captures
npx site-to-api capture https://example.com
# a browser window opens: use the site the way your wrapper will (log in, search, open pages),
# then close the window (or press Ctrl+C here) to finish
npx site-to-api build # writes api-handoff/
npx site-to-api probe # optional: what plain HTTP needs (read-only requests, 1 per second)
Then give your coding agent a task such as:
> Read api-handoff/AGENT.md and write src/shop.ts: a function that logs in and returns my
> orders, using the generated client in api-handoff/client/.
Commit api-handoff/. Never commit .site-to-api/: it holds the raw captures, with your real
cookies and tokens.
capture opens Google Chrome. Where Chrome is not installed it uses Playwright's bundled
Chromium instead and says so; download that once with npx playwright install chromium. Pass
--channel chrome (or msedge, or bundled) to require one browser. A second capture of the same
pages (--session second-pass) gives the build two samples to compare.
The generated client runs in your app with two runtime dependencies:
sh
npm install site-to-api-runtime zod
## What you get
api-handoff/
AGENT.md start here: hosts, what each session needs, key flows, top gaps
hosts/ .md everything about one host: cookies, bot protection, operations, channels
APIMAP.md one row per operation: inputs and where each value comes from
flows.json request flows and value origins (flows.md is the readable copy)
specs/ .yaml OpenAPI 3.1; .asyncapi.yaml for WebSocket and event-stream channels