### Search Progress Message Example

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

This example demonstrates a `search.progress` message, which is useful when modules are sharded across runners, indicating the progress of specific shards.

```text
event: search.progress
data: {"search_id":"SEARCH_ID","status":"running","message":"shard 1/3 progress 5/12","result_cards_count":17,"timestamp":"2026-06-23T14:11:04.000Z"}
```

--------------------------------

### Example Radar Request

Source: https://github.com/osintly/documentation/blob/main/api-reference/authentification.mdx

This example demonstrates how to make a request to the Radar API using a free API key. Ensure your key is valid for the Radar feature.

```bash
curl -X GET "https://api.osint.ly/radar/breaches?limit=3&sortBy=recently-added"
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Example Radar request (free API key)

Source: https://github.com/osintly/documentation/blob/main/api-reference/authentification.mdx

Example request to the Radar API using a free API key.

```APIDOC
## Example Radar request (free API key)

```bash
curl -X GET "https://api.osint.ly/radar/breaches?limit=3&sortBy=recently-added"
  -H "Authorization: Bearer YOUR_API_KEY"
```
```

--------------------------------

### Concrete BYOK SSE Output Example

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

This example shows the Server-Sent Events (SSE) output for Bring Your Own Key (BYOK) streams, including result and completion messages.

```text
event: byok.result
data: {"search_id":"SEARCH_ID","provider":"osint_industries","card":{"source":"github","username":"target"},"timestamp":"2026-06-23T14:11:03.000Z"}

event: byok.finished
data: {"search_id":"SEARCH_ID","provider":"osint_industries","status":"success","resultCount":6,"timestamp":"2026-06-23T14:11:08.000Z"}
```

--------------------------------

### Concrete SSE Output Example

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

This is an example of the Server-Sent Events (SSE) output you might receive, including connection, module results, and search completion messages.

```text
event: connected
data: {"search_id":"SEARCH_ID","timestamp":"2026-06-23T14:10:01.000Z"}

event: module.result
data: {"search_id":"SEARCH_ID","module":{"id":"github","name":"GitHub"},"card":{"github_001":{"username":"target"}},"timestamp":"2026-06-23T14:10:03.000Z"}

event: search.finished
data: {"search_id":"SEARCH_ID","status":"completed","totals":{"module_results":1},"timestamp":"2026-06-23T14:10:09.000Z"}
```

--------------------------------

### Typical Successful SSE Session

Source: https://github.com/osintly/documentation/blob/main/api-reference/sse-reference.mdx

This example shows the expected event sequence for a successful search execution, including connection, progress updates, module results, and final completion.

```text
event: connected
data: {"search_id":"4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f","timestamp":"2026-06-23T14:10:01.000Z"}

event: search.progress
data: {"search_id":"4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f","status":"running","message":"orchestration started","timestamp":"2026-06-23T14:10:01.100Z"}

event: module.result
data: {"search_id":"4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f","module":{"id":"github","name":"GitHub"},"card":{"github_001":{"username":"target","profile_url":"https://github.com/target"}},"timestamp":"2026-06-23T14:10:03.000Z"}

event: module.result
data: {"search_id":"4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f","module":{"id":"gravatar","name":"Gravatar"},"card":{"gravatar_001":{"email_hash":"md5:...","profile_url":"https://gravatar.com/..."}},"timestamp":"2026-06-23T14:10:05.000Z"}

event: search.finished
data: {"search_id":"4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f","status":"completed","totals":{"module_results":2},"execution_time_ms":8120,"timestamp":"2026-06-23T14:10:09.000Z"}
```

--------------------------------

### Typical BYOK SSE Session

Source: https://github.com/osintly/documentation/blob/main/api-reference/sse-reference.mdx

This example illustrates a session using Bring Your Own Key (BYOK) providers, showing events for connected, BYOK results, and provider-specific completion statuses before the final search completion.

```text
event: connected
data: {"search_id":"f1d0de6e-5f8e-42de-b88d-4b895be61d40","timestamp":"2026-06-23T14:20:01.000Z"}

event: byok.result
data: {"search_id":"f1d0de6e-5f8e-42de-b88d-4b895be61d40","provider":"osint_industries","card":{"source":"github","username":"target","url":"https://github.com/target"},"timestamp":"2026-06-23T14:20:02.500Z"}

event: byok.result
data: {"search_id":"f1d0de6e-5f8e-42de-b88d-4b895be61d40","provider":"sherlockeye","card":{"byok_sherlockeye":{"source":"social","handle":"target"}},"timestamp":"2026-06-23T14:20:03.100Z"}

event: byok.finished
data: {"search_id":"f1d0de6e-5f8e-42de-b88d-4b895be61d40","provider":"osint_industries","status":"success","resultCount":7,"timestamp":"2026-06-23T14:20:06.900Z"}

event: byok.finished
data: {"search_id":"f1d0de6e-5f8e-42de-b88d-4b895be61d40","provider":"sherlockeye","status":"no_results","resultCount":0,"timestamp":"2026-06-23T14:20:07.200Z"}

event: search.finished
data: {"search_id":"f1d0de6e-5f8e-42de-b88d-4b895be61d40","status":"completed","totals":{"module_results":7},"execution_time_ms":10004,"timestamp":"2026-06-23T14:20:11.000Z"}
```

--------------------------------

### Typical Sharding/Capacity SSE Session

Source: https://github.com/osintly/documentation/blob/main/api-reference/sse-reference.mdx

This example demonstrates SSE events related to search execution involving sharding and capacity management, showing progress messages and resource availability.

```text
event: search.progress
data: {"search_id":"8d904b9c-60fa-4b33-a6ee-1bc6ab55ee8f","status":"running","message":"waiting runner capacity (status poll: 2 reachable, 0 available)","timestamp":"2026-06-23T14:25:00.000Z"}

event: search.progress
data: {"search_id":"8d904b9c-60fa-4b33-a6ee-1bc6ab55ee8f","status":"running","message":"shard 1/3 progress 4/12","result_cards_count":11,"timestamp":"2026-06-23T14:25:15.000Z"}

event: search.progress
data: {"search_id":"8d904b9c-60fa-4b33-a6ee-1bc6ab55ee8f","status":"running","message":"shard 2/3 progress 9/12","result_cards_count":26,"timestamp":"2026-06-23T14:25:22.000Z"}
```

--------------------------------

### Typical Failed SSE Session

Source: https://github.com/osintly/documentation/blob/main/api-reference/sse-reference.mdx

This example shows the SSE event sequence for a search execution that failed, including connection and a final 'failed' status with an error reason.

```text
event: connected
data: {"search_id":"95c36c17-f76e-4911-bd4e-8ea57515b2fb","timestamp":"2026-06-23T14:15:00.000Z"}

event: search.finished
data: {"search_id":"95c36c17-f76e-4911-bd4e-8ea57515b2fb","status":"failed","error":"NO_ELIGIBLE_RUNNER","timestamp":"2026-06-23T14:15:01.000Z"}
```

--------------------------------

### Module Selection for POST /search

Source: https://github.com/osintly/documentation/blob/main/api-reference/domains.mdx

This example shows how to use the `modules` field to restrict the search to specific module IDs. This is useful when you need to target a known set of modules for a given query.

```json
{
  "query": {
    "type": "Email Address",
    "value": "target@example.com"
  },
  "modules": {
    "mode": "selected",
    "ids": [
      "4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f",
      "95c36c17-f76e-4911-bd4e-8ea57515b2fb"
    ]
  }
}
```

--------------------------------

### Test Radar Feature

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

Access the Radar feature, which is free but requires an authenticated API key. This example demonstrates fetching breach data, limited and sorted.

```bash
curl -X GET "https://api.osint.ly/radar/breaches?limit=2&sortBy=recently-added" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

--------------------------------

### Basic GET Request for Domain Logo

Source: https://github.com/osintly/documentation/blob/main/api-reference/logos.mdx

Use a simple GET request to the base URL followed by the domain to retrieve a logo image directly. The 'www.' prefix is automatically handled.

```http
GET https://logos.osint.ly/{domain}
```

```http
https://logos.osint.ly/github.com
https://logos.osint.ly/stripe.com
https://logos.osint.ly/openai.com
```

```http
https://logos.osint.ly/www.github.com  →  same as github.com
```

--------------------------------

### Get Usage Information

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

Retrieve information about your current global and daily API usage windows. This is useful for monitoring your consumption and staying within rate limits.

```APIDOC
## GET /usage

### Description
Reads current global and daily usage windows.

### Method
GET

### Endpoint
/usage

### Request Example
```bash
curl -X GET "https://api.osint.ly/usage" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

### Response
#### Success Response (200)
- **Usage Window Details** (object) - Information about global and daily usage limits and current consumption.

#### Response Example
```json
{
  "global_limit": 10000,
  "global_used": 5000,
  "daily_limit": 1000,
  "daily_used": 200,
  "reset_time": "2023-10-27T10:00:00Z"
}
```

### Error Handling
- **429 Too Many Requests**: Indicates that you have exceeded the rate limit. Respect `Retry-After` and `X-RateLimit-Reset` headers before retrying.
```

--------------------------------

### Example Tag and Note

Source: https://github.com/osintly/documentation/blob/main/search-analysis/card-annotations.mdx

Attach notes and tags to a search result. Use notes for investigation updates, action items, or decision rationale. Tags help categorize findings.

```text
Tag: Investigate
Note: Matched 3 breaches. Check HIPAA compliance.
Contact legal team by Friday.
```

--------------------------------

### HTTP GET Request for Domain Logo

Source: https://github.com/osintly/documentation/blob/main/collaboration/logo-service.mdx

Send a GET request to this endpoint with the domain as part of the URL path. The service returns the logo image directly.

```http
GET https://logos.osint.ly/{domain}
```

--------------------------------

### Get Usage Limits

Source: https://github.com/osintly/documentation/blob/main/api-reference/endpoint/usage.mdx

Retrieves the current global and daily usage limits associated with your API key.

```APIDOC
## GET /usage

### Description
Retrieves the current global and daily usage limits for the authenticated API key.

### Method
GET

### Endpoint
/usage

### Response
#### Success Response (200)
- **global_limit** (integer) - The total number of requests allowed globally.
- **daily_limit** (integer) - The total number of requests allowed per day.
- **current_global_usage** (integer) - The number of requests already made globally.
- **current_daily_usage** (integer) - The number of requests already made today.
```

--------------------------------

### Validate token

Source: https://github.com/osintly/documentation/blob/main/api-reference/authentification.mdx

Use the root auth endpoint `GET /` to quickly validate a token.

```APIDOC
## Validate token

```bash
curl -X GET "https://api.osint.ly"
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response Example

```json
{
  "message": "Authorization Valid",
  "help": "https://docs.osint.ly/api-reference/quick-start"
}
```
```

--------------------------------

### Get API Usage

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

Use this endpoint to retrieve current global and daily usage windows for your API key. Respect rate limit headers like `Retry-After` and `X-RateLimit-Reset` if you receive a `429` status code.

```bash
curl -X GET "https://api.osint.ly/usage" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

--------------------------------

### Basic Logo Request

Source: https://github.com/osintly/documentation/blob/main/api-reference/logos.mdx

Retrieve a domain logo by making a GET request to the specified URL. The `www.` prefix is automatically handled.

```APIDOC
## GET /logos.osint.ly/{domain}

### Description
Fetches the logo image for a given domain.

### Method
GET

### Endpoint
`https://logos.osint.ly/{domain}`

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain name for which to fetch the logo (e.g., `github.com`, `stripe.com`). The `www.` prefix is automatically stripped.

### Response
#### Success Response (200)
Returns the logo image directly. The `Content-Type` header indicates the image format (e.g., `image/png`, `image/svg+xml`).

#### Response Example
(Binary image data)
```

--------------------------------

### Get Radar Breach by Name

Source: https://github.com/osintly/documentation/blob/main/api-reference/endpoint/radar-breach-by-name.mdx

Fetches detailed information for a specific Radar breach identified by its name. This is a GET request that requires an API key.

```APIDOC
## GET /radar/breaches/{name}

### Description
Get detailed Radar breach information by breach name. Free plan endpoint that requires an API key.

### Method
GET

### Endpoint
/radar/breaches/{name}

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the breach to retrieve details for.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
(Response schema not provided in source)

#### Response Example
(Response example not provided in source)
```

--------------------------------

### Get Search State

Source: https://github.com/osintly/documentation/blob/main/api-reference/endpoint/get.mdx

Retrieve current execution status and metadata for a search ID.

```APIDOC
## GET /search/{id}

### Description
Retrieve current execution status and metadata for a search ID.

### Method
GET

### Endpoint
/search/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the search to retrieve the state for.
```

--------------------------------

### POST /search

Source: https://github.com/osintly/documentation/blob/main/api-reference/endpoint/search.mdx

Queue a new search task and optionally configure a webhook callback.

```APIDOC
## POST /search

### Description
Queue a new search task and optionally configure a webhook callback.

### Method
POST

### Endpoint
/search
```

--------------------------------

### Create a Search with Selected Modules

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

Perform a search for an email address, but restrict the execution to specific modules using their IDs. If 'modules' is omitted, default modules are used.

```bash
curl -X POST "https://api.osint.ly/search" \
  -H "Authorization: Bearer $OSINTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": { \
      "type": "Email Address", \
      "value": "target@example.com" \
    }, \
    "modules": { \
      "mode": "selected", \
      "ids": [ \
        "4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f", \
        "95c36c17-f76e-4911-bd4e-8ea57515b2fb" \
      ] \
    } \
  }'
```

--------------------------------

### Check Osintly Service Health

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

Use this endpoint to verify if the Osintly API service is operational. This is a simple GET request to the health endpoint.

```bash
curl -X GET "https://api.osint.ly/health"
```

--------------------------------

### Create a Basic Email Search

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

Initiate a search for an email address, specifying features like breached accounts and registered accounts. The cache mode is set to 'prefer'.

```bash
curl -X POST "https://api.osint.ly/search" \
  -H "Authorization: Bearer $OSINTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "query": { \
      "type": "Email Address", \
      "value": "target@example.com" \
    }, \
    "features": { \
      "breached_accounts": true, \
      "registered_accounts": "include" \
    }, \
    "cache": { \
      "mode": "prefer" \
    } \
  }'
```

--------------------------------

### Stream Search Progress (SSE)

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

Use this command to stream incremental events while a search is running. This allows you to monitor progress and receive results as they become available.

```bash
curl -N -X GET "https://api.osint.ly/search/SEARCH_ID/stream" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

--------------------------------

### Stream Search Progress with cURL

Source: https://github.com/osintly/documentation/blob/main/api-reference/endpoint/stream.mdx

Use this command to connect to the search stream endpoint and receive real-time updates. Ensure you replace 'YOUR_API_KEY' with your actual API key.

```bash
curl -N -X GET "https://api.osint.ly/search/4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f/stream" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Connected Event

Source: https://github.com/osintly/documentation/blob/main/api-reference/sse-reference.mdx

Emitted immediately after the SSE connection is established. Includes search ID and timestamp.

```text
event: connected
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","timestamp":"2026-05-27T12:00:00.000Z"}
```

--------------------------------

### Creating a Search with Webhook Delivery

Source: https://github.com/osintly/documentation/blob/main/api-reference/webhooks.mdx

Configure webhook delivery when creating a search by including the `delivery.webhook` object in the request payload.

```APIDOC
## POST /search

### Description
Creates a new search with optional webhook delivery configuration.

### Method
POST

### Endpoint
/search

### Parameters
#### Request Body
- **query** (object) - Required - The search query parameters.
  - **type** (string) - Required - The type of the search query (e.g., "Email Address").
  - **value** (string) - Required - The value to search for.
- **delivery** (object) - Optional - Delivery configuration.
  - **webhook** (object) - Optional - Webhook delivery configuration.
    - **url** (string) - Required - The URL of your webhook endpoint.
    - **secret** (string) - Optional - A secret key to sign webhook payloads for verification.

### Request Example
```json
{
  "query": {
    "type": "Email Address",
    "value": "target@example.com"
  },
  "delivery": {
    "webhook": {
      "url": "https://client.example/webhooks/osintly",
      "secret": "super-secret-webhook-key"
    }
  }
}
```
```

--------------------------------

### Stream Search Execution with cURL

Source: https://github.com/osintly/documentation/blob/main/api-reference/sse-reference.mdx

Use this cURL command to connect to the SSE stream for a specific search ID. Replace SEARCH_ID and YOUR_API_KEY with your actual values. The -N flag prevents buffering, ensuring real-time output.

```bash
curl -N -X GET "https://api.osint.ly/search/SEARCH_ID/stream" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### List and Fetch Leak Source Payloads

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

Use these cURL commands to list available leak sources for a given search ID or fetch a specific source's payload, optionally paginated.

```bash
# List available leak sources for a search
curl -X GET "https://api.osint.ly/search/SEARCH_ID/results/leaks" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

```bash
# Fetch one source (optional page)
curl -X GET "https://api.osint.ly/search/SEARCH_ID/results/leaks/snusbase?page=1" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

--------------------------------

### Stream Search Execution

Source: https://github.com/osintly/documentation/blob/main/api-reference/sse-reference.mdx

Use the GET /search/{id}/stream endpoint to receive real-time updates on search execution. This endpoint streams Server-Sent Events (SSE) that provide information about the search progress, results, and completion status.

```APIDOC
## GET /search/{id}/stream

### Description
Follow search execution in real time by subscribing to Server-Sent Events (SSE) from this endpoint. It provides live updates on the search process, including progress, results from various modules, and final status.

### Method
GET

### Endpoint
/search/{id}/stream

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the search to stream.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -N -X GET "https://api.osint.ly/search/SEARCH_ID/stream" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
This endpoint streams Server-Sent Events (SSE). The structure of the data within each event varies based on the event type.

**Event Types and Data Examples:**

- **connected**: Indicates a successful connection to the stream.
  ```json
  {
    "search_id": "4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f",
    "timestamp": "2026-06-23T14:10:01.000Z"
  }
  ```

- **search.progress**: Provides updates on the overall search status.
  ```json
  {
    "search_id": "4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f",
    "status": "running",
    "message": "orchestration started",
    "timestamp": "2026-06-23T14:10:01.100Z"
  }
  ```

- **module.result**: Contains results obtained from a specific module.
  ```json
  {
    "search_id": "4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f",
    "module": {"id": "github", "name": "GitHub"},
    "card": {"github_001": {"username": "target", "profile_url": "https://github.com/target"}},
    "timestamp": "2026-06-23T14:10:03.000Z"
  }
  ```

- **byok.result**: Contains results from a BYOK (Bring Your Own Key) provider.
  ```json
  {
    "search_id": "f1d0de6e-5f8e-42de-b88d-4b895be61d40",
    "provider": "osint_industries",
    "card": {"source": "github", "username": "target", "url": "https://github.com/target"},
    "timestamp": "2026-06-23T14:20:02.500Z"
  }
  ```

- **search.finished**: Indicates the completion of the search, with status and totals.
  ```json
  {
    "search_id": "4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f",
    "status": "completed",
    "totals": {"module_results": 2},
    "execution_time_ms": 8120,
    "timestamp": "2026-06-23T14:10:09.000Z"
  }
  ```

- **byok.finished**: Indicates the completion of a BYOK provider's task.
  ```json
  {
    "search_id": "f1d0de6e-5f8e-42de-b88d-4b895be61d40",
    "provider": "osint_industries",
    "status": "success",
    "resultCount": 7,
    "timestamp": "2026-06-23T14:20:06.900Z"
  }
  ```

**Error Handling:**
- **search.finished** with `"status": "failed"` indicates an error during search execution.
  ```json
  {
    "search_id": "95c36c17-f76e-4911-bd4e-8ea57515b2fb",
    "status": "failed",
    "error": "NO_ELIGIBLE_RUNNER",
    "timestamp": "2026-06-23T14:15:01.000Z"
  }
  ```
```

--------------------------------

### Fetch Final Structured Results

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

Download the complete, structured results for a completed search. This endpoint provides the final output after the search has finished processing.

```bash
curl -X GET "https://api.osint.ly/search/SEARCH_ID/results" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

--------------------------------

### connected

Source: https://github.com/osintly/documentation/blob/main/api-reference/sse-reference.mdx

Sent immediately after the SSE connection is established. Contains the search ID and connection timestamp.

```APIDOC
## Event: connected

### Description
Sent immediately after the SSE connection is established.

### Data Fields
- **search_id** (string) - The unique identifier for the search.
- **timestamp** (string) - The time when the connection was established.
```

--------------------------------

### Set Logo as CSS Background

Source: https://github.com/osintly/documentation/blob/main/api-reference/logos.mdx

Apply domain logos as background images to HTML elements using CSS.

```css
.logo {
  background-image: url('https://logos.osint.ly/github.com');
}
```

--------------------------------

### POST /search Endpoint

Source: https://github.com/osintly/documentation/blob/main/api-reference/domains.mdx

This endpoint allows you to initiate a search with various query types and optional features. It supports specifying modules, leaks, features, cache modes, and delivery webhooks.

```APIDOC
## POST /search

### Description
Initiates a search operation with specified query parameters, features, caching, and delivery options.

### Method
POST

### Endpoint
/search

### Parameters
#### Request Body
- **query** (object) - Required. Contains `type` and `value` for the search query.
  - **type** (string) - Required. The type of data to search for (e.g., `Pseudonym`, `Email Address`, `Domain Name`, `Cryptocurrency`, `IP Address`).
  - **value** (string) - Required. The value to search for.
- **modules** (object) - Optional. Used to restrict execution to a specific set of modules.
  - **mode** (string) - Optional. If `selected`, execution is limited to `modules.ids`.
  - **ids** (array) - Optional. A list of module IDs to execute.
- **leaks** (object) - Optional. Used to restrict leak providers.
  - **mode** (string) - Optional. If `selected`, execution is limited to `leaks.sources`.
  - **sources** (array) - Optional. A list of leak provider source codes/names.
- **features** (object) - Optional. Controls additional features like `breached_accounts` and `registered_accounts`.
  - **breached_accounts** (boolean) - Optional. Whether to include breached account information.
  - **registered_accounts** (string) - Optional. Controls the inclusion of registered accounts (e.g., `include`).
- **cache** (object) - Optional. Controls caching behavior.
  - **mode** (string) - Optional. Use `bypass` to force a fresh execution.
- **delivery** (object) - Optional. Configures delivery options, such as webhooks.
  - **webhook** (object) - Optional. Configuration for webhook delivery.
    - **url** (string) - Required. The URL for the webhook.
    - **secret** (string) - Required. The secret key for webhook authentication.

### Request Example
```json
{
  "query": {
    "type": "Email Address",
    "value": "target@example.com"
  },
  "features": {
    "breached_accounts": true,
    "registered_accounts": "include"
  },
  "cache": {
    "mode": "prefer"
  },
  "delivery": {
    "webhook": {
      "url": "https://client.example/webhooks/osintly",
      "secret": "super-secret-webhook-key"
    }
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the status of the search operation.
- **searchId** (string) - The unique identifier for the search.

#### Response Example
```json
{
  "status": "created",
  "searchId": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```

### Errors
- **400 Validation error**: Request shape or field values are invalid. Check enum values and data types.
- **401 Unauthorized**: Missing or invalid bearer token.
- **429 Rate limit exceeded**: Respect retry headers and retry after the reset window.
- **503 Dispatch unavailable**: Search creation failed at dispatch layer. Retry with backoff.
```

--------------------------------

### Stream Search Progress (SSE)

Source: https://github.com/osintly/documentation/blob/main/api-reference/quick-start.mdx

Receive incremental events as a search progresses. This is useful for real-time monitoring of ongoing searches.

```APIDOC
## Stream Search Progress (SSE)

### Description
Receive incremental events while the search is running. This allows for real-time monitoring of search progress.

### Method
GET

### Endpoint
`https://api.osint.ly/search/SEARCH_ID/stream`

### Parameters
#### Path Parameters
- **SEARCH_ID** (string) - Required - The unique identifier for the search.

### Request Example
```bash
curl -N -X GET "https://api.osint.ly/search/SEARCH_ID/stream" \
  -H "Authorization: Bearer $OSINTLY_API_KEY"
```

### Response
This endpoint uses Server-Sent Events (SSE). Events include `connected`, `module.result`, `search.finished`, `byok.result`, `byok.finished`, and `search.progress`.
```

--------------------------------

### Configure Webhook on Search Creation

Source: https://github.com/osintly/documentation/blob/main/api-reference/webhooks.mdx

Specify the webhook URL and secret when creating a search to receive notifications upon completion.

```json
{
  "query": {
    "type": "Email Address",
    "value": "target@example.com"
  },
  "delivery": {
    "webhook": {
      "url": "https://client.example/webhooks/osintly",
      "secret": "super-secret-webhook-key"
    }
  }
}
```

--------------------------------

### Fetch Logo as Blob in JavaScript

Source: https://github.com/osintly/documentation/blob/main/api-reference/logos.mdx

Retrieve a logo image as a Blob object using the Fetch API in JavaScript.

```javascript
const res = await fetch('https://logos.osint.ly/stripe.com');
const blob = await res.blob();
```

--------------------------------

### Dynamically Render Logo in React

Source: https://github.com/osintly/documentation/blob/main/api-reference/logos.mdx

Use a React component to dynamically display a domain logo based on a variable.

```jsx
<img src={`https://logos.osint.ly/${domain}`} alt={`${domain} logo`} />
```

--------------------------------

### Authorization Header Format

Source: https://github.com/osintly/documentation/blob/main/api-reference/authentification.mdx

All API endpoints require a bearer token in the `Authorization` header. This is the standard format for including your API key.

```bash
Authorization: Bearer YOUR_API_KEY
```

--------------------------------

### Search Progress Event

Source: https://github.com/osintly/documentation/blob/main/api-reference/sse-reference.mdx

Sent during orchestration and shard execution. Includes search ID, status, progress message, result card count, and timestamp.

```text
event: search.progress
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","status":"running","message":"shard 1/3 progress 6/18","result_cards_count":13,"timestamp":"2026-05-27T12:00:05.000Z"}
```

--------------------------------

### Header format

Source: https://github.com/osintly/documentation/blob/main/api-reference/authentification.mdx

All API endpoints require a bearer token in the `Authorization` header.

```APIDOC
## Header format

```bash
Authorization: Bearer YOUR_API_KEY
```
```

--------------------------------

### System Endpoints

Source: https://github.com/osintly/documentation/blob/main/api-reference/introduction.mdx

Endpoints for checking the system's health and authentication status.

```APIDOC
## GET /health

### Description
Checks the health status of the system.

### Method
GET

### Endpoint
/health

## GET /

### Description
Provides authentication status or information.

### Method
GET

### Endpoint
/

```

--------------------------------

### Validate API Token

Source: https://github.com/osintly/documentation/blob/main/api-reference/authentification.mdx

Use the root auth endpoint to quickly validate your API token. A successful response confirms the token is valid.

```bash
curl -X GET "https://api.osint.ly"
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "message": "Authorization Valid",
  "help": "https://docs.osint.ly/api-reference/quick-start"
}
```

--------------------------------

### byok.finished

Source: https://github.com/osintly/documentation/blob/main/api-reference/sse-reference.mdx

Sent once per BYOK provider when its execution completes. Includes search ID, provider, status, result count, and timestamp.

```APIDOC
## Event: byok.finished

### Description
Sent once per provider when provider execution completes.

### Data Fields
- **search_id** (string) - The unique identifier for the search.
- **provider** (string) - The identifier of the BYOK provider.
- **status** (string) - The completion status (`success`, `no_results`, `failed`).
- **resultCount** (integer) - The number of results produced by the provider.
- **timestamp** (string) - The time when the provider finished.
```