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

## Quick Start for LLM Agents

If you know nothing about Fiber yet, start here:

1. **Audience workflows (recommended for large tasks)**  
   - Read: `/public/docs/audience-workflow.md`  
   - Use when the user wants to research + enrich + export many companies/prospects.
2. **Company & people search (discovery)**  
   - Read: `/public/docs/company-search.md` and `/public/docs/people-search.md`  
   - Use to find targets before moving them into an audience.
3. **Enrichment (contacts + live LinkedIn)**  
   - Read: `/public/docs/contact-enrichment.md` and `/public/docs/live-enrichment.md`  
   - Use for emails/phones and fresh LinkedIn data on small sets of entities.
4. **MCP integrations**  
   - Read: `/public/docs/mcp-integration.md`  
   - Use to discover endpoints and call operations safely via MCP tools.
5. **API selector (for similar APIs)**  
   - Read: `/public/docs/api-selector.md`  
   - Use when multiple APIs look relevant (e.g., company search vs kitchen-sink).

Then follow the rules below for every call.

## Instructions for LLM Agents

**CRITICAL RULES - You MUST follow these:**

1. **ALWAYS include apiKey** - Every request needs `apiKey` in query params (GET/DELETE) or request body (POST/PATCH/PUT)
2. **ALWAYS check credits first** - Call `GET /v1/credits?apiKey=xxx` before expensive operations to show user their balance
3. **ALWAYS estimate before charging** - Call estimate endpoints and show cost BEFORE running expensive operations
4. **ALWAYS get user confirmation** - Ask "This will cost X credits. Proceed? (Yes/No)" before any credit-charging operation
5. **FOLLOW workflow order** - Audience operations MUST follow the exact sequence below
6. **NEVER skip confirmation** - Users must approve costs before you trigger enrichment or build operations
7. **HANDLE async operations** - Poll status endpoints every 30 seconds until `progressPercent = 100` or status is `COMPLETED`

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

## Audience Workflow (MUST Follow This Order)

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

1. **Create Audience** (FREE): `POST /v1/audiences/create`
   - Input: `name`, `creationMethod` (usually "NORMAL")
   - Returns: `audienceId` (save this for all subsequent calls)

2. **Set Search Filters** (FREE): `PATCH /v1/audiences/{audienceId}/search-params`
   - Define company filters: industry, location, size, funding, keywords
   - Define prospect filters: job title, seniority, department

3. **Build Audience** (CHARGES CREDITS): `POST /v1/audiences/{audienceId}/build`
   - ⚠️ CHARGES CREDITS - Ask user for confirmation first
   - Populates audience with matching companies and prospects
   - WAIT: Poll `GET /v1/audiences/{audienceId}?apiKey=xxx` until status becomes "NORMAL"

4. **Estimate Enrichment Cost** (FREE): `POST /v1/audiences/{audienceId}/enrichment/estimate`
   - Returns detailed cost breakdown by operation type
   - SHOW THIS TO USER and ask for confirmation before proceeding

5. **Trigger Enrichment** (CHARGES CREDITS): `POST /v1/audiences/{audienceId}/enrich`
   - ⚠️ ONLY CALL AFTER USER CONFIRMS COST
   - Returns: `enrichmentId`

6. **Poll Enrichment Status** (FREE): `GET /v1/audiences/{audienceId}/enrichment/status?apiKey=xxx`
   - Poll every 30 seconds
   - Continue until `progressPercent = 100` or `currentStage = "DONE"`

7. **Export Data** (FREE, uses quota): `POST /v1/audiences/{audienceId}/export/companies` or `POST /v1/audiences/{audienceId}/export/prospects`
   - Triggers CSV export
   - If `userEmail` provided, CSV links sent via email

- [Audience Workflow Complete Guide](/public/docs/audience-workflow.md): Detailed examples and edge cases

## Credit Costs

Before expensive operations, ALWAYS:
1. Call `GET /v1/credits?apiKey=xxx` to check available credits
2. Call the relevant estimate endpoint
3. Show cost to user and get confirmation

**Common costs per item:**
| 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 |

## Core APIs

### Search APIs
- [Company Search](/public/docs/company-search.md): Find companies by filters - Use for discovery before creating audiences
- [People Search](/public/docs/people-search.md): Find prospects by role - Use to discover individuals before enrichment

### Enrichment APIs
- [Contact Enrichment](/public/docs/contact-enrichment.md): Reveal emails/phones - Use sync for 1-5 contacts, batch for 10+, audience for bulk
- [Live Enrichment](/public/docs/live-enrichment.md): Latest LinkedIn data - Use for small sets needing fresh data (1-10 entities)

### Utility APIs
- `GET /v1/credits?apiKey=xxx`: Check credit balance (FREE)
- `GET /v1/regions?apiKey=xxx`: Get list of regions/countries (FREE)
- `GET /v1/industries?apiKey=xxx`: Get list of industries (FREE)

## Common Patterns

### Pattern 1: Quick Contact Lookup
```
1. POST /v1/individual-reveal/sync - Get email for a single LinkedIn URL
```

### Pattern 2: Bulk Prospect Research
```
1. Create audience → 2. Set filters → 3. Build → 4. Estimate → 5. Confirm → 6. Enrich → 7. Export
```

### Pattern 3: Company Research
```
1. POST /v1/company-search - Search for companies
2. POST /v1/linkedin-live-fetch/company/single - Get live LinkedIn data
```

### Pattern 4: Ambiguous API Choice
```
1. Use search_endpoints with the user's intent (and constraints when available)
2. If advanced fields are needed, call get_endpoint_details_full
3. Execute the selected operation
```

## Error Handling

- **401**: Invalid API key
- **400**: Invalid request (check required fields)
- **429**: Rate limited (wait and retry)
- **500**: Server error (include `errorCode` in support request)

## Optional

- [Full OpenAPI Specification](/openapi.json): Complete API schema for all endpoints
- [Interactive API Documentation](/docs): Scalar UI with try-it-out functionality
- [MCP Server Guide](/public/docs/mcp-integration.md): Using Fiber AI with Model Context Protocol
- [API Selector Guide](/public/docs/api-selector.md): Choosing the best API among similar options