Lyre Leads API

Quick Start

Get your first API call working in under 2 minutes.

First API call

curl https://lyreleads.com/api/v1/balance \
  -H "Authorization: Bearer lyre_your_api_key_here"

import requests

API_KEY = "lyre_your_api_key_here"
BASE_URL = "https://lyreleads.com"
headers = {"Authorization": f"Bearer {API_KEY}"}

resp = requests.get(f"{BASE_URL}/api/v1/balance", headers=headers)
print(resp.json())
# {'tier': 'Growth', 'tokens_balance': 4500, 'tokens_monthly_allocation': 5000, ...}

const res = await fetch('https://lyreleads.com/api/v1/balance', {
  headers: { 'Authorization': 'Bearer lyre_your_api_key_here' }
});
const data = await res.json();
console.log(data.tokens_balance); // 4500

Authentication

All API v1 requests require an API key sent as a Bearer token in the Authorization header:

Authorization: Bearer lyre_<your-64-hex-key>

API keys are scoped to your account. They inherit your token balance and tier permissions. You can create up to 10 active keys per account and revoke them at any time from the Account page.

Error Handling

The API uses standard HTTP status codes. All error responses are JSON with an error field:

{
  "error": "Insufficient tokens.",
  "tokens_needed": 20,
  "tokens_balance": 5,
  "upgrade_url": "/pricing"
}

Rate Limits

The API allows 120 requests per minute per API key. Exceeding this returns a 429 response. The limit resets every 60 seconds.

Each search result or AI evaluation costs 1 token. Check your balance at any time via GET /api/v1/balance.

MCP Server (AI Agents)

Lyre Leads ships a Model Context Protocol endpoint, so Claude, Cursor, and any MCP-compatible client can search markets, enrich them, find and verify decision-maker emails, and read the relevance verdict on each result directly. It exposes nine tools: search_leads, list_results, estimate_list, count_saved_leads, enrich_leads, find_decision_makers, verify_emails, get_job_status, and get_balance, backed by the same routes documented below (same auth, limits, and token costs).

count_leads is free and exact at any size. Agents should size a segment before spending on it, so counting is never billed and never rationed.

Point your agent at lyreleads.com/for-agents first. It is a working guide written for an AI assistant rather than a human: what each field means, what a blank value does and does not tell you, where our coverage is weak, and the four mistakes that produce confidently wrong lead lists. Raw markdown at /for-agents.md.

Building a client on top of this API? lyreleads.com/build carries complete, implementable specs an AI coding agent can follow to build a local dashboard, territory runner, outreach queue or change monitor in about one session each.

Connect via streamable HTTP with your API key as a bearer token:

{
  "mcpServers": {
    "lyre-leads": {
      "type": "http",
      "url": "https://lyreleads.com/mcp",
      "headers": { "Authorization": "Bearer lyre_your_key_here" }
    }
  }
}

Typical agent flow: search_leads for a keyword and city, then poll list_results with the returned search_id while background enrichment fills in emails, verification status, tech stack, and the relevance verdict, then filter on relevance: "yes" before you spend anything else on the batch.

Endpoints

Token Balance

{
  "tier": "Growth",
  "tokens_balance": 4500,
  "tokens_monthly_allocation": 5000,
  "tokens_reset_date": "2026-02-01T00:00:00.000Z",
  "tokens_next_reset": "2026-03-01T00:00:00.000Z"
}

Search for Leads

{
  "query": "plumbers",
  "city": "Berlin",
  "country": "Germany",
  "pages": 2
}

{
  "results": [
    {
      "name": "Müller Plumbing GmbH",
      "address": "Hauptstraße 42, 10115 Berlin",
      "phone": "+49 30 12345678",
      "website": "https://mueller-plumbing.de",
      "rating": 4.7,
      "review_count": 183,
      "type": "Plumber"
    }
  ],
  "results_count": 40,
  "tokens_used": 40,
  "tokens_remaining": 4460,
  "query": "plumbers",
  "city": "Berlin",
  "country": "Germany"
}

resp = requests.post(
    f"{BASE_URL}/api/v1/search",
    headers=headers,
    json={
        "query": "plumbers",
        "city": "Berlin",
        "country": "Germany",
        "pages": 2
    }
)
data = resp.json()
for biz in data["results"]:
    print(biz["name"], biz.get("website", ", "))

Retrieve Past Results

curl "https://lyreleads.com/api/v1/results?limit=50&query=plumbers" \
  -H "Authorization: Bearer lyre_..."

{
  "results": [ /* array of result objects */ ],
  "total": 2540,
  "limit": 50,
  "offset": 0,
  "has_more": true
}

Relevance

// POST /api/v1/count, free at any size
{
  "filters": { "relevance": "yes", "has_email": true }
}

// A row from GET /api/v1/results
{
  "name": "Bergen Roofing & Sheet Metal",
  "query": "roofing contractor",
  "relevance": "yes",
  "relevance_evidence": "Residential and commercial roof replacement since 1994"
}

OpenAPI Spec

from langchain.tools import OpenAPISpec, APIOperation
from langchain.chains import OpenAPIEndpointChain

spec = OpenAPISpec.from_url("https://lyreleads.com/api/v1/openapi.json")
# Agent can now auto-discover and call Lyre Leads endpoints