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 — they’re always in sync with what’s deployed.

Looking for a quick-start? Start with Quickstart — auth, first call, and error handling in 5 minutes. This reference is the comprehensive map; the quickstart is the ramp.

Spec sources

Live OpenAPI spec

api.bavlio.com/openapi.json — always-fresh production contract. Point your code generator at this.

Browse interactively

Use the sidebar in this section to browse every endpoint. Try-It console included for authenticated calls.

Endpoint groups

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

Authentication & Identity

/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).

Campaigns

/api/v1/campaigns/* — Create, list, launch, pause, resume campaigns. Per-campaign stats, leads, events, playground drafts. ~25 endpoints.

Email Finder & Verification

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

Lead Finder

/api/v1/lead-finder/* — Batch resolve names → LinkedIn profile URLs. Async with status polling.

Sender Profiles

/api/v1/sender-profiles/* — Manage up to 5 sender profiles per user. Named prompts (per-profile saved instructions) for AI personalization.

Templates

/api/v1/templates/* — Reusable email templates with variable substitution.

Suppression / DNC

/api/v1/suppression/* — Do-not-contact list management.

Datasets & Extractions

/api/v1/datasets/*, /api/v1/user-extractions/* — Stored data sources from CSV, Excel, Google Sheets, and Chrome extension extractions.

Personalization

/api/v1/personalize/* — Submit single or bulk personalization jobs. Async via ARQ — poll job status. Generation history endpoints expose run-level audit trail.

Agent (Bavi chat)

/api/v1/agent/* — Conversational interface to Bavlio capabilities. SSE streaming + interrupt resume. Conversation history persistence.

Connected Accounts (LinkedIn via Unipile)

/api/v1/connected-accounts/* — Connect LinkedIn accounts via hosted-auth, credentials, or cookie. Check health, set send/invite limits, resume disabled accounts.

BaviMail Proxy

/api/v1/bavimail/* — Send transactional emails, manage sending domains and aliases, list inbound replies, browse conversations. Backed by BaviMail.

Credits & Billing

/api/v1/credits/*, /api/v1/stripe/* — Check credit balance, transaction history, estimate cost. Stripe checkout / portal / subscription status (JWT only).

x402 Pay-Per-Call

/api/x402/v1/* — Wallet-paid endpoints (no API key). USDC on Base mainnet via x402 protocol. 5 endpoints. See x402 API guide for details.

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

Quickstart

First call in 5 minutes.

Authentication

Key format, rotation, scoping.

Errors

Three envelopes documented honestly.