# SDR AI

> AI sales development agent. Research prospects, generate personalized outreach emails.

SDR AI researches companies and contacts using web search + AI analysis,
then generates personalized multi-step email sequences for sales outreach.
Two auth paths: Bearer JWT for human users, MPP Lightning payments for AI agents.

- [API docs](https://sdrai.ai/docs): OpenAPI/Swagger interactive documentation
- [OpenAPI spec](https://sdrai.ai/openapi.json): Machine-readable schema
- [Agent metadata](https://sdrai.ai/.well-known/agent.json): Capabilities, auth, pricing
- [Health check](https://sdrai.ai/api/health): Service status

## Authentication (two methods)

### Option A: Bearer JWT (human users)
1. Register: POST /api/auth/register {email, password, promo_code?} -> 202 Accepted with detail message (verification email sent; no token returned in production)
2. Login: POST /api/auth/login {email, password} -> {access_token, token_type}
3. Use header: Authorization: Bearer <access_token>
4. Refresh: POST /api/auth/refresh with current token -> new token
Note: register and login are separate steps. The 202 from register has no access_token; you MUST chain to /api/auth/login with the same credentials to obtain a usable Bearer JWT.

### Option B: MPP Lightning payment (AI agents, no account needed)
1. POST any paid endpoint with no auth header
2. Receive 402 with WWW-Authenticate: Payment header containing BOLT11 invoice
3. Pay the Lightning invoice to obtain the preimage
4. Build credential: {challenge: {id, realm, method, intent, request, expires}, payload: {preimage}}
5. Base64url-encode the credential JSON
6. Retry with header: Authorization: Payment <base64url-credential>
7. Receive 200 with Payment-Receipt header

## Core Endpoints

### Prospect Research
POST /api/v1/research
  Body: {company, contact?, contact_title?, context?, url?, depth: quick|standard|deep}
  Returns: {id, company_summary, recent_news, pain_points, personalization_hooks, research_sources, cost_cents, balance_cents}
  Pricing: quick $0.20, standard $0.50, deep $1.50
  Free tier: 1 quick research/day at zero balance

### Email Draft Generation
POST /api/v1/draft
  Body: {prospect: {company, name?, title?, research: {company_summary?, personalization_hooks?, pain_points?, recent_news?}, research_id?}, sender: {product, value_prop?, tone?}, emails: 1-5}
  Returns: {sequence: [{subject, body}], cost_cents, balance_cents, request_id}
  Pricing: ~$0.04 per email (4x markup on API cost)

### Research History
GET /api/v1/research/history  -> list of past research results (max 50)
DELETE /api/v1/research/{id}  -> delete a research result
PUT /api/v1/research/{id}/drafts  -> save drafts to a research result

### Email Validation
POST /api/v1/validate-email
  Body: {emails: [str, ...]} (1-50 per request)
  Returns: {results: [{email, valid, format_valid, mx_valid, mx_host?, confidence, reason?}], cost_cents, balance_cents?, request_id}
  Pricing: 1¢ per email (10 sats per email). No mailbox probe; format + DNS MX only.

### Signal Detection
POST /api/v1/signals
  Body: {companies: [str, ...], signals?: [funding|hiring|product_launch|leadership_change]} (1-10 companies per request, signals default to all four)
  Returns: {results: [{company, signals: [{type, detail, date, source}]}], cost_cents, balance_cents?, request_id}
  Pricing: 1¢ per company (10 sats per company). One Brave query + one Gemini extract per company; filtered to the requested signal types.

### Verified Lead Generation (async)
POST /api/v1/leads
  Body: {icp: {industry, size_band?, role?, pain_signal?, geography?}, channels?: [case_studies|associations|press|conference_speakers|top_lists], count?: 1-50, exclude_companies?: [], verification_bar?: strict|generic_ok|any_reachable, seed_urls?: {channel: [url]}, expand_firms?: bool, expand_firm_cap?: 1-100}
  Returns: {job_id, status: queued, estimated_cost_cents}
GET /api/v1/leads/{job_id}  -> {status, leads: [...], dropped: [...], channel_productivity, cost_cents}
GET /api/v1/leads/{job_id}/export?format=csv|markdown
  Pricing (Bearer): ~20c per email-lead, 10c per contact-form-only lead, with a 25c minimum research fee per job (covers zero-yield upstream cost). Stage-1 drops do not add to per-lead cost, but the minimum research fee still applies.
  Pricing (MPP): flat tier paid upfront: 10 leads = 2000 sats, 25 = 4500 sats, 50 = 8000 sats. Tier price is unaffected by yield.
  Verification: firm-published emails only (aggregators like ZoomInfo/Apollo rejected). Two-stage cost gate.

## Account & Billing

GET /api/user/me              -> user profile
GET /api/user/usage           -> usage stats
GET /api/payments/balance     -> current balance in cents
POST /api/payments/create-checkout {amount: cents}  -> Stripe checkout URL (min $5)

## ICP Profiles

POST /api/icp/create  -> create Ideal Customer Profile
GET /api/icp          -> list ICP profiles
PUT /api/icp/{id}     -> update ICP profile
DELETE /api/icp/{id}  -> delete ICP profile

## Pricing

Pay-per-use with prepaid USD balance. Top up via Stripe (min $5).
- Research quick: $0.20, standard: $0.50, deep: $1.50
- Email drafts: ~$0.04 per email
- Free tier: 1 quick research/day at zero balance (auto-downgraded to quick)
- Volume discounts: 25% off after $100 lifetime spend (Pro), 50% off after $1000 (Power)

## Typical Agent Workflow

1. POST /api/auth/login to get JWT
2. GET /api/payments/balance to check funds
3. POST /api/v1/research with company name + optional contact
4. POST /api/v1/draft with research results + your product context
5. Use the generated email sequence for outreach