API Reference

FairCrawl API.

Pay-per-use web extraction, search, enrichment, monitoring, and agent workflows. Auth with one Fair Bearer key. No plan or monthly minimum.

Base URL

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

Authentication

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

Authorization: Bearer fc_live_...

Pricing

Standard web scrapes start at $0.0007 per page, with automatic volume discounts. Opt-in large responses and costlier worker methods return their exact cost in _meta.cost. Failed quality gates bill $0. Read the live catalog for all 179 active endpoint prices.

Scrape one URL

POST/v1/crawl/web/scrape

Extract one page synchronously. The request uses a real URL, not an opaque input field.

{
  "url": "https://example.com",
  "format": "markdown",
  "only_main_content": true
}

Returns extracted content plus settled billing and worker metadata:

{
  "title": "Example Domain",
  "content": "This domain is for use in documentation examples...",
  "_meta": {
    "requestId": "crawl_req_...",
    "billing_action": "crawl.single",
    "cost": 0.0007,
    "method": "direct",
    "balance": 42.671164
  }
}

Discover the full API

GET /v1/crawl/endpoints returns the live catalog, prices, required parameters, and supported modes. FairCrawl also exposes site crawl/map, search, research, browser interaction, company enrichment, monitors, watches, freshness tracking, and a plan-before-spend agent.

The product OpenAPI 3.1 file covers 103 registered operations and is generated from the route source, so the contract fails tests if a route drifts.

Errors

  • 402 Payment Required — wallet balance below the action cost. Top up at faircrawl.ai/app.
  • 401 Unauthorized — missing or invalid Bearer token.
  • 422 Unprocessable — the target or extracted result failed its quality contract; it bills $0.
  • 429 Rate Limit — exponential backoff with the Retry-After header.
  • 5xx — upstream or worker failure; unsettled work is voided.

Errors are RFC 9457 application/problem+json. Every authenticated response includes X-RateLimit-Limit, Remaining, and Reset.

Docs, OpenAPI, and MCP

Read the complete guides, download the FairCrawl OpenAPI 3.1 spec, or install @fair-company/mcp. Its 17 typed FairCrawl tools disclose the price in every tool description.