# Lead Radar (lead-radar.fr)

Lead Radar is a B2B lead generation SaaS: it searches for businesses on
Google Maps (by keyword + location, or from a Google Maps URL), deduplicates
results, and enriches email addresses from company websites.
Each search consumes credits.

The API is fully usable by AI agents: account creation, API key
authentication, and all endpoints work without a browser.

## Create an account and get an API key (single call)

POST /api/auth/register
Content-Type: application/json

{ "email": "agent@example.com", "password": "min-8-chars", "name": "My agent", "createApiKey": true }

Response: { "ok": true, "apiKey": "lr_..." }

The key is shown only once: store it. Welcome credits are granted on
signup; API signups share a global daily quota — the response's
"welcomeCredits" field (5 or 0) tells you whether you received them.
If 0, buy credits via the checkout flow below or retry another day.

## Authentication

All /api/* routes accept the header:

Authorization: Bearer lr_...

## Key management

- GET /api/keys — list your active keys
- POST /api/keys — create a key (optional { "name": "..." }); the plaintext key is only returned at creation
- DELETE /api/keys/{id} — revoke a key

## Main endpoints

### Credits
- GET /api/credits/balance — current balance
- GET /api/credits/history — ledger history

### Searches (credits debited at launch, refunded on failure)
Cost: 1 credit by default; for a KEYWORD search with radiusKm, the cost
grows with the radius (more grid cells to cover). Check your balance
before launching a large radius.
- POST /api/searches — launch a search. Body (two forms):
  { "type": "KEYWORD", "keyword": "plumber", "location": "Lyon, France", "radiusKm": 10 }
  or { "type": "MAPS_URL", "mapsUrl": "https://www.google.com/maps/search/..." }
- GET /api/searches — list your searches (status: PENDING, RUNNING, PAUSED, COMPLETED, FAILED)
- GET /api/searches/{id} — search detail and progress

Searches are asynchronous: launch, then poll the status until COMPLETED.

### Leads
- GET /api/leads — list your leads. Query params: page, limit (max 100), searchId, hasEmail (true/false), q (free text), tagId
- GET /api/leads/{id} — lead detail (tags, notes)
- PATCH /api/leads/{id} — fix phone / email
- POST /api/leads/enrich — enrich emails ({ "leadIds": ["..."] }, max 100)
- GET /api/leads/export — CSV export

### Buying credits (checkout handed to the human)
Payment happens through Stripe Checkout in a browser. The agent flow:
create the session, hand the URL to your human operator, who pays;
credits are added to the account automatically once payment is confirmed
(Stripe webhook). No further agent action is required — then check the
balance with GET /api/credits/balance.

- POST /api/stripe/checkout — create a payment session. Body:
  { "packId": "pack_10" | "pack_50" | "pack_100" }  (one-time purchase: 10/50/100 credits)
  or { "planId": "starter" | "pro" }  (monthly subscription: 100/220 credits per month)
  Response: { "url": "https://checkout.stripe.com/..." }
- Limits: 3 sessions / minute. Only one active subscription at a time.

## MCP server

An MCP server (Model Context Protocol, Streamable HTTP transport) is exposed at:

POST /api/mcp
Authorization: Bearer lr_...

Available tools: get_credit_balance, create_search, get_search,
list_searches, list_leads, enrich_leads, list_credit_packs, create_checkout.

Example MCP client configuration:
{ "url": "https://<host>/api/mcp", "headers": { "Authorization": "Bearer lr_..." } }

OAuth one-click connect: MCP clients that support OAuth can connect without
pasting a key. The server implements OAuth 2.1 (authorization code + PKCE)
with Dynamic Client Registration; discovery documents are served at
/.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.
The issued access token is a regular API key, revocable from the dashboard
settings (API keys section).

## Limits

- Signup: 5 accounts / hour / IP
- Maximum 10 active API keys per account
- 120 requests / minute per API key
- All data is scoped to the account: a key only grants access to its
  owner's data.