> ## Documentation index
> Fetch the complete documentation index at: https://docs.leadity.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Every operation of the Leadity HTTP API, generated from the definitions the API itself runs.

Each page in this reference is generated from the same definition the API serves and the MCP server registers as a tool, so the parameters, the examples and the MCP tool name on a page are what the API accepts today.

## Base URL

```text
https://api.leadity.io/v1
```

Authenticate every request with an API key: `Authorization: Bearer lk_api_...`. See [Authentication](https://docs.leadity.io/authentication).

## Reading a reference page

- **Scope** is what the key needs: `read`, `write` or `spend`. See [API keys and scopes](https://docs.leadity.io/api-keys).
- **Spends credits** marks an operation that takes credits. It needs an `Idempotency-Key` header and a `maxCredits` ceiling, and a free operation prices it first. See [Spending credits safely](https://docs.leadity.io/spending-credits).
- **MCP tool** is the name the same operation has on the [MCP server](https://docs.leadity.io/mcp/overview). **HTTP only** means the MCP server does not carry it.
- **Errors** lists the codes every call of the operation's kind can meet, with the extra fields each can carry. The codes an order or an upgrade adds of its own are on [Errors](https://docs.leadity.io/errors), with the rest.

## OpenAPI

```text
https://api.leadity.io/v1/openapi.json
```

The OpenAPI 3.1 document is generated from the same definitions as these pages.

## Every operation

**Catalog**

| Operation | Endpoint | Scope | Summary |
| --- | --- | --- | --- |
| [`list_niches`](https://docs.leadity.io/api-reference/catalog/list-niches) | `GET /v1/niches` | read | List the niches you can order, grouped by market. |
| [`get_pricing`](https://docs.leadity.io/api-reference/catalog/get-pricing) | `GET /v1/pricing` | read | Read the price card: what each lead and each filter costs, in credits. |
| [`list_territories`](https://docs.leadity.io/api-reference/catalog/list-territories) | `GET /v1/territories` | read | List the countries and the regions you can order in. |
| [`list_areas`](https://docs.leadity.io/api-reference/catalog/list-areas) | `GET /v1/areas` | read | List one region's areas and their ZIP or postal codes. |
| [`search_areas`](https://docs.leadity.io/api-reference/catalog/search-areas) | `GET /v1/areas/search` | read | Find areas and ZIP or postal codes by name across a country. |
| [`get_coverage`](https://docs.leadity.io/api-reference/catalog/get-coverage) | `GET /v1/coverage` | read | See which areas you have already swept for each niche. |

**Account**

| Operation | Endpoint | Scope | Summary |
| --- | --- | --- | --- |
| [`get_account`](https://docs.leadity.io/api-reference/account/get-account) | `GET /v1/account` | read | Read the account's balance and what this key may do. |
| [`get_scrape_defaults`](https://docs.leadity.io/api-reference/account/get-scrape-defaults) | `GET /v1/account/scrape-defaults` | read | Read the filters and lead count the account's new orders open on. |
| [`get_analytics`](https://docs.leadity.io/api-reference/account/get-analytics) | `GET /v1/account/analytics` | read | Read what the account has swept and owns, per niche and state. |

**Billing**

| Operation | Endpoint | Scope | Summary |
| --- | --- | --- | --- |
| [`list_plans`](https://docs.leadity.io/api-reference/billing/list-plans) | `GET /v1/billing/plans` | read | List both credit ladders: monthly plans and one-time packs. |
| [`get_subscription`](https://docs.leadity.io/api-reference/billing/get-subscription) | `GET /v1/billing/subscription` | read | Read the account's plan and every credit expiry. |
| [`list_credit_history`](https://docs.leadity.io/api-reference/billing/list-credit-history) | `GET /v1/billing/history` | read | Read the credit ledger: every purchase, spend, refund and expiry. |
| [`create_checkout`](https://docs.leadity.io/api-reference/billing/create-checkout) | `POST /v1/billing/checkout` | write | Open a checkout and answer the link a person pays at. |
| [`create_top_up_checkout`](https://docs.leadity.io/api-reference/billing/create-top-up-checkout) | `POST /v1/billing/top-up` | write | Open a checkout that adds credits to the monthly plan, and answer the link a person pays at. |

**Scrapes**

| Operation | Endpoint | Scope | Summary |
| --- | --- | --- | --- |
| [`estimate_scrape`](https://docs.leadity.io/api-reference/scrapes/estimate-scrape) | `POST /v1/scrapes/estimate` | read | Quote an order for free: what is still new, the per-lead rate and the floors. |
| [`create_scrape`](https://docs.leadity.io/api-reference/scrapes/create-scrape) | `POST /v1/scrapes` | spend | Order a scrape: find businesses live on Google Maps and deliver them as leads. |
| [`list_scrapes`](https://docs.leadity.io/api-reference/scrapes/list-scrapes) | `GET /v1/scrapes` | read | List the account's scrapes, newest first. |
| [`get_scrape`](https://docs.leadity.io/api-reference/scrapes/get-scrape) | `GET /v1/scrapes/{id}` | read | Read one scrape in full: its selection, its progress and its upgrades. |
| [`get_scrape_status`](https://docs.leadity.io/api-reference/scrapes/get-scrape-status) | `GET /v1/scrapes/{id}/status` | read | Poll a scrape cheaply: its status, and whether it is complete. |
| [`rename_scrape`](https://docs.leadity.io/api-reference/scrapes/rename-scrape) | `POST /v1/scrapes/{id}/rename` | write | Rename a scrape. |
| [`stop_scrape`](https://docs.leadity.io/api-reference/scrapes/stop-scrape) | `POST /v1/scrapes/{id}/stop` | write | Stop a live scrape: keep what it delivered and refund the rest. |
| [`list_leads`](https://docs.leadity.io/api-reference/scrapes/list-leads) | `GET /v1/scrapes/{id}/leads` | read | Read a scrape's delivered leads, a page at a time. |
| [`download_leads`](https://docs.leadity.io/api-reference/scrapes/download-leads) | `GET /v1/scrapes/{id}/leads.csv` | read | Download a scrape's delivered leads as one CSV file. |
| [`download_reviews`](https://docs.leadity.io/api-reference/scrapes/download-reviews) | `GET /v1/scrapes/{id}/reviews.csv` | read | Download the Google reviews a scrape walked, as one CSV file. |
| [`export_scrapes`](https://docs.leadity.io/api-reference/scrapes/export-scrapes) | `POST /v1/scrapes/export` | read | Download several scrapes' leads as one CSV file. |
| [`list_scrape_offers`](https://docs.leadity.io/api-reference/scrapes/list-scrape-offers) | `GET /v1/scrapes/{id}/offers` | read | List what a finished scrape can still sell, with prices. Free. |
| [`purchase_residuals`](https://docs.leadity.io/api-reference/scrapes/purchase-residuals) | `POST /v1/scrapes/{id}/residuals` | spend | Buy one cell of a finished scrape's held-back businesses. |
| [`purchase_phone_reveal`](https://docs.leadity.io/api-reference/scrapes/purchase-phone-reveal) | `POST /v1/scrapes/{id}/reveal-phones` | spend | Buy the phone line types of a finished scrape's delivered leads. |
| [`purchase_email_find`](https://docs.leadity.io/api-reference/scrapes/purchase-email-find) | `POST /v1/scrapes/{id}/emails/find` | spend | Buy email addresses for a finished scrape's delivered leads. |
| [`purchase_email_verify`](https://docs.leadity.io/api-reference/scrapes/purchase-email-verify) | `POST /v1/scrapes/{id}/emails/verify` | spend | Buy deliverability verdicts for a finished scrape's email addresses. |
| [`purchase_owner_names`](https://docs.leadity.io/api-reference/scrapes/purchase-owner-names) | `POST /v1/scrapes/{id}/owner-names` | spend | Buy owner names for a finished scrape's delivered leads. |

**Validations**

| Operation | Endpoint | Scope | Summary |
| --- | --- | --- | --- |
| [`preview_validation`](https://docs.leadity.io/api-reference/validations/preview-validation) | `POST /v1/validations/preview` | read | Quote a list for free: how many items survive parsing and what they cost. |
| [`create_validation`](https://docs.leadity.io/api-reference/validations/create-validation) | `POST /v1/validations` | spend | Validate a list of phone numbers or email addresses you supply. |
| [`list_validations`](https://docs.leadity.io/api-reference/validations/list-validations) | `GET /v1/validations` | read | List the account's validation runs, newest first. |
| [`download_validation`](https://docs.leadity.io/api-reference/validations/download-validation) | `GET /v1/validations/{id}.csv` | read | Download a validation run's answers as one CSV file. |
| [`get_validation`](https://docs.leadity.io/api-reference/validations/get-validation) | `GET /v1/validations/{id}` | read | Read one validation run, with its verdict counts. |
| [`list_validation_items`](https://docs.leadity.io/api-reference/validations/list-validation-items) | `GET /v1/validations/{id}/items` | read | Read a validation run's answers, a page at a time. |
| [`stop_validation`](https://docs.leadity.io/api-reference/validations/stop-validation) | `POST /v1/validations/{id}/stop` | write | Stop a live validation run: keep what it answered and refund the rest. |