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

# API Overview

> Base URL, authentication, pagination, and common patterns

# API Overview

## Base URL

All API requests should be made to:

```
https://api.naturalead.ai/api
```

## Authentication

Every request must include an API key via one of:

| Method       | Header          | Format                                           |
| ------------ | --------------- | ------------------------------------------------ |
| API Key      | `X-API-Key`     | `nl_live_<key>` or `nl_test_<key>`               |
| Bearer Token | `Authorization` | `Bearer nl_live_<key>` or `Bearer nl_test_<key>` |

See [Authentication](/authentication) for full details.

## Content Type

All request bodies must be JSON:

```
Content-Type: application/json
```

## Pagination

Paginated endpoints use `skip` and `limit` query parameters:

| Parameter | Type    | Default | Description               |
| --------- | ------- | ------- | ------------------------- |
| `skip`    | integer | `0`     | Number of records to skip |
| `limit`   | integer | `50`    | Maximum records to return |

Paginated responses vary by endpoint. Common formats include:

```json theme={null}
{
  "data": [...],
  "total": 150,
  "skip": 0,
  "limit": 50
}
```

Some endpoints (e.g., leads with filters) return:

```json theme={null}
{
  "leads": [...],
  "total": 150
}
```

## Filtering

Many list endpoints support filtering via query parameters. The leads API also supports advanced filtering via POST request bodies with complex conditions.

### Filter operators

| Operator          | Description     | Example                                                                         |
| ----------------- | --------------- | ------------------------------------------------------------------------------- |
| `is`              | Exact match     | `{ "field": "status", "operator": "is", "value": "new" }`                       |
| `is_not`          | Not equal       | `{ "field": "status", "operator": "is_not", "value": "disqualified" }`          |
| `contains`        | Substring match | `{ "field": "name", "operator": "contains", "value": "john" }`                  |
| `is_any_of`       | In list         | `{ "field": "status", "operator": "is_any_of", "value": ["new", "contacted"] }` |
| `includes_any_of` | Array overlap   | `{ "field": "tags", "operator": "includes_any_of", "value": ["vip"] }`          |
| `is_before`       | Date comparison | `{ "field": "createdAt", "operator": "is_before", "value": "2026-01-01" }`      |
| `is_after`        | Date comparison | `{ "field": "createdAt", "operator": "is_after", "value": "2026-01-01" }`       |

## Rate Limits

All responses include rate limit headers (IETF draft-7):

```
RateLimit-Limit: 1000
RateLimit-Remaining: 742
RateLimit-Reset: 34
```

See [Rate Limits](/rate-limits) for tier details.

## Error Format

All errors return a consistent JSON structure:

```json theme={null}
{
  "error": "Human-readable error message",
  "details": "Additional context (optional)"
}
```

See [Error Reference](/errors) for all error codes.

## Request IDs

All requests are logged with a correlation ID for debugging. When contacting support, include the timestamp and endpoint of your request.

## API Domains

| Domain                                                           | Base Path              | Description                      |
| ---------------------------------------------------------------- | ---------------------- | -------------------------------- |
| [Leads](/api-reference/leads/list-leads)                         | `/api/leads`           | Lead management and import       |
| [Lead Sync](/api-reference/lead-sync/bulk-sync)                  | `/api/leads/sync`      | Bulk CRM synchronization         |
| [Conversations](/api-reference/conversations/list-conversations) | `/api/conversations`   | AI-driven conversations          |
| [Campaigns](/api-reference/campaigns/list-campaigns)             | `/api/campaigns`       | Batch outreach campaigns         |
| [Agent Config](/api-reference/agent-config/list-agents)          | `/api/agent-config`    | AI agent configuration           |
| [Knowledge Bases](/api-reference/knowledge-bases/list-kbs)       | `/api/knowledge-bases` | Document and content management  |
| [Analytics](/api-reference/analytics/overview-stats)             | `/api/analytics`       | Reporting and metrics            |
| [A/B Testing](/api-reference/ab-testing/list-tests)              | `/api/ab-tests`        | Agent experiment management      |
| [Audit Logs](/api-reference/audit-logs/list-logs)                | `/api/audit-logs`      | Compliance and monitoring        |
| [Integrations](/api-reference/integrations/get-integrations)     | `/api/integrations`    | Channel configuration            |
| [API Keys](/api-reference/api-keys/list-keys)                    | `/api/api-keys`        | Key lifecycle management         |
| [Accounts](/api-reference/accounts/get-account)                  | `/api/accounts`        | Organization and team management |
| [Webhooks](/api-reference/webhooks/lead-inbound)                 | `/api/webhooks`        | Inbound message handling         |