# Forage

> Turn any web page or audio into AI-ready data. One HTTP API for agents, pipelines, and apps. Edge-deployed on Cloudflare — fast and global.

Forage is a REST API that takes a URL (or raw HTML, or an audio file URL) and returns clean, structured, LLM-ready data. It uses smart rendering: a plain fetch for static pages, and only spins up a real headless browser when a page is a JavaScript shell (or when you pass `render:"always"`). Failed operations are automatically refunded.

## When to use Forage

Web scraping and crawling for LLMs, RAG ingestion, agent tools, screenshot/PDF automation, audio transcription, and review aggregation — all behind one bearer-token HTTP API.

## Base URL and auth

- Base URL: `https://forageapi.com` (currently live at `https://forageapi.com`; `forageapi.com` coming soon).
- All endpoints live under `/v1`.
- Auth is a bearer token: `Authorization: Bearer fk_live_...`

## Getting a key

`POST /v1/keys` with `{"email":"you@example.com"}` returns a free API key with 300 free credits — no credit card, one key per email. The key is shown exactly once.

## Quickstart

Get a free API key:

```bash
curl -X POST https://forageapi.com/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'
# forageapi.com base URL coming soon
```

Convert a web page to markdown:

```bash
curl -X POST https://forageapi.com/v1/markdown \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
# forageapi.com base URL coming soon
```

## Endpoints

All endpoints are `POST` unless noted. Costs are in credits.

### POST /v1/keys — create a free API key
- Body: `{email}`
- Public, no auth. **0 credits.** Returns a key with 300 free credits (shown once).

### POST /v1/markdown — clean LLM-ready markdown from a URL
- Body: `{url, render?}`
- **1 credit.**
- Returns: `{url, rendered, markdown, tokens_estimate}`

### POST /v1/screenshot — PNG screenshot
- Body: `{url, full_page?, width?, height?, wait_ms?}`
- **1 credit.**
- Returns: PNG (`image/png`)

### POST /v1/pdf — render a page to PDF (A4)
- Body: `{url, width?, height?, wait_ms?}`
- **2 credits.**
- Returns: `application/pdf`

### POST /v1/extract — structured JSON matching your JSON Schema
- Body: `{url|html, schema, instructions?, render?}`
- **2 credits.**
- Returns: `{url, rendered, data}`
- Never invents data — uses `null` for missing fields.

### POST /v1/transcribe — Whisper transcript with word timestamps + segments
- Body: `{url}` (audio file, max 24MB)
- **2 credits minimum, then 1 credit per started minute.**
- Returns: `{url, duration_seconds, credits_charged, text, segments, vtt}`

### POST /v1/reviews — schema.org review + aggregateRating from JSON-LD markup
- Body: `{url, render?}`
- **2 credits — NOT charged if no review markup is found.**
- Returns: `{url, rendered, subject, aggregate, count, reviews[]}`

### GET /v1/usage — balance + recent usage
- Returns: `{key_id, balance, recent[]}`

## Pricing

Credit packs, one-time, no subscription:

- Free: 300 credits at signup
- $9: 3,000 credits
- $29: 12,000 credits
- $99: 50,000 credits

Unused credits are refundable within 14 days. Failed API calls are auto-refunded.

## Errors

- `401` — missing or invalid key
- `402` — `insufficient_credits` (buy more at `/#pricing`)
- `429` — `rate_limited` (60 requests/minute per key)
- `502` — upstream fetch/conversion failure (auto-refunded)

## Links

- Full docs: https://forageapi.com/docs.html
- OpenAPI spec: https://forageapi.com/openapi.json
- Contact: willchilcutt@gmail.com