back to search

API docs

one endpoint. one call. scored business leads back. no SDK, no client library, no OAuth dance.

generateresponseauthenticationerrorsx402 protocol

quick start

one endpoint, one call. send a vertical and location, get scored leads back. authenticate with an API key in the header or pay per request with x402.

POST /v1/generateJSON in, JSON outno SDK required
POST

generate leads

/v1/generate

search for business leads in a vertical and location. returns scored results with opportunity analysis. every call runs a fresh scrape — results are generated at request time, not pulled from a cache.

request body

verticalstringrequired
business category to search. supported: european-auto auto-repair self-storage home-services
locationstringrequired
city, metro area, or region. e.g. "Denver, CO"
limitnumber
max leads to return. default 50, max 200.
radiusMilesnumber
search radius in miles. default 25.
skipEnrichmentboolean
if true, returns scrape + score only (faster, cheaper). default false.
example request
curl -X POST https://gravee-ashy.vercel.app/api/search \
  -H "Authorization: Bearer gv_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "vertical": "home-services",
    "location": "Denver, CO",
    "limit": 25
  }'

response format

response body
{
  "leads": [
    {
      "business_name": "Time Plumbing & Heating",
      "city": "Denver",
      "state": "CO",
      "category": "Plumber",
      "rating": 4.6,
      "review_count": 792,
      "phone": "+13035551234",
      "website": "https://timeplumbing.com",
      "opportunity_score": 58,
      "priority_tier": "MEDIUM",
      "opportunity_details": [
        "website loads in 6.8 seconds on mobile"
      ]
    }
  ],
  "metadata": {
    "count": 25,
    "high": 8,
    "medium": 11,
    "low": 6,
    "vertical": "home-services",
    "location": "Denver, CO",
    "scraped": 142,
    "filtered": 25,
    "generated_at": "2026-09-10T14:32:01Z"
  }
}

scoring tiers

hot
70–100
warm
40–69
cool
0–39

authentication

two ways to authenticate. pick whichever fits how you work.

API key

pass your key in the Authorization header. keys are metered — each call deducts from your balance. no account required to get a key; purchase one on the website.

Authorization: Bearer gv_your_api_key

x402 payment

pay per request with the HTTP 402 protocol. no key, no account, no balance to maintain. your agent sends a request, gets a 402 with a payment requirement, settles on-chain, re-sends with the payment proof, and gets the results.

full x402 documentation

errors

errors come back as JSON with a message field. HTTP status codes are standard.

statusmeaning
400bad request — missing or invalid parameters
401unauthorized — missing or invalid API key
402payment required — x402 settlement needed
429rate limited — too many requests, slow down
500server error — something broke on our end

rate limits

each search triggers live scraping, which takes real time and real compute. API key requests are limited to 10 requests per minute and 100 per hour. x402 requests have the same per-minute limit but no hourly cap — you're paying per call, so there's no balance to drain.

rate limit headers are included on every response:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1694362800