> ## Documentation Index
> Fetch the complete documentation index at: https://bavlio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Full OpenAPI 3.1 specification for the Bavlio API. 190+ endpoints across campaigns, leads, sender profiles, personalization, BaviMail proxy, and more.

The Bavlio API is described by an OpenAPI 3.1 specification. The endpoint pages in this section are auto-generated from the live spec at [`api.bavlio.com/openapi.json`](https://api.bavlio.com/openapi.json) — they're always in sync with what's deployed.

<Tip>
  Looking for a quick-start? Start with [Quickstart](/quickstart) — auth, first call, and error handling in 5 minutes. This reference is the comprehensive map; the quickstart is the ramp.
</Tip>

## Spec sources

<CardGroup cols={2}>
  <Card title="Live OpenAPI spec" icon="file-code" href="https://api.bavlio.com/openapi.json">
    `api.bavlio.com/openapi.json` — always-fresh production contract. Point your code generator at this.
  </Card>

  <Card title="Browse interactively" icon="terminal" href="/api-reference/introduction">
    Use the sidebar in this section to browse every endpoint. Try-It console included for authenticated calls.
  </Card>
</CardGroup>

## Endpoint groups

The API surface clusters into thirteen domains. Click any path family below to jump to the relevant endpoint pages.

<AccordionGroup>
  <Accordion title="Authentication & Identity" icon="key">
    `/api/v1/auth/*`, `/api/v1/api-keys/*` — Verify your token, fetch your user profile, manage API keys.

    **Note:** API key creation requires a Supabase JWT, not an API key (prevents key-from-key minting).
  </Accordion>

  <Accordion title="Campaigns" icon="megaphone">
    `/api/v1/campaigns/*` — Create, list, launch, pause, resume campaigns. Per-campaign stats, leads, events, playground drafts. \~25 endpoints.
  </Accordion>

  <Accordion title="Email Finder & Verification" icon="envelope-magnifying-glass">
    `/api/v1/email-finder/*`, `/api/v1/email-verification/*` — Search by name+company, verify deliverability, bulk verification.

    **Note:** `find` and `verify` endpoints are async — they return `job_id`; poll for results.
  </Accordion>

  <Accordion title="Lead Finder" icon="user-magnifying-glass">
    `/api/v1/lead-finder/*` — Batch resolve names → LinkedIn profile URLs. Async with status polling.
  </Accordion>

  <Accordion title="Sender Profiles" icon="id-card">
    `/api/v1/sender-profiles/*` — Manage up to 5 sender profiles per user. Named prompts (per-profile saved instructions) for AI personalization.
  </Accordion>

  <Accordion title="Templates" icon="file-lines">
    `/api/v1/templates/*` — Reusable email templates with variable substitution.
  </Accordion>

  <Accordion title="Suppression / DNC" icon="ban">
    `/api/v1/suppression/*` — Do-not-contact list management.
  </Accordion>

  <Accordion title="Datasets & Extractions" icon="database">
    `/api/v1/datasets/*`, `/api/v1/user-extractions/*` — Stored data sources from CSV, Excel, Google Sheets, and Chrome extension extractions.
  </Accordion>

  <Accordion title="Personalization" icon="wand-magic-sparkles">
    `/api/v1/personalize/*` — Submit single or bulk personalization jobs. Async via ARQ — poll job status. Generation history endpoints expose run-level audit trail.
  </Accordion>

  <Accordion title="Agent (Bavi chat)" icon="message-bot">
    `/api/v1/agent/*` — Conversational interface to Bavlio capabilities. SSE streaming + interrupt resume. Conversation history persistence.
  </Accordion>

  <Accordion title="Connected Accounts (LinkedIn via Unipile)" icon="linkedin">
    `/api/v1/connected-accounts/*` — Connect LinkedIn accounts via hosted-auth, credentials, or cookie. Check health, set send/invite limits, resume disabled accounts.
  </Accordion>

  <Accordion title="BaviMail Proxy" icon="paper-plane">
    `/api/v1/bavimail/*` — Send transactional emails, manage sending domains and aliases, list inbound replies, browse conversations. Backed by BaviMail.
  </Accordion>

  <Accordion title="Credits & Billing" icon="credit-card">
    `/api/v1/credits/*`, `/api/v1/stripe/*` — Check credit balance, transaction history, estimate cost. Stripe checkout / portal / subscription status (JWT only).
  </Accordion>

  <Accordion title="x402 Pay-Per-Call" icon="coins">
    `/api/x402/v1/*` — Wallet-paid endpoints (no API key). USDC on Base mainnet via x402 protocol. 5 endpoints. See [x402 API guide](https://bavlio.com/developers/x402) for details.
  </Accordion>
</AccordionGroup>

## Honest about state

These reference pages reflect what's live today. If you spot a discrepancy with actual behavior, the live spec at [`api.bavlio.com/openapi.json`](https://api.bavlio.com/openapi.json) is the source of truth. Roadmap items (Idempotency-Key middleware, customer webhooks, restricted API keys, MCP server) are flagged on their respective concept pages — not silently shown as if they exist.

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    First call in 5 minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Key format, rotation, scoping.
  </Card>

  <Card title="Errors" icon="circle-exclamation" href="/errors">
    Three envelopes documented honestly.
  </Card>
</CardGroup>