# Naturalead API

## Docs

- [Create A/B Test](https://docs.naturalead.ai/api-reference/ab-testing/create-test.md): Creates a new A/B test in draft status. The test must include at least two variants, each referencing a valid agent configuration with a traffic weight. Requires `ab_testing:manage` permission.
- [Delete A/B Test](https://docs.naturalead.ai/api-reference/ab-testing/delete-test.md): Permanently deletes an A/B test. Only tests in draft or completed status can be deleted. Running or paused tests must be completed first. Requires `ab_testing:manage` permission.
- [Get Test Results](https://docs.naturalead.ai/api-reference/ab-testing/get-results.md): Returns detailed performance results for each variant in the A/B test, including conversation counts, qualification rates, and statistical significance indicators. Requires `ab_testing:view` permission.
- [Get A/B Test](https://docs.naturalead.ai/api-reference/ab-testing/get-test.md): Returns a single A/B test by ID, including its variant configuration and current status. Requires `ab_testing:view` permission.
- [List A/B Tests](https://docs.naturalead.ai/api-reference/ab-testing/list-tests.md): Returns all A/B tests for the current account, ordered by most recently updated. Requires `ab_testing:view` permission.
- [Update Test Status](https://docs.naturalead.ai/api-reference/ab-testing/update-status.md): Transitions an A/B test to a new status. Valid transitions: draft -> running, running -> paused, paused -> running, running -> completed, paused -> completed. Requires `ab_testing:manage` permission.
- [Update A/B Test](https://docs.naturalead.ai/api-reference/ab-testing/update-test.md): Updates an existing A/B test. Only tests in draft status can have their variants modified. Name and description can be updated in any status. Requires `ab_testing:manage` permission.
- [Available Roles](https://docs.naturalead.ai/api-reference/accounts/available-roles.md): Returns the list of all RBAC roles defined in the system. Useful for populating role selection dropdowns in the UI.
- [Get Current Account](https://docs.naturalead.ai/api-reference/accounts/get-account.md): Returns the current account's details including name, slug, and plan. Requires `account:view` permission.
- [Get My Roles](https://docs.naturalead.ai/api-reference/accounts/get-roles.md): Returns the authenticated user's roles and resolved permissions for the current account. Useful for client-side RBAC gating.
- [List Members](https://docs.naturalead.ai/api-reference/accounts/list-members.md): Returns all members of the current account with their user details and assigned roles. Requires `team:view` permission.
- [Remove Member](https://docs.naturalead.ai/api-reference/accounts/remove-member.md): Removes a member from the current account. The user's access to this account is revoked immediately. Requires `team:remove` permission.
- [Update Account](https://docs.naturalead.ai/api-reference/accounts/update-account.md): Updates the current account's profile fields. Only provided fields are updated; omitted fields remain unchanged. Requires `account:edit` permission.
- [Update Member Roles](https://docs.naturalead.ai/api-reference/accounts/update-member-roles.md): Updates the RBAC roles assigned to a team member. The roles array replaces the member's existing roles entirely. Requires `team:change_role` permission.
- [Apply Template](https://docs.naturalead.ai/api-reference/agent-config/apply-template.md): Returns the full agent configuration for a given template without persisting it. The caller can review and modify the configuration before saving it via `createAgent` or `updateAgent`. Requires `agent_config:edit` permission.
- [Attach Knowledge Base](https://docs.naturalead.ai/api-reference/agent-config/attach-kb.md): Attaches an existing knowledge base to the specified agent. The agent will use this knowledge base for RAG-powered responses. Requires `agent_config:edit` permission.
- [Create Agent](https://docs.naturalead.ai/api-reference/agent-config/create-agent.md): Creates a new agent configuration for the current account. Requires `agent_config:edit` permission.
- [Delete Agent](https://docs.naturalead.ai/api-reference/agent-config/delete-agent.md): Permanently deletes an agent configuration. Fails with `409` if the agent is referenced by active campaigns. Requires `agent_config:edit` permission.
- [Detach Knowledge Base](https://docs.naturalead.ai/api-reference/agent-config/detach-kb.md): Removes a knowledge base from the specified agent. The agent will no longer use this knowledge base for RAG context. Requires `agent_config:edit` permission.
- [Get Agent](https://docs.naturalead.ai/api-reference/agent-config/get-agent.md): Returns a single agent configuration by ID, with `knowledgeBaseIds` populated as full knowledge base objects. Requires `agent_config:view` permission.
- [Get Agent Stats](https://docs.naturalead.ai/api-reference/agent-config/get-agent-stats.md): Returns aggregated conversation statistics for the specified agent, including total conversations, qualified leads, qualification rate, and response rate. Requires `agent_config:view` permission.
- [Get Templates](https://docs.naturalead.ai/api-reference/agent-config/get-templates.md): Returns the list of pre-built agent configuration templates. Each template includes an id, name, and description. Use the `applyTemplate` endpoint to retrieve the full configuration for a template. Requires `agent_config:view` permission.
- [List Agent Knowledge Bases](https://docs.naturalead.ai/api-reference/agent-config/list-agent-kbs.md): Returns the knowledge bases currently attached to the specified agent. Requires `agent_config:view` permission.
- [List Agents](https://docs.naturalead.ai/api-reference/agent-config/list-agents.md): Returns all agent configurations for the current account. Pass `?single=true` for legacy single-agent mode (returns a single object instead of an array, creating a default agent if none exists). Requires `agent_config:view` permission.
- [Update Agent](https://docs.naturalead.ai/api-reference/agent-config/update-agent.md): Updates an existing agent configuration. Accepts a partial body — only the provided fields are updated. Requires `agent_config:edit` permission.
- [Campaign Performance](https://docs.naturalead.ai/api-reference/analytics/campaign-stats.md): Returns performance statistics for all campaigns in the current account, including send rates, reply rates, and qualification outcomes. Requires `analytics:view` permission.
- [Daily Stats](https://docs.naturalead.ai/api-reference/analytics/daily-stats.md): Returns daily breakdowns of key metrics over the specified time range, suitable for charting and trend analysis. Requires `analytics:view` permission.
- [Funnel Data](https://docs.naturalead.ai/api-reference/analytics/funnel.md): Returns funnel analysis showing lead progression through conversation stages, from initial contact to qualification or disqualification. Requires `analytics:view` permission.
- [Overview Stats](https://docs.naturalead.ai/api-reference/analytics/overview-stats.md): Returns high-level analytics overview for the current account, including total leads, conversations, qualification rates, and channel breakdowns. Requires `analytics:view` permission.
- [Create API Key](https://docs.naturalead.ai/api-reference/api-keys/create-key.md): Creates a new API key for the current account. The full key is returned only once in the response and is never stored or retrievable again. The key creator can only grant scopes (permissions) that they themselves hold. Requires `api_keys:manage` permission.
- [Delete API Key](https://docs.naturalead.ai/api-reference/api-keys/delete-key.md): Permanently deletes a revoked API key. Only keys with status `revoked` can be deleted. Active keys must be revoked first. Requires `api_keys:manage` permission.
- [List API Keys](https://docs.naturalead.ai/api-reference/api-keys/list-keys.md): Returns all API keys for the current account. Keys are returned with masked values (keyPrefix and keyHint only). The full key is never returned after creation. Requires `api_keys:view` permission.
- [Revoke API Key](https://docs.naturalead.ai/api-reference/api-keys/revoke-key.md): Revokes an active API key. Revoked keys can no longer authenticate requests but remain in the system for audit purposes. They can be permanently deleted after revocation. Requires `api_keys:manage` permission.
- [Rotate API Key](https://docs.naturalead.ai/api-reference/api-keys/rotate-key.md): Rotates an API key by revoking the existing key and creating a new one with the same name, scopes, and environment. The new full key is returned only once. The old key is immediately invalidated. Requires `api_keys:manage` permission.
- [Export Audit Logs](https://docs.naturalead.ai/api-reference/audit-logs/export-logs.md): Exports audit logs as a downloadable file in the specified format. Supports the same filters as the list endpoint. The response is streamed with a Content-Disposition header for file download. Requires `audit:export` permission.
- [List Audit Logs](https://docs.naturalead.ai/api-reference/audit-logs/list-logs.md): Returns paginated audit logs for the current account with optional filtering by action, resource type, actor, and date range. Results are ordered by most recent first. Requires `audit:view` permission.
- [Create Campaign](https://docs.naturalead.ai/api-reference/campaigns/create-campaign.md): Creates a new campaign in draft status. The campaign must reference a valid agent configuration and optionally include lead filters, scheduling, and channel settings. Requires `campaigns:create` permission.
- [Delete Campaign](https://docs.naturalead.ai/api-reference/campaigns/delete-campaign.md): Permanently deletes a campaign that is in draft status. Only draft campaigns can be deleted. Requires `campaigns:delete` permission.
- [Get Campaign](https://docs.naturalead.ai/api-reference/campaigns/get-campaign.md): Returns a single campaign by ID, including its full lead list and stats. Requires `campaigns:view` permission.
- [Get Available Channels](https://docs.naturalead.ai/api-reference/campaigns/get-channels.md): Returns the list of messaging channels that are configured and available for the current account. Only channels with verified integrations are returned. Requires `campaigns:view` permission.
- [Launch Campaign](https://docs.naturalead.ai/api-reference/campaigns/launch-campaign.md): Launches a draft or scheduled campaign, starting outreach to matched leads. The campaign transitions to running status and begins sending messages according to its schedule and rate limit settings. Requires `campaigns:launch` permission.
- [List Campaigns](https://docs.naturalead.ai/api-reference/campaigns/list-campaigns.md): Returns all campaigns for the current account, ordered by most recently updated. Requires `campaigns:view` permission.
- [Pause Campaign](https://docs.naturalead.ai/api-reference/campaigns/pause-campaign.md): Pauses a running campaign, halting all outbound message sending. The campaign can be relaunched later. Requires `campaigns:launch` permission.
- [Update Campaign](https://docs.naturalead.ai/api-reference/campaigns/update-campaign.md): Updates a campaign that is in draft status. Only draft campaigns can be modified. Requires `campaigns:edit` permission.
- [Get Conversation](https://docs.naturalead.ai/api-reference/conversations/get-conversation.md): Returns a single conversation by its ID, including the full message history and qualification result. Requires `conversations:view` permission.
- [List Conversations](https://docs.naturalead.ai/api-reference/conversations/list-conversations.md): Returns all conversations for the current account. Supports filtering by status and full-text search across lead phone, email, and message content. Requires `conversations:view` permission.
- [Send Message](https://docs.naturalead.ai/api-reference/conversations/send-message.md): Sends a manual message in an existing conversation. The message is delivered via the conversation's channel. Requires `conversations:send_message` permission.
- [Start Conversation](https://docs.naturalead.ai/api-reference/conversations/start-conversation.md): Starts a new LLM-driven conversation with a lead. The system sends the initial outreach message via the specified channel. Requires `leads:start_conversation` permission.
- [Update Conversation Status](https://docs.naturalead.ai/api-reference/conversations/update-status.md): Updates the status of a conversation. Only transitions to `completed`, `handed_off`, or `dropped` are allowed. Requires `conversations:change_status` permission.
- [Configure Email](https://docs.naturalead.ai/api-reference/integrations/configure-email.md): Sets up or updates the email sending configuration for the account. Registers the email domain with Resend and returns DNS records that must be added to verify the domain. Requires `integrations:edit` permission.
- [Configure Telegram](https://docs.naturalead.ai/api-reference/integrations/configure-telegram.md): Sets or updates the Telegram bot token for the account. The token is verified by calling the Telegram getMe API before saving. Requires `integrations:edit` permission.
- [Get Integrations](https://docs.naturalead.ai/api-reference/integrations/get-integrations.md): Returns the current account's integration configuration, including WhatsApp, Telegram, and Email status. Masked secrets are returned for configured channels. Requires `integrations:view` permission.
- [Verify Email Domain](https://docs.naturalead.ai/api-reference/integrations/verify-email.md): Checks whether the email domain DNS records have been configured correctly. If verification succeeds, the domain is marked as verified and email sending is enabled. Requires `integrations:edit` permission.
- [Cancel Crawl Job](https://docs.naturalead.ai/api-reference/knowledge-bases/cancel-crawl-job.md): Cancels a crawl job. Pages already processed remain in the knowledge base. Requires `knowledge:upload` permission.
- [Crawl Sitemap](https://docs.naturalead.ai/api-reference/knowledge-bases/crawl-sitemap.md): Starts a crawl job that fetches pages from a sitemap (or a provided URL list) and ingests their content into the knowledge base. Each page is optionally distilled using LLM before storage. Requires `knowledge:upload` permission.
- [Create Knowledge Base](https://docs.naturalead.ai/api-reference/knowledge-bases/create-kb.md): Creates a new knowledge base for the current account. Requires `knowledge:upload` permission.
- [Create Webhook Source](https://docs.naturalead.ai/api-reference/knowledge-bases/create-webhook-source.md): Creates a new webhook source for a knowledge base. A webhook source defines how to fetch content from an external URL or execute a series of steps to produce content. Requires either `steps` or `url`. Requires `knowledge:upload` permission.
- [Delete Document](https://docs.naturalead.ai/api-reference/knowledge-bases/delete-document.md): Deletes a document from a knowledge base and removes it from the vector store. Requires `knowledge:delete` permission.
- [Delete Knowledge Base](https://docs.naturalead.ai/api-reference/knowledge-bases/delete-kb.md): Deletes a knowledge base and all associated documents, crawl jobs, and webhook sources. Requires `knowledge:delete` permission.
- [Delete Webhook Source](https://docs.naturalead.ai/api-reference/knowledge-bases/delete-webhook-source.md): Deletes a webhook source from a knowledge base. Requires `knowledge:delete` permission.
- [Get Crawl Job](https://docs.naturalead.ai/api-reference/knowledge-bases/get-crawl-job.md): Returns details of a specific crawl job including progress. Requires `knowledge:view` permission.
- [Get Knowledge Base](https://docs.naturalead.ai/api-reference/knowledge-bases/get-kb.md): Returns a single knowledge base by ID. Requires `knowledge:view` permission.
- [Get Webhook Source](https://docs.naturalead.ai/api-reference/knowledge-bases/get-webhook-source.md): Returns details of a specific webhook source. Requires `knowledge:view` permission.
- [List Crawl Jobs](https://docs.naturalead.ai/api-reference/knowledge-bases/list-crawl-jobs.md): Returns all crawl jobs for a knowledge base. Requires `knowledge:view` permission.
- [List Documents](https://docs.naturalead.ai/api-reference/knowledge-bases/list-documents.md): Returns all documents in a knowledge base. Requires `knowledge:view` permission.
- [List Knowledge Bases](https://docs.naturalead.ai/api-reference/knowledge-bases/list-kbs.md): Returns all knowledge bases for the current account. Requires `knowledge:view` permission.
- [List Webhook Sources](https://docs.naturalead.ai/api-reference/knowledge-bases/list-webhook-sources.md): Returns all webhook sources configured for a knowledge base. Requires `knowledge:view` permission.
- [Pause Crawl Job](https://docs.naturalead.ai/api-reference/knowledge-bases/pause-crawl-job.md): Pauses a running crawl job. The job can be resumed later. Requires `knowledge:upload` permission.
- [Resume Crawl Job](https://docs.naturalead.ai/api-reference/knowledge-bases/resume-crawl-job.md): Resumes a paused crawl job from where it left off. Requires `knowledge:upload` permission.
- [Scan Sitemap](https://docs.naturalead.ai/api-reference/knowledge-bases/sitemap-scan.md): Fetches and parses a sitemap URL to discover available pages. Returns the list of URLs found without starting a crawl. Requires `knowledge:upload` permission.
- [Toggle Webhook Source](https://docs.naturalead.ai/api-reference/knowledge-bases/toggle-webhook-source.md): Toggles a webhook source between enabled and disabled states. Requires `knowledge:upload` permission.
- [Trigger Webhook Source](https://docs.naturalead.ai/api-reference/knowledge-bases/trigger-webhook-source.md): Manually triggers a webhook source to fetch and ingest content immediately, regardless of its polling schedule. Requires `knowledge:upload` permission.
- [Update Knowledge Base](https://docs.naturalead.ai/api-reference/knowledge-bases/update-kb.md): Updates a knowledge base's name or description. Requires `knowledge:upload` permission.
- [Update Webhook Source](https://docs.naturalead.ai/api-reference/knowledge-bases/update-webhook-source.md): Updates a webhook source configuration. Requires `knowledge:upload` permission.
- [Upload Document](https://docs.naturalead.ai/api-reference/knowledge-bases/upload-document.md): Uploads a new document to a knowledge base. The document content is chunked and synced to the vector store for RAG retrieval. Requires `knowledge:upload` permission.
- [Bulk Delete Leads](https://docs.naturalead.ai/api-reference/lead-sync/bulk-delete.md): Delete leads in bulk by their external IDs. Leads that do not exist are counted as `notFound` but do not cause the request to fail.
- [Bulk Sync Leads](https://docs.naturalead.ai/api-reference/lead-sync/bulk-sync.md): Create or update leads in bulk from an external system. Each lead is identified by its external `lead_id`. If a lead with the given `lead_id` already exists, it is updated; otherwise a new lead is created.
- [Advanced Filter Preview](https://docs.naturalead.ai/api-reference/leads/advanced-filter.md): Returns a preview of leads matching the given filter conditions. Useful for campaign targeting previews. Requires `leads:view` permission.
- [Assign AI Agent](https://docs.naturalead.ai/api-reference/leads/assign-agent.md): Assigns or removes an agent configuration from a lead. Pass `null` to unassign. Requires `leads:import` permission.
- [Create Lead](https://docs.naturalead.ai/api-reference/leads/create-lead.md): Creates a new lead for the account. Phone number must be unique within the account. Requires `leads:import` permission.
- [CSV Import Confirm](https://docs.naturalead.ai/api-reference/leads/csv-confirm.md): Imports leads from the previously previewed CSV content using the provided column mapping. Requires `leads:import` permission.
- [CSV Preview](https://docs.naturalead.ai/api-reference/leads/csv-preview.md): Parses CSV content and returns headers and a preview of rows for column mapping before confirming the import. Requires `leads:import` permission.
- [Delete Lead](https://docs.naturalead.ai/api-reference/leads/delete-lead.md): Permanently deletes a lead by ID. Requires `leads:import` permission.
- [Get Filterable Fields](https://docs.naturalead.ai/api-reference/leads/get-filterable-fields.md): Returns the available fields that can be used to filter leads, grouped by core fields, date fields, and custom fields. Requires `leads:view` permission.
- [Import Leads](https://docs.naturalead.ai/api-reference/leads/import-leads.md): Triggers an import of leads from the configured external lead source. Requires `leads:import` permission.
- [List Leads](https://docs.naturalead.ai/api-reference/leads/list-leads.md): Returns all leads for the account. When filter query parameters are provided, returns a paginated response with a total count. Without filters, returns a plain array. Requires `leads:view` permission.
- [Search Leads](https://docs.naturalead.ai/api-reference/leads/search-leads.md): Full-text search across lead name, phone, and email. Requires `leads:view` permission.
- [Update Custom Fields](https://docs.naturalead.ai/api-reference/leads/update-custom-fields.md): Merges custom fields into the lead. Set a field value to `null` to delete that field. Requires `leads:import` permission.
- [Update Lead](https://docs.naturalead.ai/api-reference/leads/update-lead.md): Updates lead fields such as status or assigned agent. Requires `leads:import` permission.
- [Update Lead Tags](https://docs.naturalead.ai/api-reference/leads/update-tags.md): Replaces the tags array on a lead. Requires `leads:import` permission.
- [API Overview](https://docs.naturalead.ai/api-reference/overview.md): Base URL, authentication, pagination, and common patterns
- [Email Inbound](https://docs.naturalead.ai/api-reference/webhooks/email-inbound.md): Receives inbound email events from Resend. Only `email.received` events are processed. The conversation is identified by extracting a conversation ID from the `to` address pattern: `reply+{conversationId}@{domain}`. The full email content is fetched from the Resend API.
- [Lead Inbound Webhook](https://docs.naturalead.ai/api-reference/webhooks/lead-inbound.md): Creates a new lead in the account identified by the webhook token. The token is a per-account secret found in the account settings. If a lead with the same phone number already exists, the existing lead is returned without creating a duplicate.
- [Telegram Inbound](https://docs.naturalead.ai/api-reference/webhooks/telegram-inbound.md): Receives inbound messages from Telegram. This endpoint is registered as the Telegram bot webhook URL. Non-text messages are acknowledged but ignored. The account is resolved by matching the bot token stored in the integration collection.
- [WhatsApp Inbound](https://docs.naturalead.ai/api-reference/webhooks/whatsapp-inbound.md): Receives inbound WhatsApp messages from the Meta Cloud API. The request is validated using the `X-Hub-Signature-256` header (HMAC-SHA256 with `FB_APP_SECRET`). The account is resolved by matching the WABA ID or phone number ID from the payload against the integration collection.
- [Authentication](https://docs.naturalead.ai/authentication.md): API keys, scopes, and permissions
- [Changelog](https://docs.naturalead.ai/changelog.md): API changes, new features, and deprecations
- [Error Reference](https://docs.naturalead.ai/errors.md): All error codes, messages, and recovery strategies
- [Build a Knowledge Base](https://docs.naturalead.ai/guides/build-knowledge-base.md): Complete guide to creating knowledge bases, uploading documents, crawling websites, and setting up webhook sources for auto-updating AI agent context.
- [Configure Your AI Agent](https://docs.naturalead.ai/guides/configure-ai-agent.md): Complete guide to creating, customizing, and deploying an AI agent that qualifies leads through natural conversations.
- [CSV Import Workflow](https://docs.naturalead.ai/guides/csv-import-workflow.md): Import leads from CSV files using the two-step preview-and-confirm workflow.
- [Launch Your First Campaign](https://docs.naturalead.ai/guides/launch-first-campaign.md): End-to-end guide to creating and launching an automated outreach campaign that qualifies leads using AI conversations.
- [Manage API Keys](https://docs.naturalead.ai/guides/manage-api-keys.md): Create, rotate, revoke, and delete API keys for programmatic access to the Naturalead API.
- [Set Up A/B Testing](https://docs.naturalead.ai/guides/set-up-ab-testing.md): Compare multiple AI agent configurations to find the best performer by splitting lead traffic across variants with measurable results.
- [Sync Leads from CRM](https://docs.naturalead.ai/guides/sync-leads-from-crm.md): Integrate your CRM with Naturalead using the lead sync API for idempotent upserts and bulk operations.
- [Webhook Integration](https://docs.naturalead.ai/guides/webhook-integration.md): Set up inbound webhooks for receiving leads and messages from WhatsApp, Telegram, and Email.
- [Introduction](https://docs.naturalead.ai/introduction.md): Naturalead API — automate lead qualification with AI-driven conversations
- [Quickstart](https://docs.naturalead.ai/quickstart.md): Make your first API call in under 5 minutes
- [Rate Limits](https://docs.naturalead.ai/rate-limits.md): Global and per-API rate limiting tiers, headers, and best practices
- [Roles & Permissions](https://docs.naturalead.ai/roles-permissions.md): RBAC roles, permissions matrix, and access control reference
- [cURL Examples](https://docs.naturalead.ai/sdks/curl.md): Command-line examples for the Naturalead API
- [JavaScript / Node.js Examples](https://docs.naturalead.ai/sdks/javascript.md): Node.js code examples using the fetch API
- [SDKs & Code Examples](https://docs.naturalead.ai/sdks/overview.md): Multi-language examples for common API operations
- [Python Examples](https://docs.naturalead.ai/sdks/python.md): Python code examples using the requests library

## OpenAPI Specs

- [knowledge-bases](https://docs.naturalead.ai/openapi/knowledge-bases.yaml)
- [webhooks](https://docs.naturalead.ai/openapi/webhooks.yaml)
- [leads](https://docs.naturalead.ai/openapi/leads.yaml)
- [integrations](https://docs.naturalead.ai/openapi/integrations.yaml)
- [conversations](https://docs.naturalead.ai/openapi/conversations.yaml)
- [campaigns](https://docs.naturalead.ai/openapi/campaigns.yaml)
- [audit-logs](https://docs.naturalead.ai/openapi/audit-logs.yaml)
- [api-keys](https://docs.naturalead.ai/openapi/api-keys.yaml)
- [analytics](https://docs.naturalead.ai/openapi/analytics.yaml)
- [agent-config](https://docs.naturalead.ai/openapi/agent-config.yaml)
- [accounts](https://docs.naturalead.ai/openapi/accounts.yaml)
- [ab-testing](https://docs.naturalead.ai/openapi/ab-testing.yaml)
- [lead-sync](https://docs.naturalead.ai/openapi/lead-sync.yaml)
- [openapi](https://docs.naturalead.ai/api-reference/openapi.json)