# 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**: companies → `/ai-docs/textToCompanySearch.md`;
   people → `/ai-docs/textToProfileSearch.md`;
   job-description matching → `/ai-docs/jdToProfileSearch.md`.
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`.

**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, use the credit balance plus the representative
   pricing below for the confirmation prompt, 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**. Poll
   `GET /v1/audiences/{audienceId}?apiKey=xxx` until `status === "NORMAL"`.
   [`/ai-docs/buildAudience.md`](/ai-docs/buildAudience.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

Before any chargeable call, either:

- check `GET /v1/get-org-credits?apiKey=xxx`, and
- call the operation's estimate endpoint when one exists, or use the
  representative pricing below for pre-call confirmation and reconcile with
  `chargeInfo` after the response.

Representative per-item costs:

| Operation | Credits |
| --- | --- |
| Work email reveal | 2 |
| Personal email reveal | 2 |
| Phone number reveal | 3 |
| Live profile enrichment | 1 |
| Company search result | 1 |
| People search result | 1 |

Actual per-org pricing may differ; always trust the live estimate.

## Core APIs (canonical per-operation pages)

### 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.
- [`companyCount`](/ai-docs/companyCount.md) / [`peopleSearchCount`](/ai-docs/peopleSearchCount.md) — count-only variants.
- [`textToCompanySearch`](/ai-docs/textToCompanySearch.md) / [`textToProfileSearch`](/ai-docs/textToProfileSearch.md) — NL prompt → resolved structured filters → results. Translates freeform intent (e.g., "VPs at fintech startups in NYC") into typed seniority levels and entity-resolved company identifiers automatically.
- [`jdToProfileSearch`](/ai-docs/jdToProfileSearch.md) — job description → candidate list.

### 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).
- [`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).

### 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.

### 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.
- [`kitchenSinkCompany`](/ai-docs/kitchenSinkCompany.md) — resolve a company from any identifier. Returns comprehensive company data including tech stack, funding, headcount history, and social presence.

### 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)).
- `GET /v1/regions`, `GET /v1/industries` — reference data.

## Common patterns

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

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

### 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.
- **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 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.