Apitap

ApiTap

<!-- Maintainers: this file documents the apitap CLI, driven through the
     terminal tool. The repo-root SKILL.md documents the MCP tools. They are
     different surfaces on purpose — skim both on every package release. -->

Sites render themselves from their own JSON APIs. ApiTap gets you that JSON instead of HTML: pull page content with no browser, or record a site's API traffic once, save it as a signed skill file, and replay those endpoints on demand with a plain HTTP call. Replay is an ordinary fetch(), with one exception: it can open a browser to re-mint credentials. Setup spells out exactly when.

Most tasks only need apitap read <url>. Start there and work down only when it falls short.

read has no size cap unless you pass --max-bytes <n>. On a long page it can return far more than 10K — cap it when the page might be large.

Where it sits next to tools you already have:

• vs web_extract — that returns generic page text; ApiTap returns the site's own structured JSON once an endpoint is known.
• vs browser automation — no selectors, no waiting on a page to settle, and normally no browser process at all (the exception is the credential re-mint described in Setup).
• vs a hand-written scraper — the artifact is a signed skill file on disk, reusable by every later session on that machine. Signatures are machine-bound, so a skill file does not transfer to another machine as-is.

Requires @apitap/core 2.2.0 or newer.

When to Use

Any request that means "get me data from a website or an API": articles, listings, search results, comments, prices, profile data, API responses.

Reach for ApiTap before browser tools. Escalate to a browser only after the browser-free path is exhausted: apitap peek, apitap read, apitap browse, and — when you need structured records — apitap discover or apitap import.

Setup

1. node -v — ApiTap needs Node 20 or newer.

2. command -v apitap — if that prints a path, it is already installed. Skip to the demo.

3. Install it: npm install -g @apitap/core. The download is large: Playwright is a hard dependency of the package even though almost nothing below needs a browser.

4. Still "command not found"? The npm global bin directory is not on PATH. Run npm prefix -g and invoke the binary as <prefix>/bin/apitap.

5. Some commands drive a browser: apitap capture and apitap inspect drive one through Playwright — they first try to attach to a Chrome already listening on a CDP port (18792, 18800, 9222) and only launch a fresh one when none is found (--launch forces a launch), apitap refresh launches one under the same condition as replay below (refreshable tokens, or a refresh URL that an OAuth exchange did not already satisfy) and otherwise does not, and apitap attach connects to a Chrome you already have running over plain CDP and needs no Playwright browser at all. Before using capture, inspect or refresh, run npx playwright install chromium in case the launch fallback is needed. These never launch one: apitap peek, apitap read, apitap browse, apitap search, apitap list, apitap show, apitap discover, apitap import, apitap stats.

   apitap replay is the in-between case, and this is the whole rule — the rest of this file defers to it. Replay attempts a credential re-mint in three situations: you passed --fresh, the stored credentials look expired, or the site answered 401/403. That re-mint opens a browser only when the skill file declares refreshable tokens (CSRF- or nonce-style values ApiTap detected in request bodies during capture) or a refresh URL; a pure OAuth refresh completes with no browser. Both conditions are properties of the skill file as a whole, not of the endpoint you replay — so replaying a public endpoint from a file that also holds refreshable tokens can open a browser if the site answers 403. Replay from a file with neither never does. In a sandbox with no browser, that re-mint fails the whole call.

Sandboxed terminal backends (Docker, Modal) are the weak spot. A global npm install may be refused, and an ephemeral filesystem loses both the install and the saved skill files under ~/.apitap between sessions. Prefer a local terminal backend. If you are inside a sandbox, apitap read and apitap peek still work after a fresh install; treat apitap capture as unavailable.

npx @apitap/core <cmd> is broken (scoped-package bin resolution, tracked as issue 46 in the repo). Use the installed apitap binary.

Quick demo

Works on a clean install, with no saved skill files and no browser:

apitap read https://en.wikipedia.org/wiki/Application_programming_interface --json

JSON lands on stdout — title, description, content, links. Parse stdout only: some commands write notices to stderr.

Quick Reference

Every command in this table accepts --json. The one exception anywhere in this file is apitap index build (see Pitfalls) — on success it takes no flags and always prints human-readable text. Its failure path honours --json like every other command.

Handy flags: --max-bytes <n> caps a response (apitap read, apitap browse, apitap replay); --limit <n> and --search <term> bound an import.

Write flag values space-separated: --max-bytes 50000, never --max-bytes=50000. The equals form is not parsed — the flag is silently dropped, with no error and no clue that it was ignored. Nothing validates flag values either, so a non-numeric one is discarded just as quietly.

Procedure

Day one, nothing saved yet — the normal case.

1. apitap peek <url> --json — free triage; says whether the page is reachable and what to do next.
2. apitap read <url> --json — for articles, threads, and content pages this is usually the entire job. Stop here once you have the data.
3. Need structured records rather than prose? apitap discover <url> --json finds endpoints without a browser; add --save to keep them as a skill file. For a well-known public API, apitap import --from apis-guru --search <name> --json beats discovery. Careful with --json --save together: when discover actually saves a file it prints two JSON documents — the result, then {"saved": "<path>"} — and a single parse of the whole output fails with "Extra data". Parse the first document, or read the output as a JSON stream. (When discover finds nothing to save, only one document appears, so this bites intermittently.)

Once skill files exist.

4. apitap search <query> --json to find the domain or endpoint, then apitap show <domain> --json to read the endpoint ids.
5. apitap replay <domain> <endpoint-id> key=value --json — the cheapest structured data available: no HTML, just the response. Usually a plain fetch(); see Setup for the cases where it re-mints credentials and can open a browser.

When you cannot tell which case you are in.

• apitap browse <url> --json runs the whole escalation and reports which source answered.

Last resort.

• apitap capture <url> --duration 30 --json opens a real browser and records traffic. Needs a browser on the host plus npx playwright install chromium. --duration is not optional in practice: without it capture waits for a Ctrl+C that an agent session never sends, and under --json it prints nothing at all while it waits, so it looks like a hang. Two ways to get that hang while believing you passed the flag: --duration=30 (the equals form is dropped) and --duration abc (a non-numeric value is discarded). Write --duration 30. Do not lead with this command, and expect it to be unavailable in a sandbox.