Basegrep API

The Basegrep API sells credential records — (domain, url, login, password) tuples — through a metered JSON API. You preview a query for free, run a search with a spend guard, and download the results as CSV. Big matches get dramatically cheaper per row, and you can retrieve any match in chunks without ever changing the total price.

flowchart LR
    A[Fund your token] --> B[POST /v1/count<br/>free preview]
    B --> C[POST /v1/search<br/>with billing guards]
    C --> D["303 → CSV file<br/>(no auth needed)"]
    D --> E{Rows remaining?}
    E -- yes --> F["POST /v1/search<br/>{\"continue\": ...}"]
    F --> D
    E -- no --> G[410 order_exhausted<br/>— done]

Quickstart

All examples use curl. Authentication is a bearer token obtained from the service administrator:

Authorization: Bearer sk_live_<secret>

Your token is printed once at creation and cannot be recovered — store it securely, and treat every file URL you receive as a secret too (see Files).

1. Check your balance (free):

curl -s https://api.basegrep.com/v1/balance \
  -H "Authorization: Bearer sk_live_..."

{"balance_cents": 100000, "spending_cents": 0,
 "period_start": "2026-09-01T00:00:00Z"}

2. Preview a query for free — never search blind:

curl -s -X POST https://api.basegrep.com/v1/count \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query": {"domain": "example.org"}, "max_rows": 1000}'

{
  "total_count": 2234,
  "delivered_count": 1000,
  "by_source": {"a": 1000, "b": 100, "c": 1134},
  "est_total_cost_cents": 33971,
  "est_cost_cents": 15206
}

3. Run the search with guards. max_rows caps how many units this chunk delivers; max_cost_cents aborts (charging nothing) if the chunk would cost more:

curl -i -X POST https://api.basegrep.com/v1/search \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6c84fb90-c1b9-4c26-9d0e-2d4a6a1f9c33" \
  -d '{
    "query": {"domain": "example.org"},
    "billing": {"max_rows": 1000, "max_cost_cents": 40000}
  }'

HTTP/1.1 303 See Other
Location: /v1/files/ord_9f8e7d6a5b4c3d2e1f0a....csv

Always send an Idempotency-Key (any UUID you generate) — it makes retries safe and free.

4. Download the file. No auth header; the URL itself is the credential:

curl -s "https://api.basegrep.com/v1/files/ord_9f8e7d6a5b4c3d2e1f0a....csv" \
  -o chunk-1.csv

5. Continue for the remainder. Same endpoint, query replaced by continue; repeat until you get 410 order_exhausted:

curl -i -X POST https://api.basegrep.com/v1/search \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"continue": "ord_9f8e7d6a5b4c3d2e1f0a...",
       "billing": {"max_rows": 1000, "max_cost_cents": 40000}}'

To assemble the full match, concatenate the chunk files and drop the repeated header lines from all but the first. The result is gap-free, non-overlapping, and deterministically ordered — and the chunks always sum to exactly what a one-shot search would have cost.

The five rules that matter

1. All money is integer cents. No floats anywhere.
2. You are billed per unique (domain, login, password) — duplicate URLs within a domain are free.
3. Chunking never changes the total. Retrieve in 1 chunk or 50; the sum is identical to the cent.
4. max_rows gives you a deterministic sample; max_cost_cents is a hard stop that charges nothing on trip.
5. Files live 72 hours from the root order — continuations never extend that clock.