Official Python SDK for the Fiber AI API. Auto-generated from the OpenAPI specification.
Do NOT guess operation names — read the canonical agent-facing docs first:
- Routing index + critical rules: https://api.fiber.ai/llms.txt
- Per-operation markdown:
https://api.fiber.ai/ai-docs/<operationId>.md(e.g.companySearch,syncQuickContactReveal,triggerExhaustiveContactEnrichment) - Operation index: https://api.fiber.ai/ai-docs/index.md
- Full corpus (single file): https://api.fiber.ai/llms-full.txt
- OpenAPI spec:
https://api.fiber.ai/openapi.json(sendAccept: text/markdownfor the agent-friendly variant) - MCP server:
https://mcp.fiber.ai/mcp/v2(also see fiber-ai/mcp)
See also llms.txt in this repo for the SDK-specific quickstart.
- Installation
- Quick start
- Authentication
- Async usage
- Detailed responses
- Error handling
- Pagination
- Credit tracking
- Available API modules
- Configuration
- Choosing the right operation
- Links
pip install fiberaiRequires Python 3.11 or newer. Runtime dependencies: httpx, attrs, python-dateutil.
import os
from fiberai import Client
from fiberai.api.search import company_search
from fiberai.models import CompanySearchBody
from fiberai.models.company_search_response_200 import CompanySearchResponse200
client: Client = Client(base_url="https://api.fiber.ai")
body: CompanySearchBody = CompanySearchBody.from_dict({
"apiKey": os.environ["FIBER_API_KEY"],
"searchParams": {
"industriesV2": {"anyOf": ["Software"]},
"employeeCountV2": {
"lowerBoundExclusive": 50,
"upperBoundInclusive": 500,
},
},
"pageSize": 10,
})
result = company_search.sync(client=client, body=body)
if isinstance(result, CompanySearchResponse200):
for company in result.output.data:
print(company.to_dict())
else:
# 4xx / 5xx — `result` is one of CompanySearchResponse{400,401,402,403,404,429,500}
print("error:", result.to_dict() if result else "no body")Field names matter. The body keys are camelCase JSON (
apiKey,searchParams,industriesV2,employeeCountV2) — not the snake-case Python attributes.from_dictaccepts the same shape the HTTP API accepts. Seehttps://api.fiber.ai/ai-docs/companySearch.mdfor the full filter list.
Every generated operation takes your key as a required apiKey field (in the request body, or as the api_key argument for GET operations), so the plain Client is all you need:
from fiberai import Client
client: Client = Client(base_url="https://api.fiber.ai")AuthenticatedClient is also exported. It sends the key as an Authorization: Bearer header, which the API accepts too, but the generated models still require apiKey, so it adds nothing over Client.
Get an API key at https://fiber.ai/app/api. Production keys start with sk_live_, sandbox keys with sk_test_. Treat them like passwords — never commit them; load from os.environ or a secrets manager.
Every operation ships sync and async variants. The signature, body model, and return type are identical; only the function name changes (sync → asyncio, sync_detailed → asyncio_detailed):
import asyncio
import os
from fiberai import Client
from fiberai.api.search import company_search
from fiberai.models import CompanySearchBody
from fiberai.models.company_search_response_200 import CompanySearchResponse200
async def main() -> None:
client: Client = Client(base_url="https://api.fiber.ai")
body: CompanySearchBody = CompanySearchBody.from_dict({
"apiKey": os.environ["FIBER_API_KEY"],
"searchParams": {"industriesV2": {"anyOf": ["Software"]}},
"pageSize": 10,
})
result = await company_search.asyncio(client=client, body=body)
if isinstance(result, CompanySearchResponse200):
print(f"got {len(result.output.data)} companies")
asyncio.run(main())For long-running scripts, reuse a single Client (or use it as an async with context manager) so the underlying httpx.AsyncClient connection pool is shared across calls.
Use sync_detailed / asyncio_detailed when you need the HTTP status code, headers, or raw body alongside the parsed object:
from fiberai.api.search import company_search
from fiberai.types import Response
response: Response = company_search.sync_detailed(client=client, body=body)
print(response.status_code) # http.HTTPStatus
print(response.headers) # MutableMapping[str, str]
print(response.content) # raw bytes
print(response.parsed) # the same object sync() returns (or None)response.headers is where you read Retry-After for 429s, X-Request-Id for support tickets, etc.
The non-detailed call returns a discriminated union covering every documented status. Type-narrow with isinstance to dispatch:
from fiberai.api.search import company_search
from fiberai.models.company_search_response_200 import CompanySearchResponse200
from fiberai.models.company_search_response_401 import CompanySearchResponse401
from fiberai.models.company_search_response_402 import CompanySearchResponse402
from fiberai.models.company_search_response_429 import CompanySearchResponse429
result = company_search.sync(client=client, body=body)
if isinstance(result, CompanySearchResponse200):
companies = result.output.data
elif isinstance(result, CompanySearchResponse401):
raise RuntimeError("invalid API key")
elif isinstance(result, CompanySearchResponse402):
raise RuntimeError("out of credits — top up at https://fiber.ai/app/billing")
elif isinstance(result, CompanySearchResponse429):
# Rate limited — sync_detailed exposes the Retry-After header
raise RuntimeError("rate limited; back off and retry")
else:
raise RuntimeError(f"unexpected error: {result}")For undocumented status codes (e.g. transient 502/503 from upstream), the SDK returns None by default. Set raise_on_unexpected_status=True to surface them as exceptions instead:
from fiberai import Client
from fiberai import errors
client: Client = Client(
base_url="https://api.fiber.ai",
raise_on_unexpected_status=True,
)
try:
result = company_search.sync(client=client, body=body)
except errors.UnexpectedStatus as exc:
print(exc.status_code, exc.content[:200])httpx.TimeoutException (request exceeded timeout) and httpx.ConnectError (network) propagate untouched.
Search responses include output.next_cursor. Pass it back as the next request's cursor to walk the full result set:
import os
from typing import Optional
from fiberai.api.search import company_search
from fiberai.models import CompanySearchBody
from fiberai.models.company_search_response_200 import CompanySearchResponse200
cursor: Optional[str] = None
all_companies: list[dict] = []
while True:
body: CompanySearchBody = CompanySearchBody.from_dict({
"apiKey": os.environ["FIBER_API_KEY"],
"searchParams": {"industriesV2": {"anyOf": ["Software"]}},
"pageSize": 100,
**({"cursor": cursor} if cursor else {}),
})
result = company_search.sync(client=client, body=body)
if not isinstance(result, CompanySearchResponse200):
raise RuntimeError(f"search failed: {result}")
all_companies.extend(c.to_dict() for c in result.output.data)
cursor = result.output.next_cursor or None
if not cursor:
breakThe same pattern applies to people_search, investor_search, investment_search, and job_posting_search.
Every successful response carries a charge_info object documenting exactly how many credits were consumed and why. Persist it for billing reconciliation rather than deriving cost from result counts:
result = company_search.sync(client=client, body=body)
if isinstance(result, CompanySearchResponse200):
print(result.charge_info.to_dict())
# { "method": "...", "creditsCharged": 7.0 }To check your balance before kicking off a large batch:
import os
from fiberai.api.account import get_org_credits
from fiberai.models.get_org_credits_response_200 import GetOrgCreditsResponse200
credits = get_org_credits.sync(client=client, api_key=os.environ["FIBER_API_KEY"])
if isinstance(credits, GetOrgCreditsResponse200):
print(credits.to_dict())
get_org_creditsis aGETrequest that takes the API key as a query-string kwarg rather than a body. A handful of read-only utility operations follow this convention; the per-operation docs at https://api.fiber.ai/ai-docs/index.md note which.
The SDK is organized by API domain. The endpoint path corresponding to each operation lives in the module's _get_kwargs helper if you need to grep for it.
| Module | What's in it |
|---|---|
fiberai.api.search |
company_search, people_search, investor_search, investment_search, job_posting_search (+ _count variants), and the combined-search trio (combined_search, sync_combined_search, poll_combined_search) |
fiberai.api.live_fetch |
Real-time LinkedIn fetches: profile_live_enrich, company_live_enrich, plus posts/comments/reactions for both profiles and companies |
fiberai.api.contact_details |
Email + phone reveal: sync_contact_enrichment (sync), trigger_contact_enrichment + poll_contact_enrichment_result (async waterfall), start_batch_contact_enrichment + poll_batch_contact_enrichment (batch) |
fiberai.api.kitchen_sink |
Bulk company/profile lookup by identifier: kitchen_sink_company, kitchen_sink_profile, kitchen_sink_bulk_company, kitchen_sink_bulk_profile |
fiberai.api.google_maps |
Google Maps business search: google_maps_search, poll_google_maps_results, check_google_maps_results |
fiberai.api.ai_research |
AI-powered domain lookup: domain_lookup_trigger, domain_lookup_polling |
fiberai.api.agentic_search |
LLM-powered text-to-search: text_to_company_search, text_to_profile_search, text_to_combined_search |
fiberai.api.exclusions |
Manage company and prospect exclusion lists (create / add / remove / list / delete) |
fiberai.api.saved_search |
Saved search lifecycle: create, list, run, fetch run results |
fiberai.api.email_lookup |
reverse_email_lookup (email → LinkedIn profile) |
fiberai.api.validation |
email_bounce_detection |
fiberai.api.account |
get_org_credits |
fiberai.api.enums |
Enum value lookups: industries, accelerators, NAICS codes, regions, languages, tags, time zones |
fiberai.api.typeaheads |
company_typeahead, location_typeahead |
fiberai.api.company_info |
bulk_company_logos |
fiberai.api.coming_soon |
Beta endpoints: start_local_business_search, poll_local_business_search |
fiberai.api.utility |
health_check, get_open_api (no API key required) |
If you want LinkedIn-URL → company details, use
live_fetch.company_live_enrich(notcompany_info). Thecompany_infomodule currently only exposes bulk logo fetching.
The Python SDK lags slightly behind the API in a few places — notably the new syncQuickContactReveal / syncTurboContactEnrichment / triggerExhaustiveContactEnrichment operation names, which still ship under their older sync_contact_enrichment / trigger_contact_enrichment module names here. See llms.txt for the workaround (direct httpx call) until the next regeneration.
Client accepts the same kwargs as httpx.Client plus a few of its own:
import httpx
import ssl
from fiberai import Client
client: Client = Client(
base_url="https://api.fiber.ai",
timeout=httpx.Timeout(60.0, connect=10.0),
headers={"X-Custom-Header": "value"},
cookies={"session": "..."},
verify_ssl=True, # bool | str | ssl.SSLContext
follow_redirects=False,
raise_on_unexpected_status=False, # see "Error handling"
httpx_args={"http2": True}, # forwarded to httpx.Client(...)
)Useful helpers (each returns a new Client rather than mutating in place):
client_with_auth: Client = client.with_headers({"X-Trace-Id": "abc123"})
client_with_timeout: Client = client.with_timeout(httpx.Timeout(120.0))For long-running services, use the client as a context manager so connection pools are torn down cleanly:
with Client(base_url="https://api.fiber.ai") as client:
result = company_search.sync(client=client, body=body)
# or, async:
async with Client(base_url="https://api.fiber.ai") as client:
result = await company_search.asyncio(client=client, body=body)Several Fiber operations cover overlapping use cases (e.g. three different ways to reveal contact info, two ways to search). The trade-offs (cost, latency, coverage, quality) live in the per-operation docs, not in this README:
| Use case | Read this |
|---|---|
| Sync vs turbo vs exhaustive contact reveal | https://api.fiber.ai/llms.txt and the relevant ai-docs/<operationId>.md |
| When to use audiences vs ad-hoc search | https://api.fiber.ai/ai-docs/index.md |
| Rate limits and credit cost per operation | Stamped at the top of each ai-docs/<operationId>.md page |
When in doubt, prefer reading these over guessing — the routing rules change faster than this SDK regenerates.
- Fiber AI — main website
- API documentation — full API docs
- Per-operation reference — every operation, its schema, its cost
- TypeScript SDK — TypeScript/JavaScript SDK
- MCP server — expose Fiber operations as MCP tools to your agent
- Get an API key
- Issues — bug reports and feature requests
MIT — see LICENSE for details.