Skip to content
FairCrawl Docs

TypeScript SDK

faircrawl is the first-party TypeScript SDK. It wraps the live REST surface closely and exports both a high-level FairCrawl class and a lower-level FairCrawlClient for raw paths.

Install

Terminal window
npm install faircrawl
# or
pnpm add faircrawl
# or
bun add faircrawl

Initialize

import { FairCrawl } from "faircrawl";


const fc = new FairCrawl({
  apiKey: process.env.FAIRCRAWL_API_KEY!,
  baseUrl: "https://api.faircompany.ai/v1",
});

Core namespaces

  • fc.scrape(...)
  • fc.scrape.crawl(...)
  • fc.map(...)
  • fc.interact(...)
  • fc.research(...)
  • fc.agent(...)
  • fc.enrich.company(...)
  • fc.enrich.contact(...)
  • fc.enrich.contacts(...)
  • fc.freshness.*
  • fc.twitter.*, fc.tiktok.*, fc.instagram.*, fc.youtube.*, fc.reddit.*, fc.linkedin.*, fc.facebook.*, fc.bluesky.*, fc.threads.*, fc.truthsocial.*, fc.pinterest.*, fc.twitch.*, fc.snapchat.*, fc.linktree.*
  • fc.endpoints(), fc.jobs(), fc.usage()

Typical flow

const map = await fc.map({
  url: "https://docs.stripe.com",
  limit: 50,
  search: "checkout",
});


const firstPage = map.urls[0];
if (firstPage) {
  const doc = await fc.scrape({
    url: firstPage,
    format: "markdown",
    only_main_content: true,
  });


  console.log(doc.text);
}

Browser and agent workflows

const session = await fc.interact({
  url: "https://example.com/login",
  actions: [
    { type: "fill", selector: "#email", value: "user@example.com" },
    { type: "fill", selector: "#password", value: "secret" },
    { type: "click", selector: 'button[type="submit"]' },
    { type: "wait_for_selector", selector: ".dashboard", timeout_ms: 10000 },
    { type: "extract", format: "markdown" },
  ],
});


const answer = await fc.agent({
  instruction: "Find the pricing page linked from the current dashboard and summarize it.",
  max_steps: 6,
  budget_usd: 0.05,
});

Raw client access

Use FairCrawlClient when you want a raw path that is not wrapped in the high-level class yet.

import { FairCrawlClient } from "faircrawl";


const client = new FairCrawlClient({
  apiKey: process.env.FAIRCRAWL_API_KEY!,
});


const linkedinCompany = await client.get("/crawl/linkedin/company", {
  url: "https://www.linkedin.com/company/microsoft/",
});


console.log(linkedinCompany);

Freshness and platform clients

await fc.freshness.registerSource({
  entity_id: "company_stripe",
  entity_type: "company",
  source_key: "pricing_page",
  source_url: "https://stripe.com/pricing",
  refresh_cadence: "7 days",
  priority: 90,
});


const dashboard = await fc.freshness.dashboard();
const twitterProfile = await fc.twitter.profile({ handle: "openai" });