# LeakRadar — Full Reference

> LeakRadar.io is a threat-intelligence platform that indexes 565B+ plain-text credentials from stealer logs, combolists, database breaches and dark-web dumps. This file is the complete LLM-friendly reference: product context, pricing, API concepts, and the full endpoint catalog generated from the live OpenAPI schema.

LeakRadar is built by Radar Forge SASU (France). It collects leaked credentials exclusively from public forums and Telegram channels, stores them as plain text (no hashes, no redaction), and provides real-time alerts when new records match monitored domains, emails or keywords. Alerts can be delivered via Email, Slack, Discord, Telegram or Webhook.

## Quick links

- Homepage: https://leakradar.io/en
- API base URL: https://api.leakradar.io
- Interactive docs (Redoc): https://docs.leakradar.io
- OpenAPI schema: https://api.leakradar.io/openapi.json
- Short LLM index: https://leakradar.io/llms.txt
- Python wrapper: https://github.com/LeakRadar/leakradar-wrapper (`pip install leakradar`)
- Status page: https://status.leakradar.io
- Contact: contact@leakradar.io

## Search Capabilities

LeakRadar supports five search modes. Email, Domain and Advanced query the same credential dataset parsed from stealer logs; Raw and Dark Web query separate datasets:

- **Email Search**: Query a single email address or username and retrieve every leak containing it.
- **Domain Search**: Map a domain's full exposure. Results are categorized into employees (`email_domain = company AND url_domain = company`), third-party accounts (`email_domain = company AND url_domain != company`), and customers (`url_domain = company AND email_domain != company`).
- **Advanced Search**: Combine criteria with boolean operators, wildcards and field filters across `url`, `url_host`, `url_domain`, `url_tld`, `url_scheme`, `url_port`, `username`, `password`, `email_host`, `email_domain`, `email_tld`.
- **Raw Search**: Full-text search across raw leak files and stealer logs. Browse containers, parts, and download files.
- **Dark Web Search**: Search dark web forum posts and mentions.

## Use Cases

- Bug Bounty: Find leaked credentials as part of vulnerability reports — https://leakradar.io/en/use-cases/bug-bounty
- Domain Monitoring: Continuous monitoring of corporate domain exposure — https://leakradar.io/en/use-cases/domain-monitoring
- Email Monitoring: Track specific email addresses across new leaks — https://leakradar.io/en/use-cases/email-monitoring
- Research: Threat intelligence research and analysis — https://leakradar.io/en/use-cases/research

## Pricing

All plans include unlimited searches. "Unlocks" reveal plain-text usernames and passwords. Annual billing saves 20%. Lifetime plans save 70% (no Lifetime tier on Unlimited).

### Plan comparison

| Plan        | Monthly  | Annual    | Lifetime   | Daily unlocks | Searches included          | Monitored assets | Unlocked-list limit | Team   | Downloads |
|-------------|----------|-----------|------------|---------------|----------------------------|------------------|---------------------|--------|-----------|
| **Starter** | €29.99   | €299.99   | €899.99    | 10,000        | Email + Domain             | 20               | 100                 | —      | —         |
| **Enterprise** | €69.99 | €699.99 | €2,099.99  | 100,000       | + Advanced + Dark Web      | 100              | 1,000               | up to 2 | —        |
| **Platinum** | €159.99 | €1,599.99 | €4,799.99  | 300,000       | + Raw                      | 1,000            | 2,000               | up to 5 | 50 GB    |
| **Unlimited** | €999.99 | €9,999.99 | —          | unlimited (no points) | All                | 10,000           | 3,000               | up to 10 | 500 GB |

All paid plans include API access and Export features.

### Payment

- Credit card via Stripe
- 100+ cryptocurrencies via NowPayments (Bitcoin, Monero, USDT, etc.)
- Custom plans on request: contact@leakradar.io
- Free lifetime access for law enforcement and military teams: contact@leakradar.io

## API Concepts

### Authentication

All endpoints require a Bearer token (API key) in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

Generate your API key from https://members.leakradar.io/settings?tab=api-key (paid plan required).

### Rate limits

| Context | Limit |
|---|---|
| Search (free user) | 5 req/sec |
| Search (paid subscriber) | 30 req/sec |
| Advanced search | 5 req/sec |
| Raw search | 5 req/sec |
| Unlock operations | 10 req/sec |

Exceeding a limit returns HTTP **429**. Every search response includes:

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Requests remaining before throttling |
| `X-RateLimit-Reset` | Seconds until the window resets |
| `Retry-After` | (on 429 only) seconds to wait before retrying |

Most HTTP libraries (httpx, requests, axios, fetch) honor `Retry-After` automatically.

### Concurrent jobs

Max export jobs per account with status `PENDING` or `IN_PROGRESS`:

| Export endpoint | Max |
|---|---|
| Email / Domain / Advanced / Raw | 5 |
| Advanced URLs | 1 |

Exceeding the concurrent export limit returns HTTP **400**.

Max unlock tasks per account with status `QUEUED` or `RUNNING`:

| Scope | Max |
|---|---|
| Email / Domain | 5 |
| Advanced / Raw | 2 |

Exceeding the concurrent unlock limit returns HTTP **429**.

### Points system

Every unlock consumes points from your account balance (subscription + extra points).
When `auto_unlock=true` is passed, items on the current page are automatically unlocked and points are deducted. If your balance is insufficient, a partial unlock is performed. The response field `auto_unlock_points_consumed` indicates how many points were used.

### Pagination

| Endpoint        | `page_size` range | Default |
|-----------------|-------------------|---------|
| Email search    | 1 – 100           | 10      |
| Advanced search | 1 – 1,000         | 100     |
| Raw search      | 1 – 100           | 10      |
| Raw parts       | 1 – 1,000         | 100     |

`page` starts at **1**.

**Deep pagination cap:** interactive paging is capped at `page * page_size <= 1,000,000`. Above this offset, requests return **400** with a hint to the bulk export endpoint. Affected endpoints:

- `GET /search/domain/{domain}/all`
- `GET /search/domain/{domain}/customers`
- `GET /search/domain/{domain}/employees`
- `GET /search/domain/{domain}/third_parties`
- `POST /search/advanced`

For large datasets, use the matching `/export` endpoint (returns up to 5M rows asynchronously).

### Date format

All datetime parameters must be **ISO 8601 with a timezone** (e.g. `2025-01-15T00:00:00Z`). Naive datetimes return HTTP **400**.

### Password strength

Leaked passwords are scored on an integer scale (0+). The API groups them into four categories:

| Category   | Score range |
|------------|-------------|
| `too_weak` | 0 – 2       |
| `weak`     | 3 – 4       |
| `medium`   | 5 – 7       |
| `strong`   | 8+          |

Response fields return the raw integer score. Filter parameters accept the category name.

## API Reference

This section catalogs every public endpoint, generated from the live OpenAPI schema (version `1.0.0`). Endpoints are grouped by their primary tag.

### Search Email

#### POST `/search/email`

**Search leaks by email or username**

Search for leaks associated with a specific email or username. Provide the search payload in the JSON body.

Pagination
- `page` starts at 1.
- `page_size` is 1 to 100 (default 100).

Access and visibility
- If your plan includes `email_search`, full URLs and item IDs are returned.
- Otherwise URLs are redacted except for the first 10 items per page and IDs are omitted.
- Credentials are returned only when `unlocked=true` and your plan includes `email_search`.

Auto-unlock
Pass `auto_unlock=true` to automatically unlock locked items on the current page. Points are consumed per newly unlocked item. If insufficient points, partial unlock is performed. The response field `auto_unlock_points_consumed` indicates how many points were used.

Response
`EmailSearchResponse` with `items`, `total`, `total_unlocked`, `page`, `page_size`.

Special case: if `email` is a full SHA-1 (40 hex chars, no '@'), search is done on username_hash exactly.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=100, default=`100`)_ |
| `auto_unlock` | boolean | no | Automatically unlock locked items on the current page using your points. _(default=`False`)_ |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `email` | string | yes | Email or username to search. _(maxLength=254)_ |
| `search` | string \| null | no | Optional free-text filter. |
| `is_email` | boolean \| null | no | Identifier type filter: true=email only, false=username only, null=both. |

**Responses:**

- `200` — Search results successfully returned.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (LeakDetails)> | yes | List of leak records for the current page. |
| `total` | integer | yes | Total number of matching leak records. |
| `total_unlocked` | integer | yes | Number of already-unlocked records in the total results. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
| `auto_unlock_points_consumed` | integer \| null | no | Number of points consumed by auto-unlock on this request. |
- `400` — Bad request.
- `422` — Validation error.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/email' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/search/email/export`

**Export leaks for an email to CSV/TXT/JSON**

Queue an export of all leaks that match the given email or username and optional filters. Provide the search payload in the JSON body.

Request body
- `email` the email or username to search.
- `search` optional free-text filter applied to URL or username.
- `is_email` optional boolean: `true` emails only, `false` usernames only, `null` both.

Query parameters
- `format` optional output format: `csv` (default), `txt`, or `json`.

Limits and plan requirement
- You can have at most 5 exports with status PENDING or IN_PROGRESS (per account).
- Requires a paid plan with `email_search` enabled.

Response
`ExportResponse` with `status`, `message`, and `export_id`.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `format` | string ('csv', 'txt', 'json') | no | Output format: csv (default), txt, or json. _(enum: 'csv', 'txt', 'json')_ |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `email` | string | yes | Email or username to search. _(maxLength=254)_ |
| `search` | string \| null | no | Optional free-text filter. |
| `is_email` | boolean \| null | no | Identifier type filter: true=email only, false=username only, null=both. |

**Responses:**

- `200` — Export job queued successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | yes | Export job status: 'queued', 'processing', 'completed', or 'failed'. |
| `message` | string | yes | Human-readable status message. |
| `export_id` | integer | yes | ID of the export job. Use this to check status or download the result. |
- `400` — No data found or concurrent export limit reached.
- `401` — Authentication required.
- `403` — Email search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/email/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/search/email/unlock`

**Unlock leaks for an email**

Unlock leaks for the given email or username. Provide the search payload in the JSON body. Use the `max` query parameter to cap how many new leaks to unlock. The effective limit is capped by your available points.

Request body
- `email` the email or username to search.
- `search` optional free-text filter applied to URL or username.
- `is_email` optional boolean: `true` emails only, `false` usernames only, `null` both.

Behavior
- Only previously locked items are unlocked. Already unlocked items are left unchanged.
- Only newly unlocked items consume points.
- If nothing new can be unlocked but matching unlocked items exist, those unlocked items are returned.
- **Hard cap**: synchronous unlocks are limited to 10,000. Use `/search/email/unlock/task` for higher volumes.

Plan requirement
Requires a paid plan with `email_search` enabled.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `max` | integer \| null | no | 0 or omitted = use all your points |
| `list_id` | integer \| null | no | Assign this list id to new unlocks. |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `email` | string | yes | Email or username to search. _(maxLength=254)_ |
| `search` | string \| null | no | Optional free-text filter. |
| `is_email` | boolean \| null | no | Identifier type filter: true=email only, false=username only, null=both. |

**Responses:**

- `200` — Unlocked leaks returned successfully.
- `400` — No data found, all data already unlocked, or insufficient points.
- `401` — Authentication required.
- `403` — Email search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded (10 req/sec).

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/email/unlock' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/search/email/unlock/task`

**Queue an async mass unlock task for an email**

Creates an **asynchronous** unlock Task for the given email/username + optional filters. Returns a `task_id` you can poll with the task-status endpoint.

max semantics
- Omit `max` or set `max=0` → use all your available points.
- Positive `max` → unlock up to that number (and ≤ your points).

**Concurrency limit**
- advanced / raw: max 2 concurrent tasks per user.
- email / domain: max 5 concurrent tasks per user.
- Returns 429 if limit exceeded.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `max` | integer \| null | no | 0 or omitted = use all your points |
| `list_id` | integer \| null | no | Assign this list id to new unlocks. |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `email` | string | yes | Email or username to search. _(maxLength=254)_ |
| `search` | string \| null | no | Optional free-text filter. |
| `is_email` | boolean \| null | no | Identifier type filter: true=email only, false=username only, null=both. |

**Responses:**

- `200` — Successful Response
- `422` — Validation Error
- `429` — Too many concurrent unlock tasks. Wait for existing tasks to complete.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/email/unlock/task' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/search/emails/locked-exists`

**Batch exists-check of still-locked leaks by email or username (account-specific)**

For up to 100 emails or usernames, returns booleans and optional counts indicating whether there are leaks that are still locked for the current account. Use include_counts=true to also get locked/total/unlocked counts.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `emails` | array<string> | yes | List of emails or usernames, max 100. |
| `include_counts` | boolean | no | If true, also include counts (locked/total/unlocked). _(default=`False`)_ |

**Responses:**

- `200` — Successful Response

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | array<object (EmailMassResult)> | yes |  |
- `422` — Validation Error
- `429` — Rate limit exceeded

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/emails/locked-exists' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

### Search Domain

#### GET `/search/domain/{domain}`

**Get leak report for a domain**

Return a domain leak report. If unauthenticated, `light=true` is forced.

**Modes**
- `light=true`: returns sampled counts only.
- `light=false` (authenticated): returns exact counts plus password stats per group.

**Parameters**
- `include_search_count=true`: include the number of distinct users who searched this domain in the last 7 days (`searched_by_count`). Disabled by default to avoid an expensive SQL query.

**Caching**
- Light up to 24 hours, full up to 1 hour.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `light` | boolean | no | _(default=`False`)_ |
| `include_search_count` | boolean | no | _(default=`False`)_ |

**Responses:**

- `200` — Results returned successfully.
- `400` — Invalid domain or insufficient points.
- `401` — Authentication required.
- `403` — Domain search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/domain/<domain>' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/search/domain/{domain}/all`

**List all leaks for a domain (employees + customers + third parties)**

Return a paginated list of **all** leaks linked to a domain, regardless of
category (employees, customers, third parties).

Each item includes a `category` field indicating whether the leak belongs
to employees, customers, or third parties.

**Query parameters**
- `page` starts at 1.
- `page_size` is 1 to 1000 (default 100).
- `search` optional term to narrow results.
- `is_email` optional boolean to filter emails (true), usernames (false), or both (null).

**Access and visibility**
- If your plan includes `domain_search`, full URLs and item IDs are returned.
- Otherwise URLs are redacted except for the first 10 items per page and IDs are omitted.
- Credentials are included only for items with `unlocked=true` and if your plan includes `domain_search`.

**Response**
`PaginatedAllLeaksResponse` with `items`, `total`, `total_unlocked`, `page`, `page_size`.

**Auto-unlock**
Pass `auto_unlock=true` to automatically unlock locked items on the current page. Points are consumed per newly unlocked item. If insufficient points, partial unlock is performed. The response field `auto_unlock_points_consumed` indicates how many points were used.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string \| null | no | Optional search term to filter results. |
| `is_email` | boolean \| null | no |  |
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=1000, default=`100`)_ |
| `auto_unlock` | boolean | no | Automatically unlock locked items on the current page using your points. _(default=`False`)_ |

**Responses:**

- `200` — Leaks returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (AllLeakDetails)> | yes | List of leak records for the current page. |
| `total` | integer | yes | Total number of matching leak records. |
| `total_unlocked` | integer | yes | Number of already-unlocked records in the total results. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
| `auto_unlock_points_consumed` | integer \| null | no | Number of points consumed by auto-unlock on this request. |
- `400` — Invalid domain or insufficient points, or pagination too deep (offset > 1,000,000 — use the matching `/export` endpoint).
- `401` — Authentication required.
- `403` — Domain search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded. Response includes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/domain/<domain>/all' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/search/domain/{domain}/customers`

**List leaks for customers of a domain**

Return a paginated list of leaks linked to customers of the given domain.

**Query parameters**
- `page` starts at 1.
- `page_size` is 1 to 1000 (default 100).
- `search` optional term to narrow results.
- `is_email` optional boolean to filter emails (true), usernames (false), or both (null).

**Access and visibility**
- If your plan includes `domain_search`, full URLs and item IDs are returned.
- Otherwise URLs are redacted except for the first 10 items per page and IDs are omitted.
- Credentials are included only for items with `unlocked=true` and if your plan includes `domain_search`.

**Response**
`PaginatedLeaksResponse` with `items`, `total`, `total_unlocked`, `page`, `page_size`.

**Auto-unlock**
Pass `auto_unlock=true` to automatically unlock locked items on the current page. Points are consumed per newly unlocked item. If insufficient points, partial unlock is performed. The response field `auto_unlock_points_consumed` indicates how many points were used.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | Page number. _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | Number of results per page. _(minimum=1, maximum=1000, default=`100`)_ |
| `search` | string \| null | no | Optional search term to filter results. |
| `is_email` | boolean \| null | no |  |
| `auto_unlock` | boolean | no | Automatically unlock locked items on the current page using your points. _(default=`False`)_ |

**Responses:**

- `200` — Results returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (LeakDetails)> | yes | List of leak records for the current page. |
| `total` | integer | yes | Total number of matching leak records. |
| `total_unlocked` | integer | yes | Number of already-unlocked records in the total results. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
| `auto_unlock_points_consumed` | integer \| null | no | Number of points consumed by auto-unlock on this request. |
- `400` — Invalid domain or insufficient points, or pagination too deep (offset > 1,000,000 — use the matching `/export` endpoint).
- `401` — Authentication required.
- `403` — Domain search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded. Response includes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/domain/<domain>/customers' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/search/domain/{domain}/employees`

**List leaks for employees of a domain**

Return a paginated list of leaks linked to employees of the given domain.

**Query parameters**
- `page` starts at 1.
- `page_size` is 1 to 1000 (default 100).
- `search` optional term to narrow results.
- `is_email` optional boolean to filter emails (true), usernames (false), or both (null).

**Access and visibility**
- If your plan includes `domain_search`, full URLs and item IDs are returned.
- Otherwise URLs are redacted except for the first 10 items per page and IDs are omitted.
- Credentials are included only for items with `unlocked=true` and if your plan includes `domain_search`.

**Response**
`PaginatedLeaksResponse` with `items`, `total`, `total_unlocked`, `page`, `page_size`.

**Auto-unlock**
Pass `auto_unlock=true` to automatically unlock locked items on the current page. Points are consumed per newly unlocked item. If insufficient points, partial unlock is performed. The response field `auto_unlock_points_consumed` indicates how many points were used.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string \| null | no | Optional search term to filter results. |
| `is_email` | boolean \| null | no |  |
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=1000, default=`100`)_ |
| `auto_unlock` | boolean | no | Automatically unlock locked items on the current page using your points. _(default=`False`)_ |

**Responses:**

- `200` — Results returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (LeakDetails)> | yes | List of leak records for the current page. |
| `total` | integer | yes | Total number of matching leak records. |
| `total_unlocked` | integer | yes | Number of already-unlocked records in the total results. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
| `auto_unlock_points_consumed` | integer \| null | no | Number of points consumed by auto-unlock on this request. |
- `400` — Invalid domain or insufficient points, or pagination too deep (offset > 1,000,000 — use the matching `/export` endpoint).
- `401` — Authentication required.
- `403` — Domain search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded. Response includes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/domain/<domain>/employees' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/search/domain/{domain}/report/pdf`

**Download domain report as PDF**

Generate and download a PDF report for the given domain.

**Content**
- Aggregated counts for compromised employees, third parties, and customers.
- Aggregated password statistics per group when available.

**Errors**
- 400 The `domain` parameter cannot be empty.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |

**Responses:**

- `200` — PDF report for the requested domain.
- `400` — Bad request - invalid domain.
- `401` — Unauthorized.
- `404` — Domain not found or no data available.
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/domain/<domain>/report/pdf' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/search/domain/{domain}/subdomains`

**List subdomains for a domain**

Return a paginated list of distinct subdomains for the given domain with their occurrence counts.

**Query parameters**
- `page` starts at 1.
- `page_size` is 1 to 1000 (default 100).
- `search` optional wildcard filter on subdomain.

**Access and visibility**
- If your plan includes `domain_search`, full subdomains are returned.
- Otherwise subdomains are redacted except for the first 10 items per page. If `search` is provided and you are not entitled, results are redacted.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string \| null | no |  |
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=1000, default=`100`)_ |

**Responses:**

- `200` — Results returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (SubdomainOccurrences)> | yes | List of items for the current page. |
| `total` | integer | yes | Total number of matching items. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
- `400` — Invalid domain or insufficient points.
- `401` — Authentication required.
- `403` — Domain search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/domain/<domain>/subdomains' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/search/domain/{domain}/subdomains/export`

**Export all subdomains for a domain as CSV/TXT/JSON**

Generate an on-demand export of all distinct subdomains for the given domain. The export contains a single `Subdomain` column.

**Plan requirement**
Requires a paid plan with `domain_search` enabled.

**Parameters**
- You can provide `search` either as a query parameter or in the JSON body. If both are provided, the JSON body value takes precedence.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string \| null | no | Optional wildcard filter on subdomain when using query parameters. If also provided in the JSON body, the body value takes precedence. |
| `format` | string ('csv', 'txt', 'json') | no | Output format: csv (default), txt, or json. _(enum: 'csv', 'txt', 'json')_ |

**Request body** (optional, `application/json`):

Type: `object (DomainSubdomainsExportBody) \| null`

**Responses:**

- `200` — Results returned successfully.
- `400` — Invalid domain or insufficient points.
- `401` — Authentication required.
- `403` — Domain search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/domain/<domain>/subdomains/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### GET `/search/domain/{domain}/third_parties`

**List leaks for third parties of a domain**

Return a paginated list of leaks linked to third parties of the given domain.

**Query parameters**
- `page` starts at 1.
- `page_size` is 1 to 1000 (default 100).
- `search` optional term to narrow results.
- `is_email` optional boolean to filter emails (true), usernames (false), or both (null).

**Access and visibility**
- If your plan includes `domain_search`, full URLs and item IDs are returned.
- Otherwise URLs are redacted except for the first 10 items per page and IDs are omitted.
- Credentials are included only for items with `unlocked=true` and if your plan includes `domain_search`.

**Response**
`PaginatedLeaksResponse` with `items`, `total`, `total_unlocked`, `page`, `page_size`.

**Auto-unlock**
Pass `auto_unlock=true` to automatically unlock locked items on the current page. Points are consumed per newly unlocked item. If insufficient points, partial unlock is performed. The response field `auto_unlock_points_consumed` indicates how many points were used.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=1000, default=`100`)_ |
| `search` | string \| null | no | Optional search term to filter results. |
| `is_email` | boolean \| null | no |  |
| `auto_unlock` | boolean | no | Automatically unlock locked items on the current page using your points. _(default=`False`)_ |

**Responses:**

- `200` — Results returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (LeakDetails)> | yes | List of leak records for the current page. |
| `total` | integer | yes | Total number of matching leak records. |
| `total_unlocked` | integer | yes | Number of already-unlocked records in the total results. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
| `auto_unlock_points_consumed` | integer \| null | no | Number of points consumed by auto-unlock on this request. |
- `400` — Invalid domain or insufficient points, or pagination too deep (offset > 1,000,000 — use the matching `/export` endpoint).
- `401` — Authentication required.
- `403` — Domain search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded. Response includes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/domain/<domain>/third_parties' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/search/domain/{domain}/urls`

**List URLs for a domain**

Return a paginated list of distinct URLs for the given domain with their occurrence counts.

**Query parameters**
- `page` starts at 1.
- `page_size` is 1 to 1000 (default 100).
- `search` optional wildcard filter on URL.

**Access and visibility**
- If your plan includes `domain_search`, full URLs are returned.
- Otherwise URLs are redacted except for the first 10 items per page. If `search` is provided and you are not entitled, results are redacted.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string \| null | no | Optional wildcard filter on url. |
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=1000, default=`100`)_ |

**Responses:**

- `200` — Results returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (URLOccurrences)> | yes | List of items for the current page. |
| `total` | integer | yes | Total number of matching items. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
- `400` — Invalid domain or insufficient points.
- `401` — Authentication required.
- `403` — Domain search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/domain/<domain>/urls' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/search/domain/{domain}/urls/export`

**Export all URLs for a domain as CSV/TXT/JSON**

Generate an on-demand export of all distinct URLs for the given domain. The export contains a single `URL` column and is capped at 100,000 rows.

**Plan requirement**
Requires a paid plan with `domain_search` enabled.

**Parameters**
- You can provide `search` either as a query parameter or in the JSON body. If both are provided, the JSON body value takes precedence.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string \| null | no | Optional search term to filter results when using query parameters. If also provided in the JSON body, the body value takes precedence. |
| `format` | string ('csv', 'txt', 'json') | no | Output format: csv (default), txt, or json. _(enum: 'csv', 'txt', 'json')_ |

**Request body** (optional, `application/json`):

Type: `object (DomainURLsExportBody) \| null`

**Responses:**

- `200` — Results returned successfully.
- `400` — Invalid domain or insufficient points.
- `401` — Authentication required.
- `403` — Domain search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/domain/<domain>/urls/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/search/domain/{domain}/{leak_type}/export`

**Export domain leaks to CSV/TXT/JSON**

Queue an export of all leaks for the given domain and leak type (valid values: `employees`, `customers`, `third_parties`, `all`). The job runs asynchronously and the file will appear in the Exports section when ready.

**Parameters**
- You can provide `search`, `is_email`, and `format` either as query parameters or in the JSON body. If both are provided, the JSON body values take precedence.

**Query parameters**
- `search` optional term to narrow results.
- `is_email` optional boolean to filter emails (true), usernames (false), or both (null).
- `format` optional output format: `csv` (default), `txt`, or `json`.

**Limits and plan requirement**
- You can have at most 5 exports with status PENDING or IN_PROGRESS (per account).
- Requires a paid plan with `domain_search` enabled.

**Response**
`ExportResponse` with `status`, `message`, and `export_id`.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |
| `leak_type` | string ('employees', 'third_parties', 'customers', 'all') | yes | _(enum: 'employees', 'third_parties', 'customers', 'all')_ |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string \| null | no | Optional term to narrow results when using query parameters. If also provided in the JSON body, the body value takes precedence. |
| `is_email` | boolean \| null | no | Optional boolean to filter emails (true), usernames (false), or both (null). If also provided in the JSON body, the body value takes precedence. |
| `format` | string ('csv', 'txt', 'json') | no | Output format: csv (default), txt, or json. _(enum: 'csv', 'txt', 'json')_ |

**Request body** (optional, `application/json`):

Type: `object (DomainExportBody) \| null`

**Responses:**

- `200` — Results returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | yes | Export job status: 'queued', 'processing', 'completed', or 'failed'. |
| `message` | string | yes | Human-readable status message. |
| `export_id` | integer | yes | ID of the export job. Use this to check status or download the result. |
- `400` — Invalid domain or insufficient points.
- `401` — Authentication required.
- `403` — Domain search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/domain/<domain>/<leak_type>/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/search/domain/{domain}/{leak_type}/unlock`

**Unlock leaks for a domain**

Unlock leaks for the given domain and leak type (valid values: `employees`, `customers`, `third_parties`). Use `max` to cap how many new leaks to unlock. The effective limit is capped by your available points.

Behavior
- Only previously locked items are unlocked. Already unlocked items are left unchanged.
- Only newly unlocked items consume points.
- **Hard cap**: synchronous unlocks are limited to 10,000. Use `/search/domain/{domain}/{leak_type}/unlock/task` for higher volumes.

Plan requirement
Requires a paid plan with `domain_search` enabled.

Errors
- 400 The `domain` parameter is required, no data found matching the criteria, insufficient points, or too many unlocks for sync (>10k).
- 403 Domain search is not available on your plan.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |
| `leak_type` | string ('employees', 'third_parties', 'customers', 'all') | yes | _(enum: 'employees', 'third_parties', 'customers', 'all')_ |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string \| null | no | Optional search term to filter results. |
| `is_email` | boolean \| null | no | Filter on e-mails (`true`), usernames (`false`) or both (`null`). |
| `max` | integer \| null | no | Maximum number of leaks to unlock. |
| `list_id` | integer \| null | no | Assign this list id to new unlocks. |

**Responses:**

- `200` — Results returned successfully.
- `400` — Invalid domain or insufficient points.
- `401` — Authentication required.
- `403` — Domain search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/domain/<domain>/<leak_type>/unlock' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/search/domain/{domain}/{leak_type}/unlock/task`

**Queue an async mass unlock task for a domain**

Creates an asynchronous unlock **Task** for the given domain and leak type. Returns a `task_id` for polling.

**Concurrency limit**
- advanced / raw: max 2 concurrent tasks per user.
- email / domain: max 5 concurrent tasks per user.
- Returns 429 if limit exceeded.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `domain` | string | yes |  |
| `leak_type` | string ('employees', 'third_parties', 'customers', 'all') | yes | _(enum: 'employees', 'third_parties', 'customers', 'all')_ |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string \| null | no | Optional search term. |
| `is_email` | boolean \| null | no | True=email only, false=username only, null=both. |
| `max` | integer \| null | no | Optional cap for new unlocks. |
| `list_id` | integer \| null | no | Assign this list id to new unlocks. |

**Responses:**

- `200` — Successful Response
- `422` — Validation Error
- `429` — Too many concurrent unlock tasks. Wait for existing tasks to complete.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/domain/<domain>/<leak_type>/unlock/task' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/search/domains/locked-exists`

**Batch exists-check of still-locked leaks by domain and category (account-specific)**

For up to 100 domains, returns per-category booleans indicating whether there are leaks that are still locked for the current account (total minus the account's unlocked items). Use include_counts=true to also get locked/total/unlocked counts.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `domains` | array<string> | yes | List of domains, max 100. |
| `categories` | array<(recursive)> \| null | no | Subset among employees, customers, third_parties. If omitted -> all. |
| `include_counts` | boolean | no | If true, also include counts (locked/total/unlocked). _(default=`False`)_ |

**Responses:**

- `200` — Successful Response

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `results` | array<object (DomainMassResult)> | yes |  |
- `422` — Validation Error
- `429` — Rate limit exceeded

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/domains/locked-exists' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

### Search Advanced

#### POST `/search/advanced`

**Search leaks with advanced filters (JSON body)**

Search leaked credentials using any combination of fields defined in `LeakSearchFilters`.

**Pagination:** `page` ≥ 1, `page_size` in [1, 1 000] (default 100).

**Access:** If your plan includes `advanced_search`, full URLs and item IDs are returned; otherwise redacted.

**Rate limit:** 5 requests per second per user.

**Auto-unlock:**
Pass `auto_unlock=true` to automatically unlock locked items on the current page. Points are consumed per newly unlocked item. If insufficient points, partial unlock is performed. The response field `auto_unlock_points_consumed` indicates how many points were used.

---

**Filter limits:**

| Constraint | Value |
|------------|-------|
| Max values per filter field | 50 |
| Min characters per value (default) | 3 |
| Min characters for `url_scheme`, `url_tld`, `email_tld` | 2 |
| Min characters for `username_hash`, `password_hash` | 4 |
| Max characters per string value | 100 |
| Max characters for `url_scheme` | 20 |
| Max characters for `url_tld`, `email_tld` | 10 |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=1000, default=`100`)_ |
| `auto_unlock` | boolean | no | Automatically unlock locked items on the current page using your points. _(default=`False`)_ |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `username` | array<string> \| null | no | Username must contain. |
| `username_not` | array<string> \| null | no | Exclude usernames containing these values. |
| `password` | array<string> \| null | no | Password must contain. |
| `password_not` | array<string> \| null | no | Exclude passwords containing these values. |
| `url` | array<string> \| null | no | URL must contain. |
| `url_not` | array<string> \| null | no | Exclude URLs containing these values. |
| `url_domain` | array<string> \| null | no | URL domain must contain. |
| `url_domain_not` | array<string> \| null | no | Exclude URL domains containing these values. |
| `url_host` | array<string> \| null | no | URL host must contain. |
| `url_host_not` | array<string> \| null | no | Exclude URL hosts containing these values. |
| `username_hash` | array<string> \| null | no | Username SHA-1 hash prefix (hex). |
| `password_hash` | array<string> \| null | no | Password SHA-1 hash prefix (hex). |
| `url_scheme` | array<string> \| null | no | URL scheme(s) to include (multi). |
| `url_scheme_not` | array<string> \| null | no | URL scheme(s) to exclude (multi). |
| `url_port` | array<integer> \| null | no | URL port(s) to include (multi). |
| `url_port_not` | array<integer> \| null | no | URL port(s) to exclude (multi). |
| `url_tld` | array<string> \| null | no | URL TLD(s) to include (multi). |
| `url_tld_not` | array<string> \| null | no | URL TLD(s) to exclude (multi). |
| `is_email` | boolean \| null | no | Identifier type filter: true=email only, false=username only, null=both. |
| `email_domain` | array<string> \| null | no | Email domain must contain. |
| `email_domain_not` | array<string> \| null | no | Exclude email domains containing these values. |
| `email_host` | array<string> \| null | no | Email host must contain. |
| `email_host_not` | array<string> \| null | no | Exclude email hosts containing these values. |
| `email_tld` | array<string> \| null | no | Email TLD(s) to include (multi). |
| `email_tld_not` | array<string> \| null | no | Email TLD(s) to exclude (multi). |
| `password_strength` | string ('too_weak', 'weak', 'medium', 'strong') \| null | no | Filter by password strength category. too_weak = score 0-2, weak = 3-4, medium = 5-7, strong = 8+. |
| `added_from` | string \| null | no | Only include leaks indexed on/after this UTC datetime. |
| `added_to` | string \| null | no | Only include leaks indexed on/before this UTC datetime. |
| `force_and` | boolean \| null | no | When true, require all values within each field (AND within field). |

**Responses:**

- `200` — Search results returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (LeakDetails)> | yes | List of leak records for the current page. |
| `total` | integer | yes | Total number of matching leak records. |
| `total_unlocked` | integer | yes | Number of already-unlocked records in the total results. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
| `auto_unlock_points_consumed` | integer \| null | no | Number of points consumed by auto-unlock on this request. |
- `400` — Invalid filters or insufficient points, or pagination too deep (offset > 1,000,000 — use `/search/advanced/export`).
- `401` — Authentication required.
- `403` — Advanced search not included in your plan.
- `422` — Validation error in filter parameters.
- `429` — Rate limit exceeded (5 req/sec). Response includes `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/advanced' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/search/advanced/export`

**Export leaks to CSV/TXT/JSON**

Queue an export of all leaks that match the provided advanced search filters. At least one filter is required.

Request body
- JSON payload following the `LeakSearchFilters` schema.

Query parameters
- `format` optional output format: `csv` (default), `txt`, or `json`.

Limits and plan requirement
- You can have at most 5 exports with status PENDING or IN_PROGRESS per account.
- Requires a paid plan with `advanced_search` enabled.

Response
`ExportResponse` with `status`, `message`, and `export_id`.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `format` | string ('csv', 'txt', 'json') | no | Output format: csv (default), txt, or json. _(enum: 'csv', 'txt', 'json')_ |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `username` | array<string> \| null | no | Username must contain. |
| `username_not` | array<string> \| null | no | Exclude usernames containing these values. |
| `password` | array<string> \| null | no | Password must contain. |
| `password_not` | array<string> \| null | no | Exclude passwords containing these values. |
| `url` | array<string> \| null | no | URL must contain. |
| `url_not` | array<string> \| null | no | Exclude URLs containing these values. |
| `url_domain` | array<string> \| null | no | URL domain must contain. |
| `url_domain_not` | array<string> \| null | no | Exclude URL domains containing these values. |
| `url_host` | array<string> \| null | no | URL host must contain. |
| `url_host_not` | array<string> \| null | no | Exclude URL hosts containing these values. |
| `username_hash` | array<string> \| null | no | Username SHA-1 hash prefix (hex). |
| `password_hash` | array<string> \| null | no | Password SHA-1 hash prefix (hex). |
| `url_scheme` | array<string> \| null | no | URL scheme(s) to include (multi). |
| `url_scheme_not` | array<string> \| null | no | URL scheme(s) to exclude (multi). |
| `url_port` | array<integer> \| null | no | URL port(s) to include (multi). |
| `url_port_not` | array<integer> \| null | no | URL port(s) to exclude (multi). |
| `url_tld` | array<string> \| null | no | URL TLD(s) to include (multi). |
| `url_tld_not` | array<string> \| null | no | URL TLD(s) to exclude (multi). |
| `is_email` | boolean \| null | no | Identifier type filter: true=email only, false=username only, null=both. |
| `email_domain` | array<string> \| null | no | Email domain must contain. |
| `email_domain_not` | array<string> \| null | no | Exclude email domains containing these values. |
| `email_host` | array<string> \| null | no | Email host must contain. |
| `email_host_not` | array<string> \| null | no | Exclude email hosts containing these values. |
| `email_tld` | array<string> \| null | no | Email TLD(s) to include (multi). |
| `email_tld_not` | array<string> \| null | no | Email TLD(s) to exclude (multi). |
| `password_strength` | string ('too_weak', 'weak', 'medium', 'strong') \| null | no | Filter by password strength category. too_weak = score 0-2, weak = 3-4, medium = 5-7, strong = 8+. |
| `added_from` | string \| null | no | Only include leaks indexed on/after this UTC datetime. |
| `added_to` | string \| null | no | Only include leaks indexed on/before this UTC datetime. |
| `force_and` | boolean \| null | no | When true, require all values within each field (AND within field). |

**Responses:**

- `200` — Export job queued.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | yes | Export job status: 'queued', 'processing', 'completed', or 'failed'. |
| `message` | string | yes | Human-readable status message. |
| `export_id` | integer | yes | ID of the export job. Use this to check status or download the result. |
- `400` — No data or concurrent export limit reached.
- `401` — Authentication required.
- `403` — Advanced search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/advanced/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/search/advanced/export_urls`

**Export distinct URLs to CSV/TXT/JSON**

Queue an export of all distinct URLs from leaks that match the provided advanced search filters. Provide the filters in the JSON request body.

Request body
- `filters` payload following `LeakSearchFilters` fields.

Query parameters
- `format` optional output format: `csv` (default), `txt`, or `json`.

Limits and plan requirement
- At least one filter is required.
- You can have at most 1 export with status PENDING or IN_PROGRESS per account.
- Requires a paid plan with `advanced_search` enabled.

Response
`ExportResponse` with `status`, `message`, and `export_id`.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `format` | string ('csv', 'txt', 'json') | no | Output format: csv (default), txt, or json. _(enum: 'csv', 'txt', 'json')_ |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `username` | array<string> \| null | no | Username must contain. |
| `username_not` | array<string> \| null | no | Exclude usernames containing these values. |
| `password` | array<string> \| null | no | Password must contain. |
| `password_not` | array<string> \| null | no | Exclude passwords containing these values. |
| `url` | array<string> \| null | no | URL must contain. |
| `url_not` | array<string> \| null | no | Exclude URLs containing these values. |
| `url_domain` | array<string> \| null | no | URL domain must contain. |
| `url_domain_not` | array<string> \| null | no | Exclude URL domains containing these values. |
| `url_host` | array<string> \| null | no | URL host must contain. |
| `url_host_not` | array<string> \| null | no | Exclude URL hosts containing these values. |
| `username_hash` | array<string> \| null | no | Username SHA-1 hash prefix (hex). |
| `password_hash` | array<string> \| null | no | Password SHA-1 hash prefix (hex). |
| `url_scheme` | array<string> \| null | no | URL scheme(s) to include (multi). |
| `url_scheme_not` | array<string> \| null | no | URL scheme(s) to exclude (multi). |
| `url_port` | array<integer> \| null | no | URL port(s) to include (multi). |
| `url_port_not` | array<integer> \| null | no | URL port(s) to exclude (multi). |
| `url_tld` | array<string> \| null | no | URL TLD(s) to include (multi). |
| `url_tld_not` | array<string> \| null | no | URL TLD(s) to exclude (multi). |
| `is_email` | boolean \| null | no | Identifier type filter: true=email only, false=username only, null=both. |
| `email_domain` | array<string> \| null | no | Email domain must contain. |
| `email_domain_not` | array<string> \| null | no | Exclude email domains containing these values. |
| `email_host` | array<string> \| null | no | Email host must contain. |
| `email_host_not` | array<string> \| null | no | Exclude email hosts containing these values. |
| `email_tld` | array<string> \| null | no | Email TLD(s) to include (multi). |
| `email_tld_not` | array<string> \| null | no | Email TLD(s) to exclude (multi). |
| `password_strength` | string ('too_weak', 'weak', 'medium', 'strong') \| null | no | Filter by password strength category. too_weak = score 0-2, weak = 3-4, medium = 5-7, strong = 8+. |
| `added_from` | string \| null | no | Only include leaks indexed on/after this UTC datetime. |
| `added_to` | string \| null | no | Only include leaks indexed on/before this UTC datetime. |
| `force_and` | boolean \| null | no | When true, require all values within each field (AND within field). |

**Responses:**

- `200` — Export job queued.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | yes | Export job status: 'queued', 'processing', 'completed', or 'failed'. |
| `message` | string | yes | Human-readable status message. |
| `export_id` | integer | yes | ID of the export job. Use this to check status or download the result. |
- `400` — No data or concurrent export limit reached.
- `401` — Authentication required.
- `403` — Advanced search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/advanced/export_urls' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/search/advanced/unlock`

**Unlock leaks for advanced search**

Unlock leaks returned by the same advanced search filters as `/search/advanced`. Provide filters in the JSON body. Optional query parameter `max` limits how many new leaks to unlock.

**Behavior**
- If `max` is omitted, the service unlocks as many as your available points allow (subscription + extra).
- Only previously locked items are unlocked. Already unlocked items remain unchanged.
- Only newly unlocked items consume points.
- **Hard cap**: synchronous unlocks are limited to 10,000. Use `/search/advanced/unlock/task` for higher volumes.

**Plan requirement**
Requires a paid plan with `advanced_search` enabled.

**Errors**
- 400 No data found for these filters.
- 400 All data already unlocked.
- 400 Insufficient points.
- 400 Too many unlocks for synchronous endpoint (>10k).
- 403 Advanced search is not available on your plan.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `max` | integer \| null | no | 0 or omitted = use all your points |
| `list_id` | integer \| null | no | Assign this list id to new unlocks. |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `username` | array<string> \| null | no | Username must contain. |
| `username_not` | array<string> \| null | no | Exclude usernames containing these values. |
| `password` | array<string> \| null | no | Password must contain. |
| `password_not` | array<string> \| null | no | Exclude passwords containing these values. |
| `url` | array<string> \| null | no | URL must contain. |
| `url_not` | array<string> \| null | no | Exclude URLs containing these values. |
| `url_domain` | array<string> \| null | no | URL domain must contain. |
| `url_domain_not` | array<string> \| null | no | Exclude URL domains containing these values. |
| `url_host` | array<string> \| null | no | URL host must contain. |
| `url_host_not` | array<string> \| null | no | Exclude URL hosts containing these values. |
| `username_hash` | array<string> \| null | no | Username SHA-1 hash prefix (hex). |
| `password_hash` | array<string> \| null | no | Password SHA-1 hash prefix (hex). |
| `url_scheme` | array<string> \| null | no | URL scheme(s) to include (multi). |
| `url_scheme_not` | array<string> \| null | no | URL scheme(s) to exclude (multi). |
| `url_port` | array<integer> \| null | no | URL port(s) to include (multi). |
| `url_port_not` | array<integer> \| null | no | URL port(s) to exclude (multi). |
| `url_tld` | array<string> \| null | no | URL TLD(s) to include (multi). |
| `url_tld_not` | array<string> \| null | no | URL TLD(s) to exclude (multi). |
| `is_email` | boolean \| null | no | Identifier type filter: true=email only, false=username only, null=both. |
| `email_domain` | array<string> \| null | no | Email domain must contain. |
| `email_domain_not` | array<string> \| null | no | Exclude email domains containing these values. |
| `email_host` | array<string> \| null | no | Email host must contain. |
| `email_host_not` | array<string> \| null | no | Exclude email hosts containing these values. |
| `email_tld` | array<string> \| null | no | Email TLD(s) to include (multi). |
| `email_tld_not` | array<string> \| null | no | Email TLD(s) to exclude (multi). |
| `password_strength` | string ('too_weak', 'weak', 'medium', 'strong') \| null | no | Filter by password strength category. too_weak = score 0-2, weak = 3-4, medium = 5-7, strong = 8+. |
| `added_from` | string \| null | no | Only include leaks indexed on/after this UTC datetime. |
| `added_to` | string \| null | no | Only include leaks indexed on/before this UTC datetime. |
| `force_and` | boolean \| null | no | When true, require all values within each field (AND within field). |

**Responses:**

- `200` — Successful Response
- `422` — Validation Error

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/advanced/unlock' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/search/advanced/unlock/task`

**Queue an async mass unlock task for advanced search**

Creates an asynchronous unlock **Task** for the given advanced filters. Returns a `task_id` you can poll with the task-status endpoint.

**Concurrency limit**
- advanced / raw: max 2 concurrent tasks per user.
- email / domain: max 5 concurrent tasks per user.
- Returns 429 if limit exceeded.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `max` | integer \| null | no | Optional cap of new unlocks. |
| `list_id` | integer \| null | no | Assign this list id to new unlocks. |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `username` | array<string> \| null | no | Username must contain. |
| `username_not` | array<string> \| null | no | Exclude usernames containing these values. |
| `password` | array<string> \| null | no | Password must contain. |
| `password_not` | array<string> \| null | no | Exclude passwords containing these values. |
| `url` | array<string> \| null | no | URL must contain. |
| `url_not` | array<string> \| null | no | Exclude URLs containing these values. |
| `url_domain` | array<string> \| null | no | URL domain must contain. |
| `url_domain_not` | array<string> \| null | no | Exclude URL domains containing these values. |
| `url_host` | array<string> \| null | no | URL host must contain. |
| `url_host_not` | array<string> \| null | no | Exclude URL hosts containing these values. |
| `username_hash` | array<string> \| null | no | Username SHA-1 hash prefix (hex). |
| `password_hash` | array<string> \| null | no | Password SHA-1 hash prefix (hex). |
| `url_scheme` | array<string> \| null | no | URL scheme(s) to include (multi). |
| `url_scheme_not` | array<string> \| null | no | URL scheme(s) to exclude (multi). |
| `url_port` | array<integer> \| null | no | URL port(s) to include (multi). |
| `url_port_not` | array<integer> \| null | no | URL port(s) to exclude (multi). |
| `url_tld` | array<string> \| null | no | URL TLD(s) to include (multi). |
| `url_tld_not` | array<string> \| null | no | URL TLD(s) to exclude (multi). |
| `is_email` | boolean \| null | no | Identifier type filter: true=email only, false=username only, null=both. |
| `email_domain` | array<string> \| null | no | Email domain must contain. |
| `email_domain_not` | array<string> \| null | no | Exclude email domains containing these values. |
| `email_host` | array<string> \| null | no | Email host must contain. |
| `email_host_not` | array<string> \| null | no | Exclude email hosts containing these values. |
| `email_tld` | array<string> \| null | no | Email TLD(s) to include (multi). |
| `email_tld_not` | array<string> \| null | no | Email TLD(s) to exclude (multi). |
| `password_strength` | string ('too_weak', 'weak', 'medium', 'strong') \| null | no | Filter by password strength category. too_weak = score 0-2, weak = 3-4, medium = 5-7, strong = 8+. |
| `added_from` | string \| null | no | Only include leaks indexed on/after this UTC datetime. |
| `added_to` | string \| null | no | Only include leaks indexed on/before this UTC datetime. |
| `force_and` | boolean \| null | no | When true, require all values within each field (AND within field). |

**Responses:**

- `200` — Successful Response
- `422` — Validation Error
- `429` — Too many concurrent unlock tasks. Wait for existing tasks to complete.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/advanced/unlock/task' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

### Raw Search

#### GET `/container/file_info`

**Fetch metadata for a raw entry**

Return the stored metadata for a raw entry located in the container tree.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `container_id` | integer | yes | _(minimum=1)_ |
| `entry_path` | string | yes | _(minLength=1)_ |

**Responses:**

- `200` — Entry metadata returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `container_id` | string | yes | Identifier of the container that owns the entry. |
| `entry_path` | string | yes | Entry path looked up in the index. |
| `entry_name` | string \| null | no | Base name of the entry, when known. |
| `size_bytes` | integer \| null | no | Size of the entry in bytes, if provided by the index. |
| `sha256_original` | string \| null | no | SHA-256 hash of the original raw file, when known. |
- `401` — Authentication required.
- `404` — Entry not found in the index.
- `422` — Validation Error
- `500` — Search error.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/container/file_info' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/container/subfolders`

**List immediate subfolders**

Aggregate the immediate subfolders located under the provided prefix.

Pagination is `page`/`page_size`. The server hides any cursor and handles deep paging internally.

Uniform response: { items, total, page, page_size } + has_more.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `container_id` | integer | yes | _(minimum=1)_ |
| `prefix` | string | no | folder prefix ('' for root) _(default=``)_ |
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=100000, default=`1000`)_ |

**Responses:**

- `200` — Subfolders aggregated successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<string> | yes | List of immediate subfolders found below the prefix. |
| `total` | integer | yes | Total count of distinct immediate subfolders estimated precisely. |
| `page` | integer | yes | Requested page index (1-based). |
| `page_size` | integer | yes | Page size used for the listing. |
| `has_more` | boolean | yes | True if there are more subfolders beyond this page. |
| `container_id` | string | yes | Identifier of the container that was browsed. |
| `prefix` | string | yes | Folder prefix used for the aggregation. |
- `401` — Authentication required.
- `422` — Validation Error
- `500` — Aggregation failed.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/container/subfolders' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/container/tree`

**Browse the container tree**

List entries located under a given prefix within a container.

Pagination uses `page`/`page_size`.

Uniform response: { items, total, page, page_size }.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `container_id` | integer | yes | _(minimum=1)_ |
| `prefix` | string | no | folder prefix, ex: 'db/users' ('' = root of container) _(default=``)_ |
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=1000, default=`200`)_ |

**Responses:**

- `200` — Entries listed successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (TreeEntry)> | yes | Entries located under the requested prefix. |
| `total` | integer | yes | Total entries under the prefix. |
| `page` | integer | yes | Requested page index (1-based). |
| `page_size` | integer | yes | Maximum number of entries returned in this response. |
| `container_id` | string | yes | Identifier of the container that was browsed. |
| `prefix` | string | yes | Folder prefix used for the listing. |
- `401` — Authentication required.
- `422` — Validation Error
- `500` — Search query failed.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/container/tree' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/container/tree/resolve_path`

**Resolve a full folder chain and prefetch its contents**

Resolve an entry path by hydrating every folder segment leading to it.

The resolver fetches the immediate subfolders and a page of files for each segment in the chain. It also can prefetch parts around a target sequence.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `container_id` | integer | yes | Identifier of the container that owns the entry. _(minimum=1.0)_ |
| `entry_path` | string | no | Entry path to resolve from the root of the container. _(default=``)_ |
| `options` | object (ResolvePathOptions) \| null | no | Fine-grained resolver options. |

**Responses:**

- `200` — Folder chain resolved successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `container_id` | string | yes | Identifier of the container that owns the resolved path. |
| `entry_path` | string | yes | Entry path requested by the caller. |
| `segments` | array<object (ResolvePathSegment)> | yes | Ordered list of segments composing the folder chain. |
| `target_entry` | object (TreeEntry) \| null | no | Entry metadata for the resolved file when found. |
| `target_parts` | object (PartsResponse) \| null | no | Prefetched parts for the resolved file when requested. |
- `401` — Authentication required.
- `404` — Folder or entry not found.
- `422` — Validation Error
- `500` — Search query failed.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/container/tree/resolve_path' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/raw/download`

**Generate a download URL for a raw file**

Return a short-lived pre-signed URL that allows downloading a raw file. Either provide the `sha256_original` hash directly or specify both `container_id` and `entry_path` so the hash can be resolved.

You can pass parameters either as query string or in the JSON body. If both are provided, the JSON body values take precedence.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `sha256_original` | string \| null | no |  |
| `container_id` | integer \| null | no |  |
| `entry_path` | string \| null | no |  |
| `expires_in` | integer | no | _(minimum=60, maximum=3600, default=`900`)_ |

**Request body** (optional, `application/json`):

Type: `object \| null`

**Responses:**

- `200` — Pre-signed URL generated successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string | yes | Pre-signed URL that can be used to download the file. |
| `expires_in` | integer | no | Number of seconds before the pre-signed URL expires. _(default=`900`)_ |
| `file_name` | string \| null | no | Suggested file name for the downloaded file. |
| `size_bytes` | integer \| null | no | Size of the file in bytes, when known. |
| `mime` | string \| null | no | MIME type of the file, when available. |
| `already_unlocked` | boolean | no | True when the user had an active unlock for the file prior to this request. _(default=`False`)_ |
| `downloaded_before` | boolean | no | Indicates whether the user has successfully downloaded this file in the past. _(default=`False`)_ |
- `400` — Missing or invalid identifier.
- `401` — Authentication required.
- `402` — Insufficient GB quota to unlock the file.
- `404` — File not found.
- `422` — Validation Error
- `500` — Storage or search error.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/raw/download' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### GET `/raw/download/preview`

**Preview unlock cost for a raw file**

Return the quota impact of unlocking a raw file. Either provide `sha256_original` or the tuple (`container_id`, `entry_path`).

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `sha256_original` | string \| null | no |  |
| `container_id` | integer \| null | no |  |
| `entry_path` | string \| null | no |  |

**Responses:**

- `200` — Preview computed successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `sha256_original` | string | yes | SHA-256 hash of the raw file that would be downloaded. |
| `raw_file_id` | integer | yes | Internal identifier of the raw file record. |
| `file_name` | string \| null | no | Proposed download file name, when available. |
| `original_file_name` | string \| null | no | Original file name when it differs from the stored name. |
| `source_size_bytes` | integer | yes | Original file size in bytes. |
| `already_unlocked` | boolean | yes | Whether the user has already unlocked the complete file. |
| `cost_bytes` | integer | yes | Number of bytes that will be debited if the user unlocks the file. |
| `user_gb_available_bytes` | integer | yes | Remaining quota in bytes for the current user. |
| `can_unlock` | boolean | yes | True when the user has enough quota to unlock the file. |
| `file_password` | string \| null | no | Password required to open the downloaded archive, when present. |
| `downloaded_before` | boolean | no | True if the user has downloaded this file previously, regardless of unlock expiration. _(default=`False`)_ |
- `400` — Missing or invalid identifier.
- `401` — Authentication required.
- `404` — File not found.
- `422` — Validation Error
- `500` — Search error.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/raw/download/preview' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/raw/files`

**List indexed raw files**

Return raw files that are done, non-duplicate and have indexed lines.

**Responses:**

- `200` — Successful Response

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/raw/files' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/search/raw`

**Search raw leak blocks**

Perform a full-text search across raw leak blocks. Provide the search payload in the JSON body.

**Request body**

- `q`: Optional search string (minimum 4 characters once quotes are removed).
- `container_id`: Optional container identifier.
- `exts` / `exts_not`: File extensions to include / exclude.
- `categories` / `categories_not`: Raw file categories to include / exclude.
- `file_name` / `file_name_not`: Wildcard on `entry_name` (max 50 items, min 2 chars each).
- `force_and`: Apply AND logic for `file_name` values (default OR).
- `ingested_at_min` / `ingested_at_max`: Datetime range filter (ISO 8601 with timezone).

If `q` is omitted, you must provide at least one filter among `container_id`, `exts`, `categories`, `file_name`.

**Query parameters**

- `page` starts at 1.
- `page_size` ranges from 1 to 100 (default 10).
- `cursor`: Cursor returned in the previous response to fetch the next page of results.

**Rate limit:** 5 requests per second per user.

**Response:** `{ items, total, page, page_size }`

---

**Limits:**

| Constraint | Value |
|------------|-------|
| Max file name filters | 50 |
| Min characters per file name | 2 |
| Max export results | 5 000 |
| Max export files | 25 |
| Download link retention | 7 days |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=100, default=`10`)_ |
| `cursor` | string \| null | no | Cursor from previous response to fetch the next page |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `q` | string \| null | no | Optional full text query to match within raw blocks. Quotes are ignored for the length check. When omitted or empty, you must provide at least one filter among container_id, exts, categories, file_name. |
| `container_id` | integer \| null | no | Restrict the search to a specific container id. |
| `exts` | array<string> \| null | no | List of file extensions to include (case-insensitive, without leading dot). |
| `exts_not` | array<string> \| null | no | List of file extensions to exclude (case-insensitive, without leading dot). |
| `categories` | array<string> \| null | no | Filter results by raw file category. Applied after the search query. |
| `categories_not` | array<string> \| null | no | Exclude these raw file categories. Applied after the search query. |
| `file_name` | array<string> \| null | no | Case-insensitive wildcards that must match the entry name (OR by default, AND if force_and=true). |
| `file_name_not` | array<string> \| null | no | Case-insensitive wildcards that must NOT match the entry name. |
| `force_and` | boolean \| null | no | When true, require all file_name values to match (AND instead of OR). |
| `ingested_at_min` | string \| null | no | Filter results ingested on or after this datetime (inclusive). |
| `ingested_at_max` | string \| null | no | Filter results ingested on or before this datetime (inclusive). |

**Responses:**

- `200` — Search executed successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (RawSearchItem)> | yes | List of matching raw blocks. |
| `total` | integer | yes | Total number of results (-1 if using cursor mode). |
| `page` | integer | yes | Requested page index (1-based). |
| `page_size` | integer | yes | Maximum number of items returned in this page. |
| `has_more` | boolean \| null | no | True if more results available (cursor mode only). |
| `next_cursor` | string \| null | no | Cursor for next page (cursor mode only). |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
- `400` — Invalid query or unsupported pagination.
- `401` — Authentication required.
- `422` — Validation Error
- `500` — Upstream search error.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/raw' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/search/raw/export`

**Queue a raw export job**

Queue an asynchronous export job for raw search results. Mode 'rows' exports a CSV of matching lines, mode 'parts' exports a text snapshot of matching parts.

**Important**: This export only includes results that have been previously unlocked via Mass Unlock. No points are consumed during export. Use `/search/raw/unlock/task` to unlock results first.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `export` | string | yes |  |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `q` | string \| null | no | Optional full text query to match within raw blocks. Quotes are ignored for the length check. When omitted or empty, you must provide at least one filter among container_id, exts, categories, file_name. |
| `container_id` | integer \| null | no | Restrict the search to a specific container id. |
| `exts` | array<string> \| null | no | List of file extensions to include (case-insensitive, without leading dot). |
| `exts_not` | array<string> \| null | no | List of file extensions to exclude (case-insensitive, without leading dot). |
| `categories` | array<string> \| null | no | Filter results by raw file category. Applied after the search query. |
| `categories_not` | array<string> \| null | no | Exclude these raw file categories. Applied after the search query. |
| `file_name` | array<string> \| null | no | Case-insensitive wildcards that must match the entry name (OR by default, AND if force_and=true). |
| `file_name_not` | array<string> \| null | no | Case-insensitive wildcards that must NOT match the entry name. |
| `force_and` | boolean \| null | no | When true, require all file_name values to match (AND instead of OR). |
| `ingested_at_min` | string \| null | no | Filter results ingested on or after this datetime (inclusive). |
| `ingested_at_max` | string \| null | no | Filter results ingested on or before this datetime (inclusive). |

**Responses:**

- `200` — Export job queued successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | yes | Export job status: 'queued', 'processing', 'completed', or 'failed'. |
| `message` | string | yes | Human-readable status message. |
| `export_id` | integer | yes | ID of the export job. Use this to check status or download the result. |
- `400` — Invalid query.
- `401` — Authentication required.
- `403` — Subscription does not allow raw exports.
- `422` — Validation Error
- `500` — Error while creating the export job.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/raw/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### GET `/search/raw/part`

**Retrieve a raw entry part**

Fetch the textual content for a specific raw entry block. If the block is not unlocked, the content is censored unless `auto_unlock=true` succeeds.

**Query parameters**
- `container_id`: Required container identifier.
- `entry_path`: Path of the entry inside the container.
- `seq`: Block sequence number (0-based).
- `trim_overlap`: When true, drop the overlapping prefix shared with the previous block.
- `overlap_chars`: Number of characters to trim when `trim_overlap=true` (default from configuration).
- `auto_unlock`: Attempt to unlock the block using points when necessary.

**Response**
Returns `PartResponse` describing the block and its (possibly censored) content.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `container_id` | integer | yes | _(minimum=1)_ |
| `entry_path` | string | yes | _(minLength=1)_ |
| `seq` | integer | yes | _(minimum=0)_ |
| `trim_overlap` | boolean | no | _(default=`False`)_ |
| `overlap_chars` | integer | no | _(minimum=0, maximum=8192, default=`256`)_ |
| `auto_unlock` | boolean | no | _(default=`False`)_ |

**Responses:**

- `200` — Block returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `container_id` | string | yes | Identifier of the container that owns the part. |
| `entry_path` | string | yes | Entry path that contains the part. |
| `seq` | integer | yes | Sequential part number requested. |
| `offset` | integer | yes | Byte offset of the part inside the entry. |
| `size_bytes` | integer \| null | no | Size of the returned block in bytes, if available. |
| `ingested_at` | string \| null | no | ISO timestamp of the ingestion time for the block. |
| `trim_overlap` | boolean | yes | True if the overlapping prefix was trimmed from the returned content. |
| `overlap_chars` | integer | yes | Number of characters trimmed from the start when `trim_overlap=true`. |
| `text` | string | yes | Text content of the block. May be censored. |
| `censored` | boolean | yes | True if the user has not unlocked the content and it was redacted. |
- `401` — Authentication required.
- `404` — Block not found or unavailable.
- `422` — Validation Error
- `500` — Search query failed.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/raw/part' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/search/raw/parts`

**List parts for a raw entry**

Return metadata about the blocks (parts) of a raw entry.

**Query parameters**
- `container_id`: Required container identifier.
- `entry_path`: Path of the entry inside the container.
- `page`/`page_size`: Pagination parameters.

**Response**
Uniform shape: { items, total, page, page_size } and optional `window`.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `container_id` | integer | yes | _(minimum=1)_ |
| `entry_path` | string | yes | _(minLength=1)_ |
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=1000, default=`100`)_ |

**Responses:**

- `200` — Parts listed successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (PartsItem)> | yes | Sequence of parts found for the requested slice. |
| `total` | integer | yes | Total number of parts available for the entry. |
| `page` | integer | yes | Requested page index (1-based). |
| `page_size` | integer | yes | Number of parts returned in this page. |
| `window` | object (PartsWindow) \| null | no | Span of part indexes covered by the response. |
| `container_id` | string | yes | Identifier of the container queried. |
| `entry_path` | string | yes | Entry path for which the parts are listed. |
- `401` — Authentication required.
- `422` — Validation Error
- `500` — Search query failed.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/raw/parts' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/search/raw/unlock/task`

**Queue an async mass unlock task for raw search**

Creates an asynchronous unlock **Task** for the given raw search filters. Returns a `task_id` you can poll with the task-status endpoint.

**Request body**
- `q`: Optional search string (minimum 4 characters if provided). Required if no other filter is provided.
- `container_id`: Optional container identifier.
- `exts`: Optional list of file extensions to keep.
- `exts_not`: Optional list of file extensions to exclude.
- `categories`: Optional list of raw file categories.
- `categories_not`: Optional list of raw file categories to exclude.
- `file_name`: Optional wildcard applied to `entry_name`.
- `file_name_not`: Optional wildcard that must NOT match `entry_name`.
- `ingested_at_min`: Optional datetime to filter results ingested on or after.
- `ingested_at_max`: Optional datetime to filter results ingested on or before.

**Query parameters**
- `max`: Optional cap of new unlocks. 0 or omitted = use all your points.

**Plan requirement**
Requires a paid plan with `raw_search` enabled.

**Concurrency limit**
- advanced / raw: max 2 concurrent tasks per user.
- email / domain: max 5 concurrent tasks per user.
- Returns 429 if limit exceeded.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `max` | integer \| null | no | 0 or omitted = use all your points |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `q` | string \| null | no | Optional full text query to match within raw blocks. Quotes are ignored for the length check. When omitted or empty, you must provide at least one filter among container_id, exts, categories, file_name. |
| `container_id` | integer \| null | no | Restrict the search to a specific container id. |
| `exts` | array<string> \| null | no | List of file extensions to include (case-insensitive, without leading dot). |
| `exts_not` | array<string> \| null | no | List of file extensions to exclude (case-insensitive, without leading dot). |
| `categories` | array<string> \| null | no | Filter results by raw file category. Applied after the search query. |
| `categories_not` | array<string> \| null | no | Exclude these raw file categories. Applied after the search query. |
| `file_name` | array<string> \| null | no | Case-insensitive wildcards that must match the entry name (OR by default, AND if force_and=true). |
| `file_name_not` | array<string> \| null | no | Case-insensitive wildcards that must NOT match the entry name. |
| `force_and` | boolean \| null | no | When true, require all file_name values to match (AND instead of OR). |
| `ingested_at_min` | string \| null | no | Filter results ingested on or after this datetime (inclusive). |
| `ingested_at_max` | string \| null | no | Filter results ingested on or before this datetime (inclusive). |

**Responses:**

- `200` — Task queued successfully.
- `400` — Invalid query or insufficient points.
- `403` — Raw search is not available on your plan.
- `422` — Validation Error
- `429` — Too many concurrent unlock tasks. Wait for existing tasks to complete.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/raw/unlock/task' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

### Dark Web Search

#### POST `/search/dark-web`

**Search dark web mentions**

Look for mentions of a company, domain, IP, or email across scraped dark web/forum posts.

**Simple mode**: Use `query` to search across title + content.

**Advanced mode**: Use specific fields (`title`, `content`, `author`, `source_url`) with AND/OR logic.

- Pagination: `page` starts at 1, `page_size` max 100.
- Fields: title, content, author, source, source_ref, target, published_at, ingested_at.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=100, default=`25`)_ |
| `sources` | string \| null | no | Comma-separated list of sources to filter by |
| `date_from` | string \| null | no | Filter posts published after this date |
| `date_to` | string \| null | no | Filter posts published before this date |
| `sort_by` | string | no | Sort field: ingested_at or published_at _(default=`ingested_at`)_ |
| `sort_order` | string | no | Sort order: asc or desc _(default=`desc`)_ |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string \| null | no | Global search term (simple mode). |
| `title` | string \| null | no | Search in title only (advanced mode). |
| `content` | string \| null | no | Search in content only (advanced mode). |
| `author` | string \| null | no | Exact author match (advanced mode). |
| `source_url` | string \| null | no | Source URL contains (advanced mode). |
| `logic` | string \| null | no | Logic for combining fields: AND or OR. _(default=`AND`)_ |

**Responses:**

- `200` — Search results.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (DarkWebItem)> | yes | List of dark web posts for the current page. |
| `total` | integer | yes | Total number of matching posts. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
- `400` — Invalid search parameters.
- `401` — Authentication required.
- `403` — Dark web search not included in your plan.
- `422` — Validation Error
- `429` — Rate limit exceeded.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/search/dark-web' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### GET `/search/dark-web/post/{post_id}`

**Get a single dark web post by ID**

Returns the full content of a dark web post without truncation.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `post_id` | string | yes | The post ID (document _id) |

**Responses:**

- `200` — Post content.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | string \| null | no | Unique post identifier. |
| `title` | string \| null | no | Post title. |
| `content` | string \| null | no | Post content. May be truncated for long posts. |
| `source` | string \| null | no | Source identifier (forum/market). |
| `source_name` | string \| null | no | Human-readable source name. |
| `target` | string \| null | no | Target entity mentioned in the post. |
| `source_ref` | string \| null | no | Original reference URL on the source. |
| `author` | string \| null | no | Post author. |
| `published_at` | string \| null | no | Original publication date. |
| `ingested_at` | string \| null | no | Date when the post was indexed by LeakRadar. |
| `truncated` | boolean | no | Whether the content was truncated due to length. _(default=`False`)_ |
| `censored` | boolean | no | Whether sensitive content was censored. _(default=`False`)_ |
- `401` — Authentication required.
- `404` — Post not found.
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/dark-web/post/<post_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/search/dark-web/sources`

**Get available dark web sources**

Returns a list of all scraped forum sources with their post counts.

**Responses:**

- `200` — List of sources.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `sources` | array<object (DarkWebSource)> | yes |  |
- `401` — Authentication required.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/dark-web/sources' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/search/dark-web/stats`

**Get dark web statistics**

Returns overall statistics about the dark web index.

**Responses:**

- `200` — Dark web statistics.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `total_posts` | integer | yes |  |
| `total_sources` | integer | yes |  |
| `latest_ingested_at` | string \| null | no |  |
| `oldest_published_at` | string \| null | no |  |
- `401` — Authentication required.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/search/dark-web/stats' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Unlock

#### POST `/unlock`

**Unlock selected leaks by ID**

Unlock leaks by their IDs for the authenticated account if they have enough points.

**Request body**
- `leak_ids` array of leak IDs to unlock (max 10,000). Duplicates are ignored while preserving order.

**Behavior**
- Requires an active paid subscription.
- 1 point per leak. Points are charged up front and partially refunded if some items were already unlocked during processing.
- Only found leaks are processed. If none are found, the request fails.
- The response reflects the final unlocked state from the account-level index.

**Visibility**
- `id` is included only for paid users.
- Credentials are included only for items with `unlocked=true`.

**Errors**
- 400 No leak IDs provided, too many leak IDs, insufficient points, or all selected data already unlocked.
- 401 Unauthorized.
- 403 Forbidden: subscription does not allow unlocking.
- 404 No valid leaks found.
- 422 Validation error.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `leak_ids` | array<string> | yes | List of leak document IDs to unlock. |
| `target_list_id` | integer \| null | no | Optional list id to assign to newly unlocked items. |

**Responses:**

- `200` — Selected leaks successfully unlocked.
- `400` — Bad request.
- `401` — Unauthorized.
- `403` — Forbidden. The user's subscription does not allow unlocking data.
- `404` — Not found. No valid leaks were found.
- `422` — Validation error.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/unlock' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

### Password Range

#### GET `/password-range`

**Search password hashes by prefix**

Search leaked password hashes (SHA-1) by prefix or full hash and get the distinct matches with their occurrence counts.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `prefix` | string | yes | SHA-1 prefix or full hash to search for. _(maxLength=40, minLength=5)_ |
| `limit` | integer | no | Maximum number of matching hashes to return. _(minimum=1, maximum=10000, default=`1000`)_ |
| `suffix_only` | boolean | no | If true, return only hash suffixes (after the first 5 chars) instead of full hashes. _(default=`False`)_ |

**Responses:**

- `200` — Matching hashes returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `prefix` | string | yes |  |
| `total` | integer | yes |  |
| `hashes` | array<object (PasswordRangeItem)> | yes |  |
- `400` — Prefix must be hexadecimal.
- `422` — Validation Error
- `429` — Rate limit exceeded.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/password-range' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Notifications

#### GET `/notification_methods`

**List notification methods**

Return all notification methods configured for the current account.

Method types
- `email`
- `slack` (Incoming Webhook URL)
- `telegram` (`value` = bot token, `second_value` = chat_id)
- `webhook` (generic HTTP webhook)
- `discord` (Discord Webhook URL)

Response
Array of objects with `id`, `type`, `value`, `second_value`, `timestamp`.

**Responses:**

- `200` — Notification methods listed successfully.
- `401` — Authentication required.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/notification_methods' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/notification_methods`

**Create notification method**

Create a new notification method for the current account.

Body fields
- `type` one of: `email`, `slack`, `telegram`, `webhook`, `discord`.
- `value` string. For Slack/Discord use the webhook URL. For Telegram use the bot token.
- `second_value` optional. Required for Telegram (`chat_id`).

Response
Object with `id`, `type`, `value`, `second_value`, `timestamp`.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string ('email', 'slack', 'telegram', 'webhook', 'discord') | yes | NNotificationMethodTypeEnum |
| `value` | string | yes | Primary value (e.g., webhook URL, bot token, or email address). _(maxLength=500)_ |
| `second_value` | string \| null | no | Secondary value when required by the method (e.g., Telegram chat_id). |
| `headers` | array<(recursive)> \| null | no | Optional custom HTTP headers for webhook methods (max 10). |

**Responses:**

- `200` — Method created successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | Notification method ID. |
| `type` | string ('email', 'slack', 'telegram', 'webhook', 'discord') | yes | NNotificationMethodTypeEnum |
| `value` | string | yes | Primary destination (email address, webhook URL, channel ID, etc.). |
| `second_value` | string \| null | no | Secondary value (e.g. Telegram chat ID). |
| `headers` | array<(recursive)> \| null | no | Custom HTTP headers for webhook methods. |
| `timestamp` | string | yes | Creation date of this notification method. |
- `401` — Authentication required.
- `403` — No active subscription.
- `422` — Validation error.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/notification_methods' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/notification_methods/test`

**Test notification method**

Validate that the provided parameters allow sending a test notification.

Slack: Incoming Webhook URL. Telegram: `value`=bot token, `second_value`=chat_id. Discord: Webhook URL. Webhook: sends a JSON payload to the provided URL.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string ('email', 'slack', 'telegram', 'webhook', 'discord') | yes | NNotificationMethodTypeEnum |
| `value` | string | yes | Primary value (e.g., webhook URL, bot token, or email address). _(maxLength=500)_ |
| `second_value` | string \| null | no | Secondary value when required by the method (e.g., Telegram chat_id). |
| `headers` | array<(recursive)> \| null | no | Optional custom HTTP headers for webhook methods (max 10). |

**Responses:**

- `200` — Test notification sent successfully.
- `400` — Invalid parameters or delivery failed.
- `401` — Authentication required.
- `422` — Validation Error
- `429` — Rate limit exceeded (30 tests per hour).

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/notification_methods/test' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### DELETE `/notification_methods/{method_id}`

**Delete notification method**

Delete a notification method owned by the current account.

Errors
- 404 Notification method not found.
- 409 Method in use by notifications.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `method_id` | integer | yes |  |

**Responses:**

- `200` — Method deleted successfully.
- `401` — Authentication required.
- `404` — Notification method not found.
- `409` — Method is still used by active notifications.
- `422` — Validation Error

**Example:**

```bash
curl -X DELETE 'https://api.leakradar.io/notification_methods/<method_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### PATCH `/notification_methods/{method_id}`

**Update notification method**

Update an existing notification method owned by the current account.

Errors
- 404 Notification method not found.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `method_id` | integer | yes |  |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | string ('email', 'slack', 'telegram', 'webhook', 'discord') | yes | NNotificationMethodTypeEnum |
| `value` | string | yes | Primary value (e.g., webhook URL, bot token, or email address). _(maxLength=500)_ |
| `second_value` | string \| null | no | Secondary value when required by the method (e.g., Telegram chat_id). |
| `headers` | array<(recursive)> \| null | no | Optional custom HTTP headers for webhook methods (max 10). |

**Responses:**

- `200` — Method updated successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | Notification method ID. |
| `type` | string ('email', 'slack', 'telegram', 'webhook', 'discord') | yes | NNotificationMethodTypeEnum |
| `value` | string | yes | Primary destination (email address, webhook URL, channel ID, etc.). |
| `second_value` | string \| null | no | Secondary value (e.g. Telegram chat ID). |
| `headers` | array<(recursive)> \| null | no | Custom HTTP headers for webhook methods. |
| `timestamp` | string | yes | Creation date of this notification method. |
- `401` — Authentication required.
- `404` — Notification method not found.
- `422` — Validation error.

**Example:**

```bash
curl -X PATCH 'https://api.leakradar.io/notification_methods/<method_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/notification_methods/{method_id}/test-with-data`

**Test notification method with fake data**

Send a test notification with realistic fake data.

Supports all notification types via the `type` query parameter:
- `leak` (default): Test with fake credential leaks
- `raw`: Test with fake raw search results
- `dark_web`: Test with fake dark web posts

Rate limit: 30 tests per hour.

Supported for all method types: email, slack, telegram, webhook, discord.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `method_id` | integer | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `notification_type` | string | no | _(default=`leak`)_ |

**Responses:**

- `200` — Test notification sent successfully.
- `400` — Delivery failed.
- `401` — Authentication required.
- `404` — Notification method not found.
- `422` — Validation Error
- `429` — Rate limit exceeded (30 tests per hour).

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/notification_methods/<method_id>/test-with-data' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/notifications`

**List notifications**

Return all notifications configured for the current account, including linked method info.

Response
Array of objects with fields like `id`, `method_id`, `type`, `second_type`, `value`, `filters`, `is_active`, `timestamp`, `method_type`, `method_value`, `auto_unlock`, `max_points`, `daily_spent`, `daily_reset_at`, `total_notifications`, `total_cost`.

**Responses:**

- `200` — Notifications listed successfully.
- `401` — Authentication required.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/notifications' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/notifications`

**Create notification**

Create a new notification bound to an existing notification method.

Supported types
- `email` requires `value` (email). `second_type` is not allowed.
- `domain` requires `value` (domain). `second_type` optional: one of domain leak types, default `ALL`.
- `advanced` requires `filters` (no `value`). Bulk is not allowed.

Bulk creation
- For `email` and `domain`, set `bulk=true` and provide newline-separated values in `value` to create several notifications at once.

Limit
- Max notifications = plan limit + extra monitoring assets purchased.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `method_id` | integer \| null | no | Notification method ID to use. |
| `type` | string ('email', 'domain', 'advanced', 'raw', 'dark_web') | yes | NNotificationTypeEnum |
| `value` | string \| null | no | Value to monitor (required for EMAIL/DOMAIN types). |
| `filters` | object \| null | no | Filters when type=ADVANCED or RAW. Parsed according to type. |
| `auto_unlock` | boolean \| null | no | If true, automatically unlock new matching leaks (consumes points). |
| `max_points` | integer \| null | no | Daily points cap for auto-unlock (if enabled). |
| `second_type` | string ('ALL', 'EMPLOYEES', 'THIRD_PARTIES', 'CUSTOMERS') \| null | no | For DOMAIN notifications: which leak category to monitor. |
| `bulk` | boolean \| null | no | Create multiple notifications at once (e.g., newline-separated values). _(default=`False`)_ |

**Responses:**

- `200` — Notification created successfully.
- `400` — Invalid parameters (missing value, invalid type, etc.).
- `401` — Authentication required.
- `403` — No active subscription or notification type not included in your plan.
- `409` — Duplicate notification already exists.
- `422` — Validation error.

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/notifications' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### DELETE `/notifications/bulk`

**Delete multiple notifications**

Delete multiple notifications owned by the current account.

Body
- `ids` array of notification IDs to delete.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `ids` | array<integer> | yes | Notification IDs to delete. |

**Responses:**

- `200` — Notifications deleted successfully.
- `400` — No notification IDs provided.
- `401` — Authentication required.
- `422` — Validation Error

**Example:**

```bash
curl -X DELETE 'https://api.leakradar.io/notifications/bulk' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### GET `/notifications/stats`

**Get notification stats**

Return monitored assets usage and limits (plan + extra assets) at account level.

**Responses:**

- `200` — Stats returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `total_notifications_asset` | integer | yes |  |
| `max_notification_asset` | integer \| null | yes |  |
| `plan_limit` | integer \| null | no |  |
| `extra_limit` | integer \| null | no |  |
| `total_limit` | integer \| null | no |  |
| `available` | integer \| null | no |  |
- `401` — Authentication required.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/notifications/stats' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### DELETE `/notifications/{notification_id}`

**Delete notification**

Delete a single notification owned by the current account.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `notification_id` | integer | yes |  |

**Responses:**

- `200` — Notification deleted successfully.
- `401` — Authentication required.
- `404` — Notification not found.
- `422` — Validation Error

**Example:**

```bash
curl -X DELETE 'https://api.leakradar.io/notifications/<notification_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### PATCH `/notifications/{notification_id}`

**Update notification**

Update an existing notification owned by the current account. All type-specific rules from creation apply.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `notification_id` | integer | yes |  |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `method_id` | integer \| null | no | Notification method ID to use. |
| `type` | string ('email', 'domain', 'advanced', 'raw', 'dark_web') | yes | NNotificationTypeEnum |
| `value` | string \| null | no | Value to monitor (required for EMAIL/DOMAIN types). |
| `filters` | object \| null | no | Filters when type=ADVANCED or RAW. Parsed according to type. |
| `auto_unlock` | boolean \| null | no | If true, automatically unlock new matching leaks (consumes points). |
| `max_points` | integer \| null | no | Daily points cap for auto-unlock (if enabled). |
| `second_type` | string ('ALL', 'EMPLOYEES', 'THIRD_PARTIES', 'CUSTOMERS') \| null | no | For DOMAIN notifications: which leak category to monitor. |
| `bulk` | boolean \| null | no | Create multiple notifications at once (e.g., newline-separated values). _(default=`False`)_ |

**Responses:**

- `200` — Notification updated successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | Notification ID. |
| `method_id` | integer | yes | ID of the notification method used for delivery. |
| `type` | string ('email', 'domain', 'advanced', 'raw', 'dark_web') | yes | NNotificationTypeEnum |
| `second_type` | string ('ALL', 'EMPLOYEES', 'THIRD_PARTIES', 'CUSTOMERS') \| null | no | Sub-type for domain notifications: employees, customers, or third_parties. |
| `value` | string \| null | no | Monitored value (email address, domain, search query, etc.). |
| `filters` | object \| null | no | Additional search filters applied to this notification. |
| `last_searched_at` | string \| null | no | Last time this notification was checked for new results. |
| `is_active` | boolean | yes | Whether this notification is currently active. |
| `timestamp` | string | yes | Creation date of this notification. |
| `method_type` | string ('email', 'slack', 'telegram', 'webhook', 'discord') \| null | no | Delivery type of the associated method. |
| `method_value` | string \| null | no | Destination of the associated method. |
| `auto_unlock` | boolean \| null | no | Whether new results are automatically unlocked. |
| `max_points` | integer \| null | no | Maximum points to spend per notification run for auto-unlock. |
| `daily_spent` | integer \| null | no | Points spent today by auto-unlock on this notification. |
| `daily_reset_at` | string \| null | no | Next daily reset time for the spent counter. |
| `total_notifications` | integer \| null | no | Total number of notification runs executed. |
| `total_cost` | integer \| null | no | Total points consumed by this notification across all runs. |
- `400` — Invalid parameters.
- `401` — Authentication required.
- `403` — Feature not included in your plan.
- `404` — Notification not found.
- `422` — Validation error.

**Example:**

```bash
curl -X PATCH 'https://api.leakradar.io/notifications/<notification_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### PATCH `/notifications/{notification_id}/active`

**Set notification active**

Enable or disable a notification by ID.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `notification_id` | integer | yes |  |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `is_active` | boolean | yes | Set the notification as active/inactive. |

**Responses:**

- `200` — Status updated successfully.
- `401` — Authentication required.
- `404` — Notification not found.
- `422` — Validation Error

**Example:**

```bash
curl -X PATCH 'https://api.leakradar.io/notifications/<notification_id>/active' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

### Notifications Runs

#### GET `/notification_runs`

**List notification runs**

Return paginated notification runs for the current user ordered by most recent first.

**Pagination**
- `page` starts at 1.
- `page_size` is 1 to 1000 (default 20).

**Response**
`PaginatedResponse[NotificationRunBase]` with `items`, `total`, `page`, `page_size`.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=1000, default=`20`)_ |

**Responses:**

- `200` — Notification runs listed successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (NotificationRunBase)> | yes | List of items for the current page. |
| `total` | integer | yes | Total number of matching items. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
- `401` — Authentication required.
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/notification_runs' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/notification_runs/{run_id}/export`

**Export leaks from a notification run to CSV/TXT/JSON**

Queue an export of leaks associated with a specific notification run. Optional `search` and `is_email` filters apply. The job runs asynchronously and the file will appear in the Exports section when ready.

**Limits**
- You can have at most 5 exports with status PENDING or IN_PROGRESS.

**Query parameters**
- `format` optional output format: `csv` (default), `txt`, or `json`.

**Response**
`ExportResponse` with `status`, `message`, and `export_id`.

**Errors**
- 404 Run not found.
- 400 Too many exports in progress.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `run_id` | integer | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `search` | string \| null | no |  |
| `is_email` | boolean \| null | no |  |
| `format` | string ('csv', 'txt', 'json') | no | Output format: csv (default), txt, or json. _(enum: 'csv', 'txt', 'json')_ |

**Responses:**

- `200` — Export queued successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | yes | Export job status: 'queued', 'processing', 'completed', or 'failed'. |
| `message` | string | yes | Human-readable status message. |
| `export_id` | integer | yes | ID of the export job. Use this to check status or download the result. |
- `400` — Too many exports in progress.
- `401` — Authentication required.
- `404` — Run not found.
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/notification_runs/<run_id>/export' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/notification_runs/{run_id}/items`

**List items for a notification run (unified endpoint)**

Return items associated with a specific notification run. Supports all notification types:\n\n- **Credential leaks** (EMAIL, DOMAIN, ADVANCED): Fetches leak details from ES\n- **RAW**: Returns file metadata stored in DB\n- **DARK_WEB**: Fetches post details from ES\n\n**Pagination**\n- `page` starts at 1.\n- `page_size` is 1 to 1000 (default 100).\n\n**Response**\n`PaginatedRunItemsResponse` with `items`, `total`, `total_unlocked`, `page`, `page_size`, `item_type`.\n\n**Errors**\n- 404 Run not found.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `run_id` | integer | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=1000, default=`100`)_ |

**Responses:**

- `200` — Items returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<any> | yes | List of run items (LeakRunItem, RawRunItem, or DarkWebRunItem). |
| `total` | integer | yes | Total number of items in this run. |
| `total_unlocked` | integer | yes | Number of already-unlocked items. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `item_type` | string \| null | no | Primary item type in this run: 'leak', 'raw', or 'dark_web'. |
- `401` — Authentication required.
- `404` — Run not found.
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/notification_runs/<run_id>/items' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/notification_runs/{run_id}/leaks/unlock`

**Unlock leaks from a notification run**

Unlock leaks that belong to a specific notification run. You can optionally filter by `search` and `is_email`, and cap the number of new unlocks with `max`. The effective limit is capped by your available points.

**Behavior**
- Only items not previously unlocked in this run are attempted.
- Points are charged only for newly unlocked items.
- The response contains the final unlocked state for the requested IDs.

**Errors**
- 400 No leaks for this run, all data already unlocked, or no data matches the search.
- 404 Run not found.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `run_id` | integer | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `max` | integer \| null | no |  |
| `search` | string \| null | no |  |
| `is_email` | boolean \| null | no |  |

**Responses:**

- `200` — Leaks unlocked successfully.
- `400` — No leaks, all already unlocked, or no data matches filter.
- `401` — Authentication required.
- `404` — Run not found.
- `422` — Validation Error

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/notification_runs/<run_id>/leaks/unlock' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### PUT `/notification_runs/{run_id}/status`

**Update the status of a notification run**

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `run_id` | integer | yes |  |

**Request body** (required, `application/json`):

Type: `object (Body)`

**Responses:**

- `200` — Successful Response
- `422` — Validation Error

**Example:**

```bash
curl -X PUT 'https://api.leakradar.io/notification_runs/<run_id>/status' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

### Unlocked Leaks

#### GET `/profile/unlocked`

**List your unlocked leaks**

Return a paginated list of unlocked leaks for the authenticated account.

Pagination
- `page` starts at 1.
- `page_size` is 1 to 1000 (default 100).

Filtering
- `search` optional free-text filter applied to URL or username.
- `is_email` optional boolean: `true` emails only, `false` usernames only, `null` both.
- `list_id` optional integer: filter leaks assigned to this list.
- `list_none` optional boolean: filter leaks with no list assignment.

Response semantics
- When no filter is provided at all (no `search`, no `is_email`, no list filter), `total` equals your global count of unlocked items.
- When any filter is provided (including only `is_email`), `total` equals the filtered count, while `total_unlocked` remains your global total.

Errors
- 404 Page out of range when the offset exceeds the corresponding total.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=1000, default=`100`)_ |
| `search` | string \| null | no |  |
| `is_email` | boolean \| null | no | true=email, false=username |
| `list_id` | integer \| null | no |  |
| `list_none` | boolean \| null | no | Only leaks without a list when true |
| `status` | string \| null | no | Filter by remediation status: new, in_progress, fixed, accepted_risk |

**Responses:**

- `200` — Unlocked leaks returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (UnlockedLeakDetails)> | yes | List of unlocked leak records for the current page. |
| `total` | integer | yes | Total number of matching records. |
| `total_unlocked` | integer | yes | Total number of unlocked records. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
- `401` — Authentication required.
- `404` — Page out of range.
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/profile/unlocked' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/profile/unlocked/advanced`

**List your unlocked leaks with advanced filters**

Return a paginated list of your unlocked leaks filtered by the same fields supported by `LeakSearchFilters`. Filters are passed as query parameters. Optional `search` can further narrow results.

Pagination
- `page` starts at 1.
- `page_size` is 1 to 1000 (default 100).

Filtering
- Any combination of `LeakSearchFilters` fields.
- `search` optional free-text filter applied to URL or username.
- `list_id` optional integer: filter leaks assigned to this list.
- `list_none` optional boolean: filter leaks with no list assignment.

Response semantics
- `total` and `total_unlocked` both equal the number of unlocked items matching the filters.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=1000, default=`100`)_ |
| `search` | string \| null | no |  |
| `list_id` | integer \| null | no |  |
| `list_none` | boolean \| null | no |  |
| `status` | string \| null | no | Filter by remediation status: new, in_progress, fixed, accepted_risk |
| `username` | array<string> \| null | no | Username must contain. |
| `username_not` | array<string> \| null | no | Exclude usernames containing these values. |
| `password` | array<string> \| null | no | Password must contain. |
| `password_not` | array<string> \| null | no | Exclude passwords containing these values. |
| `url` | array<string> \| null | no | URL must contain. |
| `url_not` | array<string> \| null | no | Exclude URLs containing these values. |
| `url_domain` | array<string> \| null | no | URL domain must contain. |
| `url_domain_not` | array<string> \| null | no | Exclude URL domains containing these values. |
| `url_host` | array<string> \| null | no | URL host must contain. |
| `url_host_not` | array<string> \| null | no | Exclude URL hosts containing these values. |
| `username_hash` | array<string> \| null | no | Username SHA-1 hash prefix (hex). |
| `password_hash` | array<string> \| null | no | Password SHA-1 hash prefix (hex). |
| `url_scheme` | array<string> \| null | no | URL scheme(s) to include (multi). |
| `url_scheme_not` | array<string> \| null | no | URL scheme(s) to exclude (multi). |
| `url_port` | array<integer> \| null | no | URL port(s) to include (multi). |
| `url_port_not` | array<integer> \| null | no | URL port(s) to exclude (multi). |
| `url_tld` | array<string> \| null | no | URL TLD(s) to include (multi). |
| `url_tld_not` | array<string> \| null | no | URL TLD(s) to exclude (multi). |
| `is_email` | boolean \| null | no | Identifier type filter: true=email only, false=username only, null=both. |
| `email_domain` | array<string> \| null | no | Email domain must contain. |
| `email_domain_not` | array<string> \| null | no | Exclude email domains containing these values. |
| `email_host` | array<string> \| null | no | Email host must contain. |
| `email_host_not` | array<string> \| null | no | Exclude email hosts containing these values. |
| `email_tld` | array<string> \| null | no | Email TLD(s) to include (multi). |
| `email_tld_not` | array<string> \| null | no | Email TLD(s) to exclude (multi). |
| `password_strength` | string ('too_weak', 'weak', 'medium', 'strong') \| null | no | Filter by password strength category. too_weak = score 0-2, weak = 3-4, medium = 5-7, strong = 8+. |
| `added_from` | string \| null | no | Only include leaks indexed on/after this UTC datetime. |
| `added_to` | string \| null | no | Only include leaks indexed on/before this UTC datetime. |
| `force_and` | boolean \| null | no | When true, values within each field are combined with AND instead of OR. |

**Responses:**

- `200` — Unlocked leaks returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (UnlockedLeakDetails)> | yes | List of unlocked leak records for the current page. |
| `total` | integer | yes | Total number of matching records. |
| `total_unlocked` | integer | yes | Total number of unlocked records. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
- `401` — Authentication required.
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/profile/unlocked/advanced' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/profile/unlocked/advanced/export`

**Export your unlocked leaks to CSV/TXT/JSON (advanced filters)**

Queue an export of your unlocked leaks filtered by the same fields supported by `LeakSearchFilters`. Provide advanced filters in the JSON request body. The job runs asynchronously and the file will appear in the Exports section when ready.

Request body
- JSON payload following the `LeakSearchFilters` schema.

Query parameters
- `unlocked_at_min` optional ISO 8601 timestamp with timezone to include items unlocked at or after this instant.
- `list_id` optional list id filter.
- `list_none` optional boolean to only include leaks without list.
- `format` optional output format: `csv` (default), `txt`, or `json`.

Limits
- At least one advanced filter is required.
- You can have at most 5 exports with status PENDING or IN_PROGRESS.

Response
`ExportResponse` with `status`, `message`, and `export_id`.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `list_id` | integer \| null | no | Filter by list id |
| `list_none` | boolean \| null | no | Only leaks without list _(default=`False`)_ |
| `format` | string ('csv', 'txt', 'json') | no | Output format: csv (default), txt, or json. _(enum: 'csv', 'txt', 'json')_ |
| `unlocked_at_min` | string \| null | no |  |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `username` | array<string> \| null | no | Username must contain. |
| `username_not` | array<string> \| null | no | Exclude usernames containing these values. |
| `password` | array<string> \| null | no | Password must contain. |
| `password_not` | array<string> \| null | no | Exclude passwords containing these values. |
| `url` | array<string> \| null | no | URL must contain. |
| `url_not` | array<string> \| null | no | Exclude URLs containing these values. |
| `url_domain` | array<string> \| null | no | URL domain must contain. |
| `url_domain_not` | array<string> \| null | no | Exclude URL domains containing these values. |
| `url_host` | array<string> \| null | no | URL host must contain. |
| `url_host_not` | array<string> \| null | no | Exclude URL hosts containing these values. |
| `username_hash` | array<string> \| null | no | Username SHA-1 hash prefix (hex). |
| `password_hash` | array<string> \| null | no | Password SHA-1 hash prefix (hex). |
| `url_scheme` | array<string> \| null | no | URL scheme(s) to include (multi). |
| `url_scheme_not` | array<string> \| null | no | URL scheme(s) to exclude (multi). |
| `url_port` | array<integer> \| null | no | URL port(s) to include (multi). |
| `url_port_not` | array<integer> \| null | no | URL port(s) to exclude (multi). |
| `url_tld` | array<string> \| null | no | URL TLD(s) to include (multi). |
| `url_tld_not` | array<string> \| null | no | URL TLD(s) to exclude (multi). |
| `is_email` | boolean \| null | no | Identifier type filter: true=email only, false=username only, null=both. |
| `email_domain` | array<string> \| null | no | Email domain must contain. |
| `email_domain_not` | array<string> \| null | no | Exclude email domains containing these values. |
| `email_host` | array<string> \| null | no | Email host must contain. |
| `email_host_not` | array<string> \| null | no | Exclude email hosts containing these values. |
| `email_tld` | array<string> \| null | no | Email TLD(s) to include (multi). |
| `email_tld_not` | array<string> \| null | no | Email TLD(s) to exclude (multi). |
| `password_strength` | string ('too_weak', 'weak', 'medium', 'strong') \| null | no | Filter by password strength category. too_weak = score 0-2, weak = 3-4, medium = 5-7, strong = 8+. |
| `added_from` | string \| null | no | Only include leaks indexed on/after this UTC datetime. |
| `added_to` | string \| null | no | Only include leaks indexed on/before this UTC datetime. |
| `force_and` | boolean \| null | no | When true, require all values within each field (AND within field). |

**Responses:**

- `200` — Successful Response

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | yes | Export job status: 'queued', 'processing', 'completed', or 'failed'. |
| `message` | string | yes | Human-readable status message. |
| `export_id` | integer | yes | ID of the export job. Use this to check status or download the result. |
- `422` — Validation Error

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/profile/unlocked/advanced/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/profile/unlocked/export`

**Export your unlocked leaks to CSV/TXT/JSON**

Queue an export of your unlocked leaks with optional filters. The job runs asynchronously and the file will appear in the Exports section when ready.

Body (JSON)
- `search` optional free-text filter applied to URL or username.
- `is_email` optional boolean: `true` emails only, `false` usernames only, `null` both.
- `list_id` optional list id filter.
- `list_none` optional boolean to only include leaks without list.
- `unlocked_at_min` optional ISO 8601 timestamp (with timezone) to include items unlocked at or after this instant.

Query parameters
- `format` optional output format: `csv` (default), `txt`, or `json`.

Limits
- You can have at most 5 exports with status PENDING or IN_PROGRESS.

Response
`ExportResponse` with `status`, `message`, and `export_id`.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `format` | string ('csv', 'txt', 'json') | no | Output format: csv (default), txt, or json. _(enum: 'csv', 'txt', 'json')_ |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `search` | string \| null | no |  |
| `is_email` | boolean \| null | no |  |
| `unlocked_at_min` | string \| null | no |  |
| `list_id` | integer \| null | no |  |
| `list_none` | boolean \| null | no | _(default=`False`)_ |

**Responses:**

- `200` — Successful Response

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | yes | Export job status: 'queued', 'processing', 'completed', or 'failed'. |
| `message` | string | yes | Human-readable status message. |
| `export_id` | integer | yes | ID of the export job. Use this to check status or download the result. |
- `422` — Validation Error

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/profile/unlocked/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

### Unlocked Leaks Lists

#### POST `/profile/unlocked/bulk-status`

**Bulk update the remediation status across many unlocked leaks**

Start a background task that updates the remediation status on all unlocked leaks matching the provided filters.

Valid statuses: `new`, `in_progress`, `fixed`, `accepted_risk`.

Filtering
- Supports the same filtering fields used by the advanced unlocked search API.
- Optional helpers: `search`, `is_email`, `list_id_filter`, `list_none`, `status_filter`.

Response
- Returns a `task_id` that you can poll with `/profile/unlocked/list-tasks/{task_id}`.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `target_status` | string | yes | Target status: new, in_progress, fixed, accepted_risk |
| `search` | string \| null | no |  |
| `is_email` | boolean \| null | no |  |
| `list_id_filter` | integer \| null | no |  |
| `list_none` | boolean \| null | no |  |
| `status_filter` | string \| null | no |  |
| `filters` | object (LeakSearchFilters) \| null | no |  |

**Responses:**

- `200` — Successful Response

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `task_id` | string | yes |  |
| `running` | boolean | yes |  |
| `completed` | boolean | yes |  |
| `total` | integer \| null | no |  |
| `updated` | integer \| null | no |  |
| `version_conflicts` | integer \| null | no |  |
- `422` — Validation Error

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/profile/unlocked/bulk-status' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### GET `/profile/unlocked/list-tasks/{task_id}`

**Get unlocked lists background task status**

Return the status of a background task started by unlocked lists operations.

This endpoint is only for tasks created by:
- `POST /profile/unlocked/lists/bulk-assign` (bulk assign/unassign list)

Usage
- Use the exact `task_id` returned by one of these endpoints.

Important
- Do **not** use this endpoint for unlock tasks created by `/search/.../unlock/task`. For unlock tasks, poll `/tasks/{task_id}` instead.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `task_id` | string | yes | _(minLength=1)_ |

**Responses:**

- `200` — Successful Response

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `task_id` | string | yes |  |
| `running` | boolean | yes |  |
| `completed` | boolean | yes |  |
| `total` | integer \| null | no |  |
| `updated` | integer \| null | no |  |
| `version_conflicts` | integer \| null | no |  |
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/profile/unlocked/list-tasks/<task_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/profile/unlocked/lists`

**List your Unlocked Lists**

Return all your Unlocked Lists in ascending creation order.

Parameters
- `with_counts` when true, each list includes `items_count`, the number of unlocked leaks currently assigned to that list. When false, `items_count` is returned as 0 to avoid extra computation.

Errors
- Standard 401 when not authenticated.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `with_counts` | boolean | no | When true, include `items_count` per list. _(default=`True`)_ |

**Responses:**

- `200` — Successful Response
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/profile/unlocked/lists' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/profile/unlocked/lists`

**Create an Unlocked List**

Create a new list to organize your unlocked leaks.

Rules
- Maximum number of lists is determined by your current plan.
- List names must be unique per account, case-insensitive.

Response
- Returns the created list. `items_count` is 0 at creation time.

Errors
- 400 when the user already has the maximum number of lists.
- 400 when the user has no plan.
- 409 when a list with the same name already exists.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | _(maxLength=80, minLength=1)_ |
| `color` | string \| null | no |  |

**Responses:**

- `200` — Successful Response

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes |  |
| `name` | string | yes |  |
| `color` | string \| null | yes |  |
| `created_at` | string \| null | yes |  |
| `updated_at` | string \| null | yes |  |
| `items_count` | integer \| null | no |  |
- `422` — Validation Error

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/profile/unlocked/lists' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/profile/unlocked/lists/bulk-assign`

**Bulk assign or unassign a list across many unlocked leaks**

Start a background task that assigns a target list to all unlocked leaks matching the provided filters. Use a null `target_list_id` to remove the assignment for matches.

Filtering
- Supports the same filtering fields used by the advanced unlocked search API.
- Optional helpers: `search`, `is_email`, `list_id_filter`, `list_none`.

Validation
- `target_list_id` must be a positive integer when provided. Use null to unassign.

Response
- Returns a `task_id` that you can poll with `/profile/unlocked/list-tasks/{task_id}`.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `target_list_id` | integer \| null | yes |  |
| `search` | string \| null | no |  |
| `is_email` | boolean \| null | no |  |
| `list_id_filter` | integer \| null | no |  |
| `list_none` | boolean \| null | no |  |
| `filters` | object (LeakSearchFilters) \| null | no |  |

**Responses:**

- `200` — Successful Response

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `task_id` | string | yes |  |
| `running` | boolean | yes |  |
| `completed` | boolean | yes |  |
| `total` | integer \| null | no |  |
| `updated` | integer \| null | no |  |
| `version_conflicts` | integer \| null | no |  |
- `422` — Validation Error

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/profile/unlocked/lists/bulk-assign' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### DELETE `/profile/unlocked/lists/{list_id}`

**Delete an Unlocked List**

Delete the list and start a background cleanup of related leak assignments.

Behavior
- The list is removed immediately.
- Any unlocked leak that referenced this list will be cleaned up by a background task.
- The response includes a `task_id` that you can poll at `/profile/unlocked/list-tasks/{task_id}`.

Errors
- 404 when the list does not exist or is not owned by the account.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `list_id` | integer | yes | ID of the list to delete _(minimum=1)_ |

**Responses:**

- `200` — Successful Response

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `task_id` | string | yes |  |
| `running` | boolean | yes |  |
| `completed` | boolean | yes |  |
| `total` | integer \| null | no |  |
| `updated` | integer \| null | no |  |
| `version_conflicts` | integer \| null | no |  |
- `422` — Validation Error

**Example:**

```bash
curl -X DELETE 'https://api.leakradar.io/profile/unlocked/lists/<list_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### PATCH `/profile/unlocked/lists/{list_id}`

**Update an Unlocked List**

Update list metadata. Only provided fields are updated.

Updatable fields
- `name` must be unique per account, case-insensitive.
- `color` optional UI attribute.

Errors
- 404 when the list does not exist or is not owned by the account.
- 409 when the new name collides with another list.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `list_id` | integer | yes | ID of the list to update _(minimum=1)_ |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string \| null | no |  |
| `color` | string \| null | no |  |

**Responses:**

- `200` — Successful Response

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes |  |
| `name` | string | yes |  |
| `color` | string \| null | yes |  |
| `created_at` | string \| null | yes |  |
| `updated_at` | string \| null | yes |  |
| `items_count` | integer \| null | no |  |
- `422` — Validation Error

**Example:**

```bash
curl -X PATCH 'https://api.leakradar.io/profile/unlocked/lists/<list_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/profile/unlocked/lists/{list_id}/clear`

**Clear list assignment from leaks while keeping the list**

Remove the list assignment from all unlocked leaks that currently reference this list. The list itself is kept. The operation runs in the background and returns a `task_id`.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `list_id` | integer | yes | ID of the list whose assignments will be cleared _(minimum=1)_ |

**Responses:**

- `200` — Successful Response

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `task_id` | string | yes |  |
| `running` | boolean | yes |  |
| `completed` | boolean | yes |  |
| `total` | integer \| null | no |  |
| `updated` | integer \| null | no |  |
| `version_conflicts` | integer \| null | no |  |
- `422` — Validation Error

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/profile/unlocked/lists/<list_id>/clear' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### DELETE `/profile/unlocked/{leak_id}/comment`

**Delete the comment of one unlocked leak**

Delete the user comment attached to a specific unlocked leak.

Errors
- 404 when the leak does not exist for the account.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `leak_id` | string | yes | Unlocked leak identifier _(maxLength=64, minLength=1)_ |

**Responses:**

- `200` — Successful Response
- `422` — Validation Error

**Example:**

```bash
curl -X DELETE 'https://api.leakradar.io/profile/unlocked/<leak_id>/comment' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### PUT `/profile/unlocked/{leak_id}/comment`

**Create or update a comment for one unlocked leak**

Create or update a user comment on a single unlocked leak. Empty or whitespace-only comments are treated as delete.

Limits
- Max 500 characters.

Errors
- 404 when the leak does not exist for the account.
- 422 when the comment exceeds 500 characters.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `leak_id` | string | yes | Unlocked leak identifier _(maxLength=64, minLength=1)_ |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `comment` | string | yes | _(maxLength=500, minLength=0)_ |

**Responses:**

- `200` — Successful Response
- `422` — Validation Error

**Example:**

```bash
curl -X PUT 'https://api.leakradar.io/profile/unlocked/<leak_id>/comment' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### PUT `/profile/unlocked/{leak_id}/list`

**Assign or unassign a list for one unlocked leak**

Assign a specific list to a single unlocked leak, or unassign it.

Behavior
- Provide `list_id` to assign. Use `null` to remove the assignment.

Errors
- 404 when the leak does not exist for the account or the list is not found.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `leak_id` | string | yes | Unlocked leak identifier _(maxLength=64, minLength=1)_ |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `list_id` | integer \| null | no | null to remove list |

**Responses:**

- `200` — Successful Response
- `422` — Validation Error

**Example:**

```bash
curl -X PUT 'https://api.leakradar.io/profile/unlocked/<leak_id>/list' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### PUT `/profile/unlocked/{leak_id}/status`

**Update the remediation status of one unlocked leak**

Set the remediation status of a single unlocked leak.

Valid statuses: `new`, `in_progress`, `fixed`, `accepted_risk`.

Errors
- 404 when the leak does not exist for the account.
- 422 when the status value is invalid.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `leak_id` | string | yes | Unlocked leak identifier _(maxLength=64, minLength=1)_ |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | string | yes | Target status: new, in_progress, fixed, accepted_risk |

**Responses:**

- `200` — Successful Response
- `422` — Validation Error

**Example:**

```bash
curl -X PUT 'https://api.leakradar.io/profile/unlocked/<leak_id>/status' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

### Exports

#### GET `/exports`

**List export jobs**

Return the current account's export jobs ordered by most recent first. Supports pagination.

**Pagination**
- `page` starts at 1.
- `page_size` default and maximum are defined by server settings (default 20, max 100 if not configured).

**Response**
`PaginatedResponse[ExportBase]` with `items`, `total`, `page`, `page_size`.

**Errors**
- 404 Page out of range when the offset exceeds the total.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | Page number starting at 1 _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | Number of items per page _(minimum=1, maximum=100, default=`20`)_ |

**Responses:**

- `200` — Exports retrieved successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (ExportBase)> | yes | List of items for the current page. |
| `total` | integer | yes | Total number of matching items. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
- `401` — Unauthorized. The user is not authenticated.
- `404` — Page out of range.
- `422` — Validation error: invalid request parameters.
- `429` — Too many requests: rate limit exceeded.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/exports' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Profile

#### GET `/profile`

**Get user profile**

Return the profile of the authenticated user.

**Responses:**

- `200` — User profile retrieved successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes |  |
| `first_name` | string | yes |  |
| `last_name` | string | yes |  |
| `organization` | string \| null | yes |  |
| `email` | string | yes |  |
| `address` | string \| null | yes |  |
| `address_line2` | string \| null | yes |  |
| `city` | string \| null | yes |  |
| `region` | string \| null | yes |  |
| `zip_code` | string \| null | yes |  |
| `country` | string \| null | yes |  |
| `phone` | string \| null | yes |  |
| `tva_number` | string \| null | yes |  |
| `admin` | boolean | yes |  |
| `is_uploader` | boolean \| null | no | _(default=`False`)_ |
| `timestamp` | string | yes |  |
| `subscription_start_date` | string \| null | yes |  |
| `subscription_end_date` | string \| null | yes |  |
| `subscription_active` | boolean \| null | yes |  |
| `subscription_points` | integer \| null | yes |  |
| `subscription_gb` | integer \| null | no |  |
| `extra_points` | integer \| null | no |  |
| `extra_gb` | integer \| null | no |  |
| `last_gb_reset` | string \| null | no |  |
| `stripe_subscription_id` | string \| null | yes |  |
| `plan_id` | integer \| null | yes |  |
| `invoices` | array<object (InvoiceBase)> | yes |  |
| `plan` | object (PlanBase) \| null | yes |  |
| `parent_user_id` | integer \| null | no |  |
| `team_role` | string \| null | no |  |
| `email_confirmed` | boolean | yes |  |
| `last_login` | string \| null | yes |  |
| `last_login_ip` | string \| null | yes |  |
| `registration_ip` | string \| null | yes |  |
| `campaign_code` | string \| null | yes |  |
| `register_by` | string \| null | yes |  |
| `banned` | boolean | yes |  |
| `api` | string \| null | yes |  |
| `twofa_enabled` | boolean | yes |  |
| `twofa_pin_enabled` | boolean | no | _(default=`False`)_ |
| `twofa_totp_enabled` | boolean | no | _(default=`False`)_ |
| `has_password` | boolean | no | _(default=`True`)_ |
| `referral_code` | string \| null | no |  |
| `referral_percentage` | number \| null | no |  |
| `referral_percentage_renewal` | number \| null | no |  |
| `last_points_reset` | string \| null | no |  |
- `401` — Unauthorized. Invalid or missing authentication token.
- `404` — User not found.
- `422` — Validation error: invalid request parameters.
- `429` — Too many requests: rate limit exceeded.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/profile' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### PATCH `/profile`

**Update user profile**

Update the authenticated user's profile with fields defined by `ProfileUpdate`. If `email` is changed, uniqueness is enforced.

**Behavior**
- Only whitelisted fields from `ProfileUpdate` are applied.
- If the new email already exists, the request fails with 409.

**Response**
Returns the updated profile.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `first_name` | string \| null | no |  |
| `last_name` | string \| null | no |  |
| `organization` | string \| null | no |  |
| `address` | string \| null | no |  |
| `address_line2` | string \| null | no |  |
| `phone` | string \| null | no |  |
| `zip_code` | string \| null | no |  |
| `region` | string \| null | no |  |
| `city` | string \| null | no |  |
| `country` | string \| null | no |  |
| `tva_number` | string \| null | no |  |

**Responses:**

- `200` — User profile updated successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes |  |
| `first_name` | string | yes |  |
| `last_name` | string | yes |  |
| `organization` | string \| null | yes |  |
| `email` | string | yes |  |
| `address` | string \| null | yes |  |
| `address_line2` | string \| null | yes |  |
| `city` | string \| null | yes |  |
| `region` | string \| null | yes |  |
| `zip_code` | string \| null | yes |  |
| `country` | string \| null | yes |  |
| `phone` | string \| null | yes |  |
| `tva_number` | string \| null | yes |  |
| `admin` | boolean | yes |  |
| `is_uploader` | boolean \| null | no | _(default=`False`)_ |
| `timestamp` | string | yes |  |
| `subscription_start_date` | string \| null | yes |  |
| `subscription_end_date` | string \| null | yes |  |
| `subscription_active` | boolean \| null | yes |  |
| `subscription_points` | integer \| null | yes |  |
| `subscription_gb` | integer \| null | no |  |
| `extra_points` | integer \| null | no |  |
| `extra_gb` | integer \| null | no |  |
| `last_gb_reset` | string \| null | no |  |
| `stripe_subscription_id` | string \| null | yes |  |
| `plan_id` | integer \| null | yes |  |
| `invoices` | array<object (InvoiceBase)> | yes |  |
| `plan` | object (PlanBase) \| null | yes |  |
| `parent_user_id` | integer \| null | no |  |
| `team_role` | string \| null | no |  |
| `email_confirmed` | boolean | yes |  |
| `last_login` | string \| null | yes |  |
| `last_login_ip` | string \| null | yes |  |
| `registration_ip` | string \| null | yes |  |
| `campaign_code` | string \| null | yes |  |
| `register_by` | string \| null | yes |  |
| `banned` | boolean | yes |  |
| `api` | string \| null | yes |  |
| `twofa_enabled` | boolean | yes |  |
| `twofa_pin_enabled` | boolean | no | _(default=`False`)_ |
| `twofa_totp_enabled` | boolean | no | _(default=`False`)_ |
| `has_password` | boolean | no | _(default=`True`)_ |
| `referral_code` | string \| null | no |  |
| `referral_percentage` | number \| null | no |  |
| `referral_percentage_renewal` | number \| null | no |  |
| `last_points_reset` | string \| null | no |  |
- `401` — Unauthorized. Invalid or missing authentication token.
- `404` — User not found.
- `409` — Email already in use.
- `422` — Validation error: invalid request parameters.
- `429` — Too many requests: rate limit exceeded.

**Example:**

```bash
curl -X PATCH 'https://api.leakradar.io/profile' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### GET `/profile/activities/balance-logs`

**List balance history for the current account**

Return a paginated list of balance log entries (points and GB changes) for the authenticated user's account.

Team members see the owner's aggregated logs.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=100, default=`20`)_ |
| `order_by` | string | no | _(default=`created_at`)_ |
| `order_dir` | string | no | _(default=`desc`)_ |

**Responses:**

- `200` — Balance logs returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (BalanceLogItem)> | yes | List of items for the current page. |
| `total` | integer | yes | Total number of matching items. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
- `401` — Authentication required.
- `404` — Page out of range.
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/profile/activities/balance-logs' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/profile/activities/tasks`

**List task history for the current account**

Return a paginated list of background tasks (exports, bulk unlocks, etc.) for the authenticated user's account.

Team members see the owner's aggregated tasks.

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=100, default=`20`)_ |
| `order_by` | string | no | _(default=`id`)_ |
| `order_dir` | string | no | _(default=`desc`)_ |

**Responses:**

- `200` — Tasks returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (UserTaskItem)> | yes | List of items for the current page. |
| `total` | integer | yes | Total number of matching items. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
- `401` — Authentication required.
- `404` — Page out of range.
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/profile/activities/tasks' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### GET `/profile/preferences`

**Get user preferences**

Return the authenticated user's preferences. Defaults are used when no preferences have been saved yet.

**Responses:**

- `200` — Preferences returned.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `hide_passwords` | boolean | no | When true, plaintext passwords are redacted from search results, the unlocked-leaks list, and exports on email/domain/advanced scopes. _(default=`False`)_ |
- `401` — Unauthorized.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/profile/preferences' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### PATCH `/profile/preferences`

**Update user preferences**

Partial update of the authenticated user's preferences. Only fields provided in the body are modified.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `hide_passwords` | boolean \| null | no | Toggle password redaction. Omit to leave unchanged. |

**Responses:**

- `200` — Preferences updated.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `hide_passwords` | boolean | no | When true, plaintext passwords are redacted from search results, the unlocked-leaks list, and exports on email/domain/advanced scopes. _(default=`False`)_ |
- `401` — Unauthorized.
- `422` — Validation error.

**Example:**

```bash
curl -X PATCH 'https://api.leakradar.io/profile/preferences' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

### Profile Downloads

#### GET `/profile/raw/downloads`

**List your raw file downloads**

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `page` | integer | no | _(minimum=1, default=`1`)_ |
| `page_size` | integer | no | _(minimum=1, maximum=100, default=`20`)_ |

**Responses:**

- `200` — Successful Response

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array<object (DownloadLogItem)> | yes | List of items for the current page. |
| `total` | integer | yes | Total number of matching items. |
| `page` | integer | yes | Current page number. |
| `page_size` | integer | yes | Number of items per page. |
| `blacklisted_value` | string \| null | no | If a filter value matched a blacklist entry, this field contains the matched value. |
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/profile/raw/downloads' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/profile/raw/downloads/{download_id}/file`

**Download a raw file through the platform**

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `download_id` | integer | yes |  |

**Query parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `token` | string \| null | no |  |

**Responses:**

- `307` — Temporary redirect to a presigned URL for the raw file.
- `401` — Authentication is required.
- `404` — Download not found or raw file unavailable.
- `410` — Download expired or previous attempt failed. Unlock the file again to regenerate access.
- `422` — Validation Error

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/profile/raw/downloads/<download_id>/file' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Team

#### GET `/profile/team`

**Get team overview**

Returns the full team structure: owner, active members, pending invitations, plan summary, and member quota.

**Responses:**

- `200` — Team overview

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `owner` | object (TeamMemberResponse) | yes | TeamMemberResponse |
| `members` | array<object (TeamMemberResponse)> | yes | Active team members. |
| `invitations` | array<object (TeamInvitationResponse)> | yes | Pending and past invitations. |
| `plan` | object (TeamPlanSummary) | yes | TeamPlanSummary |
| `quota` | object (TeamQuotaResponse) | yes | TeamQuotaResponse |
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/profile/team' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/profile/team/invitations`

**Create a team invitation**

Invite a user to join your team by email. An invitation email is sent automatically. Returns 409 if the user already belongs to a team or an invitation is already pending.

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `email` | string | yes |  |
| `name` | string \| null | no |  |
| `role` | string ('member', 'admin') | no | _(default=`member`)_ |

**Responses:**

- `200` — Invitation created

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | Invitation ID. |
| `invited_email` | string | yes | Email address of the invited user. |
| `invited_name` | string \| null | no | Name of the invited user. |
| `role` | string | yes | Assigned role: 'member' or 'admin'. |
| `status` | string | yes | Invitation status: 'pending', 'accepted', 'revoked', or 'expired'. |
| `expires_at` | string | yes | Expiration date of the invitation. |
| `created_at` | string | yes | Creation date of the invitation. |
| `invited_by` | object (TeamInvitationActor) \| null | no | User who sent the invitation. |
| `accepted_user_id` | integer \| null | no | ID of the user who accepted the invitation. |
| `token` | string \| null | no | Invitation token (only returned on creation). |
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Unprocessable Content

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/profile/team/invitations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

#### POST `/profile/team/invitations/{invitation_id}/resend`

**Resend a team invitation**

Resend the invitation email for a pending invitation. Generates a new token and extends the expiration. Rate limited to 1 resend per invitation per 60 seconds.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `invitation_id` | integer | yes |  |

**Responses:**

- `200` — Invitation resent

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | Invitation ID. |
| `invited_email` | string | yes | Email address of the invited user. |
| `invited_name` | string \| null | no | Name of the invited user. |
| `role` | string | yes | Assigned role: 'member' or 'admin'. |
| `status` | string | yes | Invitation status: 'pending', 'accepted', 'revoked', or 'expired'. |
| `expires_at` | string | yes | Expiration date of the invitation. |
| `created_at` | string | yes | Creation date of the invitation. |
| `invited_by` | object (TeamInvitationActor) \| null | no | User who sent the invitation. |
| `accepted_user_id` | integer \| null | no | ID of the user who accepted the invitation. |
| `token` | string \| null | no | Invitation token (only returned on creation). |
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/profile/team/invitations/<invitation_id>/resend' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/profile/team/invitations/{invitation_id}/revoke`

**Revoke a team invitation**

Revoke a pending invitation. The invited user will no longer be able to accept it.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `invitation_id` | integer | yes |  |

**Responses:**

- `200` — Invitation revoked

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | Invitation ID. |
| `invited_email` | string | yes | Email address of the invited user. |
| `invited_name` | string \| null | no | Name of the invited user. |
| `role` | string | yes | Assigned role: 'member' or 'admin'. |
| `status` | string | yes | Invitation status: 'pending', 'accepted', 'revoked', or 'expired'. |
| `expires_at` | string | yes | Expiration date of the invitation. |
| `created_at` | string | yes | Creation date of the invitation. |
| `invited_by` | object (TeamInvitationActor) \| null | no | User who sent the invitation. |
| `accepted_user_id` | integer \| null | no | ID of the user who accepted the invitation. |
| `token` | string \| null | no | Invitation token (only returned on creation). |
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/profile/team/invitations/<invitation_id>/revoke' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### POST `/profile/team/leave`

**Leave the team**

Voluntarily leave the team you are a member of. Team owners cannot use this endpoint.

**Responses:**

- `200` — Successfully left the team
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found

**Example:**

```bash
curl -X POST 'https://api.leakradar.io/profile/team/leave' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### DELETE `/profile/team/members/{member_id}`

**Remove a team member**

Remove a member from the team. The member's account is detached but not deleted.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `member_id` | integer | yes |  |

**Responses:**

- `200` — Member removed

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | User ID of the team member. |
| `email` | string | yes | Email address of the team member. |
| `first_name` | string \| null | no | First name. |
| `last_name` | string \| null | no | Last name. |
| `organization` | string \| null | no | Organization name. |
| `team_role` | string \| null | no | Role within the team: 'member' or 'admin'. |
| `joined_at` | string | yes | Date when the member joined the team. |
| `last_login` | string \| null | no | Last login date. |
| `is_owner` | boolean | no | Whether this member is the team owner. _(default=`False`)_ |
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error

**Example:**

```bash
curl -X DELETE 'https://api.leakradar.io/profile/team/members/<member_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

#### PATCH `/profile/team/members/{member_id}`

**Update a team member's role**

Change a team member's role to 'member' or 'admin'.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `member_id` | integer | yes |  |

**Request body** (required, `application/json`):

| Field | Type | Required | Description |
|---|---|---|---|
| `team_role` | string ('member', 'admin') | yes |  |

**Responses:**

- `200` — Member updated

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `id` | integer | yes | User ID of the team member. |
| `email` | string | yes | Email address of the team member. |
| `first_name` | string \| null | no | First name. |
| `last_name` | string \| null | no | Last name. |
| `organization` | string \| null | no | Organization name. |
| `team_role` | string \| null | no | Role within the team: 'member' or 'admin'. |
| `joined_at` | string | yes | Date when the member joined the team. |
| `last_login` | string \| null | no | Last login date. |
| `is_owner` | boolean | no | Whether this member is the team owner. _(default=`False`)_ |
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Unprocessable Content

**Example:**

```bash
curl -X PATCH 'https://api.leakradar.io/profile/team/members/<member_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

### Tasks

#### GET `/tasks/{task_id}`

**Get background task status**

Return the live status for a background task started by list operations Use the `task_id` returned by the create endpoint.

**Usage**
Poll this endpoint every 1s until `completed=true`. If the task is unknown or expired, the service returns `completed=true` with no totals, which can be treated as finished.

**Path parameters:**

| Name | Type | Required | Description |
|---|---|---|---|
| `task_id` | string | yes |  |

**Responses:**

- `200` — Task status returned successfully.

Response shape:

| Field | Type | Required | Description |
|---|---|---|---|
| `task_id` | string | yes |  |
| `running` | boolean | yes |  |
| `completed` | boolean | yes |  |
| `total` | integer \| null | no |  |
| `updated` | integer \| null | no |  |
| `version_conflicts` | integer \| null | no |  |
- `400` — Invalid task_id format.
- `401` — Authentication required.
- `404` — Task not found.
- `422` — Validation Error

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/tasks/<task_id>' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Stats

#### GET `/stats`

**Get statistics**

Return the cached service statistics snapshot. If stats are not available in cache, the endpoint returns `{ "message": "Stats not available" }`.

**Responses:**

- `200` — Statistics returned successfully.

**Example:**

```bash
curl -X GET 'https://api.leakradar.io/stats' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

## Resources

- Python wrapper: https://github.com/LeakRadar/leakradar-wrapper
- GitHub organization: https://github.com/LeakRadar
- Status page: https://status.leakradar.io
- Blog: https://leakradar.io/en/blog
- Public domain reports: https://leakradar.io/en/domain-reports
- Comparisons with alternatives: https://leakradar.io/en/alternatives
- Sister product (subdomain discovery): https://subdomainradar.io
- Contact: contact@leakradar.io

## Legal

- Terms of service: https://leakradar.io/en/terms
- Privacy policy: https://leakradar.io/en/privacy
- Operator: Radar Forge SASU, France