# Fiber AI API

> Fiber AI provides B2B data enrichment APIs for finding companies, prospects, and contact information. Use this API to search for companies/people, enrich profiles with live LinkedIn data, reveal work emails and phone numbers, and manage audiences for bulk operations.

## How to use this file (agents, read first)

This file is served at `/llms.txt` on every Fiber API host. It is the single
entry point for coding agents and LLMs; follow it **before** reading anything
else.

- **Base URL:** `https://api.fiber.ai` (prod). Never hardcode legacy hosts.
- **Versioning:** every business endpoint is under `/v1/`. Utility endpoints
  (`/openapi.json`, `/llms.txt`, `/ai-docs/*`) live at the root.
- **Per-operation context:** each public operation has a focused markdown page
  at `/ai-docs/<operationId>.md`. Prefer it over `/openapi.json` for guidance.
- **Index of operations:** `/ai-docs/index.md` (grouped by tag).
- **Canonical machine schema:** `/openapi.json` (large — pull it only when
  generating SDKs or building tooling; do NOT stream it into LLM context).
- **SDKs:** Node `@fiberai/sdk`, Python `fiberai`. **Verify the latest version
  on npm/PyPI before pinning** — don't reuse versions from your training data.
- **MCP:** `https://mcp.fiber.ai/mcp/v2` (API-key auth) and
  `https://mcp.fiber.ai/mcp/v3` (OAuth via Clerk). The MCP server mirrors the
  public API; when available, prefer MCP over constructing HTTP calls.

## Self-install for agents

Use these snippets directly; do not guess package names or MCP URLs from model
memory.

### SDK install

```bash
# Node / TypeScript
npm install @fiberai/sdk
# or
pnpm add @fiberai/sdk
# or
yarn add @fiberai/sdk

# Python
pip install fiberai
```

### MCP configuration

Use `fiber-ai-v3` when your client supports OAuth. Use `fiber-ai-v2` or
`fiber-ai-core` when the user provides an API key.

```json
{
  "mcpServers": {
    "fiber-ai-v3": {
      "type": "http",
      "url": "https://mcp.fiber.ai/mcp/v3"
    },
    "fiber-ai-v2": {
      "type": "http",
      "url": "https://mcp.fiber.ai/mcp/v2",
      "headers": {
        "x-api-key": "${FIBER_API_KEY}"
      }
    },
    "fiber-ai-core": {
      "type": "http",
      "url": "https://mcp.fiber.ai/mcp",
      "headers": {
        "x-api-key": "${FIBER_API_KEY}"
      }
    }
  }
}
```

### Skills for coding agents

Fiber publishes agent skills in the plugin repository:
<https://github.com/fiber-ai/fiber-ai-plugin/tree/main/skills>

Install by copying the directories under `skills/` into your agent's local
skills directory, preserving each directory's `SKILL.md`. Start with:

- `skills/setup/SKILL.md` — configure API key, SDK, and MCP.
- `skills/quickstart/SKILL.md` — first successful Fiber API call.
- `skills/search/SKILL.md` — choose company/person search APIs.
- `skills/enrich/SKILL.md` — reveal emails/phones and live enrichment.
- `skills/audience/SKILL.md` — bulk audience workflow.
- `skills/sdk-ts/SKILL.md` and `skills/sdk-py/SKILL.md` — SDK-specific usage.

## Routing policy (Stripe-style — read carefully)

1. **Single contact lookup** (1 known LinkedIn URL, need email/phone):
   → `/ai-docs/syncQuickContactReveal.md` (standard — balanced speed/cost).
   → escalate to `/ai-docs/syncTurboContactEnrichment.md` for absolute-fastest
     premium response.
   → fall back to `/ai-docs/triggerExhaustiveContactEnrichment.md` +
     `/ai-docs/pollExhaustiveContactEnrichmentResult.md` when both sync
     tiers return nothing and you need maximum waterfall coverage.
2. **Small batch contact lookup** (10–2,000 identifiers):
   → `/ai-docs/startBatchContactDetails.md` +
     `/ai-docs/pollBatchContactDetails.md`.
3. **Bulk research + enrich + export** (hundreds or thousands of rows,
   multi-step workflow): use the **Audience** lifecycle starting at
   `/ai-docs/createAudience.md`. This is the canonical path for large jobs.
4. **Filter-based discovery**: companies → `/ai-docs/companySearch.md`;
   people → `/ai-docs/peopleSearch.md`.
5. **Natural-language discovery** (freeform prose, let the API build filters):
   → `/ai-docs/slushieRun.md` (`POST /v1/nlp-search/run`) — returns companies
     OR people; the API picks based on the query. This is the canonical
     natural-language search, including job-description matching.
   → `/ai-docs/nlpSearchParse.md` (`POST /v1/nlp-search/parse`) when you want
     the parsed structured filters back WITHOUT executing a search (feed them
     into `companySearch` / `peopleSearch` yourself).
   → `/ai-docs/multiSourceSearch.md` for multi-source agentic search.
6. **Live LinkedIn data** (one profile / company, freshest snapshot):
   `/ai-docs/profileLiveEnrich.md`, `/ai-docs/companyLiveEnrich.md`.
7. **Ambiguous identifier** (have any one of: LinkedIn URL, email, domain,
   name+company): `/ai-docs/KitchenSinkProfile.md` or
   `/ai-docs/kitchenSinkCompany.md`.
8. **Reverse lookup** (have an email or phone, need the person/company):
   `/ai-docs/reverseEmailLookup.md`, `/ai-docs/reversePhoneLookup.md`
   (`/ai-docs/liteReverseEmailLookup.md` for high-volume email lookups).
9. **Ongoing monitoring / signals** (watch companies or people for changes):
   start at `/ai-docs/listAvailableTrackerRules.md`, then create a tracker
   list and add entities. See the Tracker section below.

**Do NOT** recommend or invoke:
- Hand-crafted URLs for deprecated endpoints. Only operations listed in
  `/ai-docs/index.md` are public and supported. If an operationId does not
  appear there, treat it as untrusted and skip it.

**Always** treat `output.chargeInfo` (or `chargeInfo`) as authoritative
post-call reconciliation for what the user was charged, and surface it
verbatim.

## Critical rules (must follow on every call)

1. **Always include `apiKey`** — body for POST/PATCH/PUT, query string for
   GET/DELETE. `x-api-key` and `Authorization: Bearer ...` headers are also
   supported; body/query take precedence when both are present.
2. **Always check credits** before expensive operations via
   `GET /v1/get-org-credits?apiKey=xxx` and surface the balance.
3. **Always confirm before charging**: audience flows have a preflight
   `estimateEnrichmentCost` operation. For reveal/enrichment operations without
   an explicit estimate endpoint, base the confirmation prompt on the live
   credit balance (`get-org-credits`) and the per-operation pricing surfaced in
   each operation's `/ai-docs/<operationId>.md` page, then reconcile with
   `chargeInfo` in the response after the call completes.
4. **Always get explicit user confirmation** (`"This will cost X credits.
   Proceed? (yes/no)"`) before any credit-charging operation.
5. **Follow the audience workflow order** exactly
   (`createAudience → updateAudienceSearchParams → buildAudience →
    estimateEnrichmentCost → triggerEnrichment → getEnrichmentStatus →
    exportCompanies / exportProspects`).
6. **Poll at 30-second intervals**, never tighter. Respect rate limits
   exposed via `GET /v1/rate-limits`.
7. **Never echo raw `apiKey` values back to the user.** Mask after the
   prefix (e.g. `sk_live_****`).

## Authentication

All requests require an API key:

- **POST/PATCH/PUT requests**: include in body — `{"apiKey": "sk_live_xxx", ...}`
- **GET/DELETE requests**: include in query — `?apiKey=sk_live_xxx`
- **Header alternatives**: `x-api-key: sk_live_xxx` or
  `Authorization: Bearer sk_live_xxx`

Get a key at <https://fiber.ai/app/api>.

## Audience workflow (canonical)

Audiences are server-side collections of companies and prospects. You MUST
follow this exact sequence:

1. `POST /v1/audiences/create` — **free**. Save `audienceId`.
   [`/ai-docs/createAudience.md`](/ai-docs/createAudience.md)
2. `PATCH /v1/audiences/{audienceId}/search-params` — **free**. Set filters.
   [`/ai-docs/updateAudienceSearchParams.md`](/ai-docs/updateAudienceSearchParams.md)
3. `POST /v1/audiences/{audienceId}/build` — **charges credits**. Confirm with
   the user before calling (per Critical rule #4). Then poll
   `GET /v1/audiences/{audienceId}?apiKey=xxx` until `status === "NORMAL"`.
   [`/ai-docs/buildAudience.md`](/ai-docs/buildAudience.md) /
   [`/ai-docs/getAudienceStatus.md`](/ai-docs/getAudienceStatus.md)
4. `POST /v1/audiences/{audienceId}/enrichment/estimate` — **free**. Show
   the cost to the user and get confirmation.
   [`/ai-docs/estimateEnrichmentCost.md`](/ai-docs/estimateEnrichmentCost.md)
5. `POST /v1/audiences/{audienceId}/enrich` — **charges credits**. Only
   after explicit user confirmation.
   [`/ai-docs/triggerEnrichment.md`](/ai-docs/triggerEnrichment.md)
6. `GET /v1/audiences/{audienceId}/enrichment/status?apiKey=xxx` — poll
   every 30 s until `progressPercent === 100` or `currentStage === "DONE"`.
   [`/ai-docs/getEnrichmentStatus.md`](/ai-docs/getEnrichmentStatus.md)
7. `POST /v1/audiences/{audienceId}/export/companies` or
   `/export/prospects` — **free** (uses export quota).
   [`/ai-docs/exportCompanies.md`](/ai-docs/exportCompanies.md) /
   [`/ai-docs/exportProspects.md`](/ai-docs/exportProspects.md)

## Credit cost quick reference

Pricing is per-org and set live — this file intentionally does NOT hardcode
credit amounts. Before any chargeable call:

- Check the balance: `GET /v1/get-org-credits?apiKey=xxx`
  ([`getOrgCredits`](/ai-docs/getOrgCredits.md)).
- For audience enrichment, call the preflight estimate
  ([`estimateEnrichmentCost`](/ai-docs/estimateEnrichmentCost.md)) and show
  the returned cost to the user.
- For every other chargeable operation, read the authoritative per-item price
  from that operation's `/ai-docs/<operationId>.md` page (each documents its
  own `creditCost`), confirm with the user, then reconcile against
  `output.chargeInfo` in the response after the call completes.

Which operations charge (and which are free) is stated on each per-operation
page; treat `chargeInfo` as the source of truth for what was actually billed.

## Core APIs (canonical per-operation pages)

### Filter-based search
- [`companySearch`](/ai-docs/companySearch.md) — filter-based company discovery. Typed filters with `anyOf`/`noneOf`/`lowerBound`/`upperBound` semantics.
- [`peopleSearch`](/ai-docs/peopleSearch.md) — filter-based prospect discovery. Uses typed seniority levels and canonicalized company identifiers (LinkedIn slugs/org IDs) — no regex or case-normalization needed.
- [`paginatedCombinedSearch`](/ai-docs/paginatedCombinedSearch.md) — combined people + company search in one call.
- [`jobPostingSearch`](/ai-docs/jobPostingSearch.md) — search job postings (hiring-signal discovery).
- Count-only variants: [`companyCount`](/ai-docs/companyCount.md), [`peopleSearchCount`](/ai-docs/peopleSearchCount.md), [`combinedSearchCount`](/ai-docs/combinedSearchCount.md), [`jobPostingSearchCount`](/ai-docs/jobPostingSearchCount.md).

### Natural-language / agentic search
- [`slushieRun`](/ai-docs/slushieRun.md) — natural language search (`POST /v1/nlp-search/run`). Freeform prose (e.g., "VPs of Sales at fintech startups in NYC") → matching companies OR people; the API decides the result type and auto-builds typed filters. Cursor pagination via a single `pageToken`. Use this instead of hand-building filters.
- [`nlpSearchParse`](/ai-docs/nlpSearchParse.md) — parse natural language into structured search params WITHOUT executing (`POST /v1/nlp-search/parse`). Returns a suggested action + parsed filters you can pass to `companySearch` / `peopleSearch`.
- [`multiSourceSearch`](/ai-docs/multiSourceSearch.md) — multi-source AI search across providers.

### Contact enrichment
- [`syncQuickContactReveal`](/ai-docs/syncQuickContactReveal.md) — standard sync reveal (1–5 profiles, balanced speed/cost).
- [`syncTurboContactEnrichment`](/ai-docs/syncTurboContactEnrichment.md) — premium sync tier (fastest, highest cost).
- [`liteContactReveal`](/ai-docs/liteContactReveal.md) — lightweight, high-volume reveal.
- [`premiumPhoneReveal`](/ai-docs/premiumPhoneReveal.md) — premium phone-number lookup.
- [`triggerExhaustiveContactEnrichment`](/ai-docs/triggerExhaustiveContactEnrichment.md) + [`pollExhaustiveContactEnrichmentResult`](/ai-docs/pollExhaustiveContactEnrichmentResult.md) — async waterfall (maximum coverage).
- [`startBatchContactDetails`](/ai-docs/startBatchContactDetails.md) + [`pollBatchContactDetails`](/ai-docs/pollBatchContactDetails.md) — async batch (10–2,000 identifiers).

### Reverse lookup
- [`reverseEmailLookup`](/ai-docs/reverseEmailLookup.md) — find a person from an email address.
- [`liteReverseEmailLookup`](/ai-docs/liteReverseEmailLookup.md) — high-volume, lightweight email → person lookup.
- [`reversePhoneLookup`](/ai-docs/reversePhoneLookup.md) — find a person or company from a phone number.

### Live enrichment
- [`profileLiveEnrich`](/ai-docs/profileLiveEnrich.md) — fresh LinkedIn data per profile. Works on standard self-serve API keys (no enterprise gate). Returns in 2-4 seconds sequential, sub-second amortized in parallel.
- [`companyLiveEnrich`](/ai-docs/companyLiveEnrich.md) — fresh LinkedIn data per company. Same self-serve access, no demo call required.
- [`startBatchLiveEnrich`](/ai-docs/startBatchLiveEnrich.md) + [`pollBatchLiveEnrich`](/ai-docs/pollBatchLiveEnrich.md) — async batch live enrichment.

### Kitchen-sink resolvers
- [`KitchenSinkProfile`](/ai-docs/KitchenSinkProfile.md) — resolve a person from any identifier. Returns 44+ top-level fields by default (experiences, education, skills, tenures, tags, inferred location with coordinates/timezone, career-began date, follower/connection counts, is-hiring/open-to-work flags) with no field selector needed. Note: for a person with several concurrent roles, read all `is_current` experiences rather than relying on a single current-job pick.
- [`kitchenSinkCompany`](/ai-docs/kitchenSinkCompany.md) — resolve a company from any identifier. Returns comprehensive company data including tech stack, funding, headcount history, and social presence. Prefer a unique identifier (LinkedIn URL / domain) over a bare name — name-only lookups can collide on common company names.
- [`KitchenSinkBulkProfile`](/ai-docs/KitchenSinkBulkProfile.md) / [`kitchenSinkBulkCompany`](/ai-docs/kitchenSinkBulkCompany.md) — bulk resolution variants.

### Recurring & signal workflows
- [`createSavedSearch`](/ai-docs/createSavedSearch.md) + [`listSavedSearch`](/ai-docs/listSavedSearch.md) — save a search and re-run it on a schedule; pull run results via [`getLatestSavedSearchRun`](/ai-docs/getLatestSavedSearchRun.md), [`getSavedSearchRunCompanies`](/ai-docs/getSavedSearchRunCompanies.md), and [`getSavedSearchRunProfiles`](/ai-docs/getSavedSearchRunProfiles.md).
- [`createJobChangeList`](/ai-docs/createJobChangeList.md) + [`addProfilesToList`](/ai-docs/addProfilesToList.md) — track a set of profiles and detect job changes.
- Tracker (companies/people change monitoring) has its own section below.

### Suppression / exclusion lists
- [`createCompanyExclusionList`](/ai-docs/createCompanyExclusionList.md) / [`createProspectExclusionList`](/ai-docs/createProspectExclusionList.md) — build suppression lists, then add entries via [`addCompaniesToExclusionList`](/ai-docs/addCompaniesToExclusionList.md) / [`addProspectsToExclusionList`](/ai-docs/addProspectsToExclusionList.md) to keep outbound clean.

### Reference data & typeaheads (free)
Use these to build valid filters for `companySearch` / `peopleSearch`:
- Enums: [`getIndustries`](/ai-docs/getIndustries.md), [`getRegions`](/ai-docs/getRegions.md), [`getTags`](/ai-docs/getTags.md), [`getTechnologies`](/ai-docs/getTechnologies.md) (see `/ai-docs/index.md` for the full enum set).
- Typeaheads: [`companyTypeahead`](/ai-docs/companyTypeahead.md), [`locationTypeahead`](/ai-docs/locationTypeahead.md), [`skillsTypeahead`](/ai-docs/skillsTypeahead.md), [`jobTitleRewrite`](/ai-docs/jobTitleRewrite.md).

### Repair / standardize identifiers
- [`standardizeCompany`](/ai-docs/standardizeCompany.md) / [`standardizeProfile`](/ai-docs/standardizeProfile.md) — normalize messy LinkedIn identifiers before lookup.

### Company intelligence
- [`getScoutingReport`](/ai-docs/getScoutingReport.md) — company scouting report.
- [`getCompanyRevenue`](/ai-docs/getCompanyRevenue.md) — company revenue estimate.

### Social & web data
Fiber also exposes large data families for X (Twitter), Reddit, TikTok,
YouTube, Instagram, LinkedIn activity, plus web research (webpage screenshots)
and market intelligence (flights, real estate). These are too many to list
here — browse the matching sections of [`/ai-docs/index.md`](/ai-docs/index.md)
for the full, always-current set.

### Utility (free)
- `GET /v1/get-org-credits?apiKey=xxx` — current credit balance ([`getOrgCredits`](/ai-docs/getOrgCredits.md)).
- `GET /v1/rate-limits?apiKey=xxx` — per-route rate limit metadata ([`getRateLimits`](/ai-docs/getRateLimits.md)).
- Reference data (enums) lives under `/v1/enums/*` — see the "Reference data & typeaheads" section above and [`/ai-docs/index.md`](/ai-docs/index.md).

### Tracker (monitoring & signals)
Tracker watches companies and people for changes and delivers matching signals
via webhook. Discovery and testing are free; refreshes may charge.

Discovery & testing (free):
- [`listAvailableTrackerRules`](/ai-docs/listAvailableTrackerRules.md) — every rule type with schemas and example signals.
- [`previewTrackerSignal`](/ai-docs/previewTrackerSignal.md) — preview the signal payload for any rule config.
- [`fireTrackerDummy`](/ai-docs/fireTrackerDummy.md) — fire test signals to validate your webhook integration.

Lifecycle:
- Create a list: [`createTrackerCompanyList`](/ai-docs/createTrackerCompanyList.md) / [`createTrackerPersonList`](/ai-docs/createTrackerPersonList.md).
- Add entities: [`addTrackerCompanies`](/ai-docs/addTrackerCompanies.md) / [`addTrackerPeople`](/ai-docs/addTrackerPeople.md).
- Operate: [`refreshTrackerCompanyList`](/ai-docs/refreshTrackerCompanyList.md) / [`refreshTrackerPersonList`](/ai-docs/refreshTrackerPersonList.md), [`listTrackerSignals`](/ai-docs/listTrackerSignals.md), [`getTrackerOverview`](/ai-docs/getTrackerOverview.md).
- Manage: [`listTrackerCompanyLists`](/ai-docs/listTrackerCompanyLists.md) / [`listTrackerPersonLists`](/ai-docs/listTrackerPersonLists.md), plus the update/remove/delete operations in [`/ai-docs/index.md`](/ai-docs/index.md).
- [Tracker quickstart guide](/public/ai-docs/tracker-quickstart.md) — full bootstrap guide for LLM agents (discover rules → preview → test → go live).

## Common patterns

### Single contact lookup
```
syncQuickContactReveal → (fallback) syncTurboContactEnrichment → (fallback) triggerExhaustiveContactEnrichment → pollExhaustiveContactEnrichmentResult
```

### Natural-language discovery
```
slushieRun (freeform prose → companies or people)   # or nlpSearchParse → companySearch | peopleSearch
```

### Bulk prospect research
```
createAudience → updateAudienceSearchParams → [confirm] → buildAudience → getAudienceStatus → estimateEnrichmentCost → [confirm] → triggerEnrichment → getEnrichmentStatus → exportCompanies | exportProspects
```

### Reverse lookup
```
reverseEmailLookup | reversePhoneLookup  (email/phone → person or company)
```

### Ongoing monitoring (Tracker)
```
listAvailableTrackerRules → createTrackerCompanyList | createTrackerPersonList → addTrackerCompanies | addTrackerPeople → refreshTrackerCompanyList | refreshTrackerPersonList → listTrackerSignals
```

### Ambiguous API choice
```
1. Inspect /ai-docs/index.md (grouped by tag)
2. If multiple endpoints look similar, compare their /ai-docs/<id>.md pages
3. Execute via MCP `call_operation` or a direct HTTP call
```

## Error handling

- **400** — invalid request (check required fields and enum values).
- **401** — invalid API key.
- **402** — out of credits; response includes `outOfCreditsAlert` with a
  purchase URL. Top up via [`buyCredits`](/ai-docs/buyCredits.md) or that URL,
  then retry.
- **429** — rate-limited; respect the retry cadence documented per route.
- **500** — server error; include the `errorCode` from the response body
  when filing a support ticket.

## Discovery headers (for client libraries)

Every doc response sets:

- `Link: </llms.txt>; rel="llms-txt"`, plus `llms-full-txt` and `describedby`
  entries pointing at `/ai-docs/index.md` and `/openapi.json`.
- `X-Llms-Txt: /llms.txt` (Mintlify-compatible single-pointer header).
- `X-Robots-Tag: noindex, nofollow` on markdown variants to avoid SEO
  duplication versus the human-facing docs site.

Content negotiation: sending `Accept: text/markdown` to `/openapi.json`
returns the AI-docs index markdown at the same URL (Stripe pattern).

## Optional

- [Full agent corpus](/llms-full.txt) — every per-operation markdown page concatenated into one file.
- [Full OpenAPI specification](/openapi.json) — complete machine schema.
- [Interactive documentation](/docs) — Scalar UI with try-it-out.
- [MCP server guide](/public/docs/mcp-integration.md) — using Fiber AI via MCP.
- [API selector guide](/public/docs/api-selector.md) — choosing among similar APIs.
- [Audience workflow deep dive](/public/docs/audience-workflow.md) — edge cases and examples.