> ## 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.

# Making requests

> The base URL, the request and response format, and the OpenAPI document.

## Base URL

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

Every path starts with `/v1`. The API only answers over HTTPS.

## Requests

- Send the key as `Authorization: Bearer lk_api_...` on every call. See [Authentication](https://docs.leadity.io/authentication).
- A `GET` takes its inputs as query parameters. A `POST` takes a JSON body with `Content-Type: application/json`.
- Path parameters are ids the API gave you, such as a scrape's `id` from [`create_scrape`](https://docs.leadity.io/api-reference/scrapes/create-scrape) or [`list_scrapes`](https://docs.leadity.io/api-reference/scrapes/list-scrapes). An id is letters and digits only, and anything else in its place is refused with `invalid_body`, its `issues` naming `path.id`, before the call reaches Leadity's servers.
- Every operation that takes credits also needs an `Idempotency-Key` header and a `maxCredits` field. See [Spending credits safely](https://docs.leadity.io/spending-credits).

```bash
curl -X POST "https://api.leadity.io/v1/scrapes/Vb7nW3xQ9k/rename" \
  -H "Authorization: Bearer $LEADITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "TX roofers, mobiles" }'
```

## Responses

A success answers `200` with a JSON body, except two kinds of answer: the file downloads answer a CSV file, and an operation that takes credits answers `201` when it buys. A retry of a purchase that went through carries the header `Idempotent-Replayed: true`, and a retried order or validation run answers `200` with `"replayed": true` (see [Idempotency](https://docs.leadity.io/idempotency)). A refusal answers a `4xx` or `5xx` status with the same small body every time:

```json
{
  "error": "insufficient_scope",
  "message": "The key does not carry the scope this operation needs."
}
```

Branch on `error`, which is a stable code, and show `message` to a person. Some codes carry extra fields, such as `retryAfterSeconds` on `rate_limited`. Every code and its fields are listed on [Errors](https://docs.leadity.io/errors).

Timestamps are ISO 8601 in UTC. Credits are whole numbers on the balance; a per-lead rate is given in thousandths of a credit (`leadRateMilli`) so the arithmetic stays exact.

## OpenAPI

The API publishes an OpenAPI 3.1 document, generated from the same definitions as this reference:

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

Point a client generator or an API tool at it to get every operation and schema.

## Versioning

The version is in the path. Within `/v1`, fields are added and never renamed or removed, so a client that ignores fields it does not know keeps working. A change that would break a client becomes a new operation.