API Reference

FairCrawl API.

Pay-per-scrape REST API. Auth with a Bearer token. Every endpoint returns a hold ID — operations settle on success and void on failure.

Base URL

https://api.faircompany.ai/v1/crawl

Authentication

All requests use a Bearer token. Get one from faircrawl.ai/app.

Authorization: Bearer fair_live_...

Pricing

Every scrape costs $0.0007 per scrape. The cost is held against your wallet at request time, settled on success, and voided on failure.

Endpoints

POST/v1/crawl/web/scrape

Create a new scrape.

{
  "input": "...",
  "metadata": { "ref": "your-internal-id" }
}

Returns the resource and a hold_id:

{
  "id": "scrape_01HX...",
  "status": "queued",
  "hold_id": "hold_01HX...",
  "estimated_cost_usd": "$0.0007"
}

GET/v1/crawl/jobs/:id

Fetch a scrape by ID. Returns full state including settled cost.

GET/v1/crawl/jobs

List scrapes. Supports cursor pagination, created_after, status, and metadata filters.

DELETE/v1/crawl/jobs/:id

Cancel a queued scrape. Held funds are released. Already-settled scrapes cannot be cancelled.

POST/v1/crawl/webhooks

Register a webhook for scrape.created, scrape.completed, scrape.failed events. Signed with HMAC-SHA256.

Errors

  • 402 Payment Required — wallet balance below the hold amount. Top up at faircrawl.ai/app.
  • 401 Unauthorized — missing or invalid Bearer token.
  • 422 Unprocessable — input failed validation.
  • 429 Rate Limit — exponential backoff with the Retry-After header.
  • 5xx — held funds are auto-voided after 5 minutes if no settlement arrives.

SDKs

Typed clients available for TypeScript / Python via @fair/sdk (npm) and fair-sdk (PyPI). Full OpenAPI spec at api.faircompany.ai/openapi.