# wit URL API

> Read any GitHub repository without cloning: plaintext (or JSON) over GET
> requests, pinned to an immutable commit, with token budgets you control.

Base URL: https://wit-url-api.pages.dev/api
OpenAPI: https://wit-url-api.pages.dev/api/openapi.json

## Rules of thumb for agents

1. Start with `stats`, not `tree`: it tells you how many tokens the repo (or a
   directory) would cost and which directories/languages dominate.
2. Use `outline` on a file before `cat`: it returns symbols with line ranges, so
   you can `cat?lines=A-B` exactly what you need.
3. Prefer `rg?l=1` (files only) to locate code, then `rg?C=2` on a narrowed
   `path=` or `glob=` for context. `rg` is bounded (max=200 matches,
   max_files=200 files by default; ceilings 2000/1000). Truncation is
   reported in a trailing `# truncated:` line (or `truncated` in JSON) — narrow
   the query instead of assuming a null result.
4. Pin what you read: every response carries `x-wit-commit`, `x-wit-ref` and
   `x-wit-cache: hit|miss`. Pass `?ref=<sha>` to reproduce a read later.
5. Add `?format=json` (or `Accept: application/json`) for structured output with
   the same provenance fields in the body.

## Verbs

Repository verbs take `/{verb}/{owner}/{repo}`; the file path is always `?path=`.

| verb | purpose | key params |
|------|---------|------------|
| stats | Size, token estimate, language and directory breakdown from the tree alone (no blob reads). | path, largest (default 10, max 100), ignore |
| tree | Recursive file listing (files only, dirs implied). | path, depth, l=1 (bytes + ~tokens), ignore |
| ls | One directory level. | path, l=1 |
| outline | Line-numbered symbol index for one file (regex heuristic, no AST). | path (required), max_symbols |
| cat | File contents; ?lines=A-B reads a one-based inclusive range. | path (required), lines=A-B (or start=&end=), n=1 |
| head | First N lines of a file. | path (required), lines (default 10), n=1 |
| tail | Last N lines, or from line N onward. | path (required), lines (default 10), plus=N, n=1 |
| rg | Bounded ripgrep-style regex search over text files. | q (required), path, glob, i=1, S=1, w=1, v=1, l=1, c=1, C/B/A, max, max_files, ignore |
| refs | Default branch, branches, and tags. | — |
| commits | Recent commits, optionally for one path. | path, n (default 10, max 100), ref |
| search | GitHub repository search (find owner/repo for 'libraries that do X'). | q (raw GitHub query), p (name), lang, limit (default 10, max 100), sort=stars\|updated\|forks\|best |

Common params: `ref=` (alias `branch=`; branch, tag, or full commit SHA),
`fresh=1` (re-resolve the ref instead of serving the cached pin),
`format=json`, `ignore=GLOB` (repeatable).

Outline languages: C, C#, C++, Elixir, Go, INI, Java, JavaScript, Kotlin, Markdown, PHP, Python, Ruby, Rust, SQL, Scala, Shell, Swift, TOML, TypeScript, YAML.

## Examples

    curl "https://wit-url-api.pages.dev/api/stats/ratatui/ratatui"
    curl "https://wit-url-api.pages.dev/api/tree/ratatui/ratatui?path=src/widgets&depth=1&l=1"
    curl "https://wit-url-api.pages.dev/api/outline/ratatui/ratatui?path=src/widgets/block.rs"
    curl "https://wit-url-api.pages.dev/api/cat/ratatui/ratatui?path=src/widgets/block.rs&lines=1-60&n=1"
    curl "https://wit-url-api.pages.dev/api/rg/ratatui/ratatui?q=impl%20Widget&glob=*.rs&l=1"
    curl "https://wit-url-api.pages.dev/api/rg/ratatui/ratatui?q=fn%20render&path=src/widgets&C=2&max=20"
    curl "https://wit-url-api.pages.dev/api/refs/ratatui/ratatui"
    curl "https://wit-url-api.pages.dev/api/commits/ratatui/ratatui?path=src/lib.rs&n=5"
    curl "https://wit-url-api.pages.dev/api/search?q=terminal%20ui&lang=rust&limit=5"
    curl -H "Accept: application/json" "https://wit-url-api.pages.dev/api/ls/ratatui/ratatui?path=src"

## Errors and limits

Errors are `error: <message>` (or `{"error","code","status"}` in JSON).
HTTP 429 means GitHub's quota is exhausted for the credentials in use; the
body says whether that was the host's token or yours, `retry-after` says when
to retry, and sending your own `Authorization: Bearer <token>` always uses
your quota instead. Files over 1 MiB, binary files, and repositories whose
recursive tree GitHub truncates are refused with a clear message.

Content is pinned per request but cached for up to 24h per repo@ref; use
`fresh=1` when you need the branch head resolved now.

Token estimates are ~4 bytes per token from sizes alone (no blob reads) and
are meant for budgeting, not accounting.