{"openapi":"3.1.0","info":{"title":"Lead Enrichment API","description":"Agent-native B2B lead enrichment service","version":"1.1.0"},"paths":{"/v1/auth/register":{"post":{"tags":["auth"],"summary":"Register","description":"Register a new free-tier API key.\n\nReturns the API key once — store it safely, it cannot be retrieved again.","operationId":"register_v1_auth_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/auth/key":{"delete":{"tags":["auth"],"summary":"Revoke Key","description":"Revoke the calling API key immediately.\n\nAgents use this to clean up after themselves (minimal-footprint principle).\nAfter this call the key is permanently deactivated — no undo.","operationId":"revoke_key_v1_auth_key_delete","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/health":{"get":{"tags":["health"],"summary":"Health Check","description":"Service liveness + dependency health. Used by monitoring and agent orchestrators.","operationId":"health_check_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/search":{"post":{"tags":["search"],"summary":"Search Leads","description":"Search and retrieve enriched leads matching ICP criteria.\n\nSupports idempotent retries via the `Idempotency-Key` header (UUID).\nSame key within 24 h returns the cached result without re-charging quota.","operationId":"search_leads_v1_search_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/validate":{"post":{"tags":["validate"],"summary":"Validate Leads","description":"Validate freshness and accuracy of previously retrieved leads.","operationId":"validate_leads_v1_validate_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/subscribe":{"post":{"tags":["subscribe"],"summary":"Create Subscription","description":"Subscribe to webhook delivery of new leads matching criteria.","operationId":"create_subscription_v1_subscribe_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/subscriptions":{"get":{"tags":["subscribe"],"summary":"List Subscriptions","description":"List all active subscriptions for the authenticated API key.","operationId":"list_subscriptions_v1_subscriptions_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/subscriptions/{subscription_id}":{"delete":{"tags":["subscribe"],"summary":"Cancel Subscription","description":"Cancel (deactivate) a subscription.","operationId":"cancel_subscription_v1_subscriptions__subscription_id__delete","parameters":[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Subscription Id"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/checkout":{"post":{"tags":["billing"],"summary":"Create Checkout","description":"Create a Stripe Checkout Session to upgrade to pro tier.","operationId":"create_checkout_v1_billing_checkout_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/portal":{"post":{"tags":["billing"],"summary":"Customer Portal","description":"Create a Stripe Customer Portal session to manage subscription.","operationId":"customer_portal_v1_billing_portal_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PortalResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/status":{"get":{"tags":["billing"],"summary":"Billing Status","description":"Get current billing/tier status for the authenticated API key.","operationId":"billing_status_v1_billing_status_get","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage":{"get":{"tags":["usage"],"summary":"Get Usage","description":"Return current quota status and recent usage log for this API key.\n\nAgents use this to track spend, verify charges, and decide whether\nto make more requests before their monthly quota resets.","operationId":"get_usage_v1_usage_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"title":"Limit"}},{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummary"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/search/pay":{"post":{"tags":["x402"],"summary":"Search With X402 Payment","description":"Search leads with x402 micropayment — no API key needed.\n\nWithout X-Payment header: returns 402 with payment requirements.\nWith valid X-Payment header: returns leads.","operationId":"search_with_x402_payment_v1_search_pay_post","parameters":[{"name":"X-Payment","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Payment"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"BillingStatusResponse":{"properties":{"tier":{"type":"string","title":"Tier"},"monthly_limit":{"type":"integer","title":"Monthly Limit"},"used_this_month":{"type":"integer","title":"Used This Month"},"has_stripe_subscription":{"type":"boolean","title":"Has Stripe Subscription"}},"type":"object","required":["tier","monthly_limit","used_this_month","has_stripe_subscription"],"title":"BillingStatusResponse"},"BuyingSignals":{"properties":{"hiring":{"type":"boolean","title":"Hiring","default":false},"recent_funding":{"type":"boolean","title":"Recent Funding","default":false},"product_launch":{"type":"boolean","title":"Product Launch","default":false},"expansion":{"type":"boolean","title":"Expansion","default":false}},"type":"object","title":"BuyingSignals"},"CheckoutRequest":{"properties":{"success_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Success Url"},"cancel_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Cancel Url"}},"type":"object","required":["success_url","cancel_url"],"title":"CheckoutRequest"},"CheckoutResponse":{"properties":{"checkout_url":{"type":"string","title":"Checkout Url"}},"type":"object","required":["checkout_url"],"title":"CheckoutResponse"},"CostInfo":{"properties":{"leads_charged":{"type":"integer","title":"Leads Charged"},"price_per_lead":{"type":"number","title":"Price Per Lead"},"total_usd":{"type":"number","title":"Total Usd"}},"type":"object","required":["leads_charged","price_per_lead","total_usd"],"title":"CostInfo"},"FundingSignals":{"properties":{"last_round_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Round Type"},"estimated_amount":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estimated Amount"},"date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date"}},"type":"object","title":"FundingSignals"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Industry":{"type":"string","enum":["AI","Blockchain","Fintech","Security","Healthcare","DevTools","Other"],"title":"Industry"},"Lead":{"properties":{"lead_id":{"type":"string","format":"uuid","title":"Lead Id"},"company_name":{"type":"string","title":"Company Name"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"industry":{"$ref":"#/components/schemas/Industry"},"sub_industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sub Industry"},"stage":{"$ref":"#/components/schemas/Stage"},"estimated_employees":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Estimated Employees"},"location":{"$ref":"#/components/schemas/Location"},"tech_stack_signals":{"items":{"type":"string"},"type":"array","title":"Tech Stack Signals"},"funding_signals":{"$ref":"#/components/schemas/FundingSignals"},"buying_signals":{"$ref":"#/components/schemas/BuyingSignals"},"icp_score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Icp Score"},"buying_intent_score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Buying Intent Score"},"icp_tags":{"items":{"type":"string"},"type":"array","title":"Icp Tags"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"},"confidence":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Confidence"},"data_sources":{"items":{"type":"string"},"type":"array","title":"Data Sources"},"enriched_at":{"type":"string","format":"date-time","title":"Enriched At"}},"type":"object","required":["lead_id","company_name","industry","stage","location","icp_score","buying_intent_score","confidence","enriched_at"],"title":"Lead","description":"Enriched lead record."},"LeadValidation":{"properties":{"lead_id":{"type":"string","format":"uuid","title":"Lead Id"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website"},"status":{"type":"string","title":"Status"},"freshness_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Freshness Days"},"website_reachable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Website Reachable"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"}},"type":"object","required":["lead_id","status"],"title":"LeadValidation"},"Location":{"properties":{"country":{"type":"string","title":"Country"},"region":{"$ref":"#/components/schemas/Region"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City"}},"type":"object","required":["country","region"],"title":"Location"},"Pagination":{"properties":{"offset":{"type":"integer","title":"Offset"},"limit":{"type":"integer","title":"Limit"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["offset","limit","has_more"],"title":"Pagination"},"PortalRequest":{"properties":{"return_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Return Url"}},"type":"object","required":["return_url"],"title":"PortalRequest"},"PortalResponse":{"properties":{"portal_url":{"type":"string","title":"Portal Url"}},"type":"object","required":["portal_url"],"title":"PortalResponse"},"Region":{"type":"string","enum":["EU","US","APAC","MENA","Other"],"title":"Region"},"RegisterRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["email"],"title":"RegisterRequest"},"RegisterResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"},"tier":{"type":"string","title":"Tier"},"monthly_limit":{"type":"integer","title":"Monthly Limit"},"message":{"type":"string","title":"Message"}},"type":"object","required":["api_key","tier","monthly_limit","message"],"title":"RegisterResponse"},"SearchCriteria":{"properties":{"industries":{"anyOf":[{"items":{"$ref":"#/components/schemas/Industry"},"type":"array"},{"type":"null"}],"title":"Industries"},"stages":{"anyOf":[{"items":{"$ref":"#/components/schemas/Stage"},"type":"array"},{"type":"null"}],"title":"Stages"},"regions":{"anyOf":[{"items":{"$ref":"#/components/schemas/Region"},"type":"array"},{"type":"null"}],"title":"Regions"},"min_employees":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Min Employees"},"min_icp_score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Min Icp Score","default":0},"min_buying_intent":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Min Buying Intent","default":0},"tech_stack_contains":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tech Stack Contains"},"max_age_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Max Age Days","default":30}},"type":"object","title":"SearchCriteria"},"SearchRequest":{"properties":{"criteria":{"$ref":"#/components/schemas/SearchCriteria"},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","default":10},"offset":{"type":"integer","minimum":0.0,"title":"Offset","default":0},"sort_by":{"type":"string","title":"Sort By","default":"icp_score"}},"type":"object","required":["criteria"],"title":"SearchRequest"},"SearchResponse":{"properties":{"leads":{"items":{"$ref":"#/components/schemas/Lead"},"type":"array","title":"Leads"},"total_count":{"type":"integer","title":"Total Count"},"returned_count":{"type":"integer","title":"Returned Count"},"cost":{"$ref":"#/components/schemas/CostInfo"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"type":"object","required":["leads","total_count","returned_count","cost","pagination"],"title":"SearchResponse"},"Stage":{"type":"string","enum":["Pre-seed","Seed","Series A","Series B","Series C+","Public","Unknown"],"title":"Stage"},"SubscribeRequest":{"properties":{"criteria":{"$ref":"#/components/schemas/SearchCriteria"},"webhook_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Webhook Url"},"webhook_secret":{"type":"string","minLength":16,"title":"Webhook Secret","description":"Shared secret for HMAC verification (min 16 chars)"},"frequency":{"type":"string","title":"Frequency","description":"hourly, daily, or weekly","default":"daily"},"max_leads_per_delivery":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Max Leads Per Delivery","default":25}},"type":"object","required":["criteria","webhook_url","webhook_secret"],"title":"SubscribeRequest"},"SubscribeResponse":{"properties":{"subscription":{"$ref":"#/components/schemas/SubscriptionInfo"},"message":{"type":"string","title":"Message"}},"type":"object","required":["subscription","message"],"title":"SubscribeResponse"},"SubscriptionInfo":{"properties":{"subscription_id":{"type":"string","format":"uuid","title":"Subscription Id"},"webhook_url":{"type":"string","title":"Webhook Url"},"frequency":{"type":"string","title":"Frequency"},"max_leads_per_delivery":{"type":"integer","title":"Max Leads Per Delivery"},"criteria":{"$ref":"#/components/schemas/SearchCriteria"},"next_delivery":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Delivery"},"is_active":{"type":"boolean","title":"Is Active","default":true},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"}},"type":"object","required":["subscription_id","webhook_url","frequency","max_leads_per_delivery","criteria"],"title":"SubscriptionInfo"},"SubscriptionListResponse":{"properties":{"subscriptions":{"items":{"$ref":"#/components/schemas/SubscriptionInfo"},"type":"array","title":"Subscriptions"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["subscriptions","total"],"title":"SubscriptionListResponse"},"UsageEntry":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"endpoint":{"type":"string","title":"Endpoint"},"leads_returned":{"type":"integer","title":"Leads Returned"},"cost_usd":{"type":"number","title":"Cost Usd"},"request_at":{"type":"string","format":"date-time","title":"Request At"}},"type":"object","required":["id","endpoint","leads_returned","cost_usd","request_at"],"title":"UsageEntry"},"UsageSummary":{"properties":{"tier":{"type":"string","title":"Tier"},"monthly_limit":{"type":"integer","title":"Monthly Limit"},"used_this_month":{"type":"integer","title":"Used This Month"},"remaining":{"type":"integer","title":"Remaining"},"reset_at":{"type":"string","title":"Reset At"},"entries":{"items":{"$ref":"#/components/schemas/UsageEntry"},"type":"array","title":"Entries"},"total_entries":{"type":"integer","title":"Total Entries"}},"type":"object","required":["tier","monthly_limit","used_this_month","remaining","reset_at","entries","total_entries"],"title":"UsageSummary"},"ValidateRequest":{"properties":{"lead_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Lead Ids"}},"type":"object","required":["lead_ids"],"title":"ValidateRequest"},"ValidateResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/LeadValidation"},"type":"array","title":"Results"},"total_checked":{"type":"integer","title":"Total Checked"},"valid_count":{"type":"integer","title":"Valid Count"},"stale_count":{"type":"integer","title":"Stale Count"},"unreachable_count":{"type":"integer","title":"Unreachable Count"},"not_found_count":{"type":"integer","title":"Not Found Count"}},"type":"object","required":["results","total_checked","valid_count","stale_count","unreachable_count","not_found_count"],"title":"ValidateResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}