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.
Authentication
All API requests must be authenticated using an API key. API keys provide stateless, scoped authentication for programmatic access.Key format
| Environment | Prefix | Example |
|---|---|---|
| Production | nl_live_ | nl_live_a1b2c3d4e5f6... (64 hex chars) |
| Test | nl_test_ | nl_test_a1b2c3d4e5f6... (64 hex chars) |
Passing your API key
You can authenticate using either method: Option 1: X-API-Key header (recommended)When both
X-API-Key and Authorization: Bearer nl_* are present, the X-API-Key header takes precedence.Key security
- The full key is shown only once at creation. Naturalead stores only a SHA-256 hash.
- Keys are scoped to a single account (organization).
- Each key has a
keyHint(last 4 characters) for identification in the dashboard. - Keys can be set to expire at a specific date.
Creating API keys
Create keys via the dashboard (Settings > API Keys) or programmatically:Key lifecycle
| Action | Endpoint | Description |
|---|---|---|
| Create | POST /api/api-keys | Generate a new key with selected scopes |
| List | GET /api/api-keys | View all keys for the account (masked) |
| Revoke | PATCH /api/api-keys/:id/revoke | Disable a key (irreversible) |
| Rotate | POST /api/api-keys/:id/rotate | Revoke old key, generate new one atomically |
| Delete | DELETE /api/api-keys/:id | Permanently delete a revoked key |
Scopes and Permissions
API keys are scoped to specific permissions. A key can only perform actions matching its scopes.Available scopes
| Domain | Scope | Description |
|---|---|---|
| Leads | leads:view | List, search, and filter leads |
| Leads | leads:import | Create, update, delete, and import leads |
| Leads | leads:start_conversation | Start conversations with leads |
| Leads | leads:sync_create | Bulk sync (create/update) leads |
| Leads | leads:sync_delete | Bulk delete synced leads |
| Conversations | conversations:view | List and read conversations |
| Conversations | conversations:edit | Edit conversation data |
| Conversations | conversations:send_message | Send messages in conversations |
| Conversations | conversations:change_status | Update conversation status |
| Agent Config | agent_config:view | View agent configurations |
| Agent Config | agent_config:edit | Create and modify agents |
| Knowledge | knowledge:view | View knowledge bases and documents |
| Knowledge | knowledge:upload | Upload documents and manage sources |
| Knowledge | knowledge:delete | Delete documents and knowledge bases |
| Campaigns | campaigns:view | List and view campaigns |
| Campaigns | campaigns:create | Create new campaigns |
| Campaigns | campaigns:edit | Update campaign settings |
| Campaigns | campaigns:launch | Launch and pause campaigns |
| Campaigns | campaigns:delete | Delete campaigns |
| Analytics | analytics:view | View analytics and reports |
| A/B Testing | ab_testing:view | View A/B tests |
| A/B Testing | ab_testing:manage | Create and manage A/B tests |
| Audit | audit:view | View audit logs |
| Audit | audit:export | Export audit logs |
| API Keys | api_keys:view | View API keys |
| API Keys | api_keys:manage | Manage API keys |
When creating an API key, you can only grant scopes that your own role has permission for. This prevents privilege escalation.
Error responses
| Status | Response | Cause |
|---|---|---|
401 | {"error": "Invalid or expired API key"} | API key is revoked, expired, or not found |
401 | {"error": "Authentication required. Provide an API key via X-API-Key header or Authorization: Bearer header."} | No API key provided |
403 | {"error": "Forbidden", "message": "API key does not have the required scope (requires: leads:view)."} | Key is missing the required permission |
403 | {"error": "Forbidden", "message": "You do not have permission to perform this action (requires: leads:view)."} | Your role lacks the required permission |