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

# Upload domains

> Crawl a domain into the project knowledge base

Adds a domain crawl source and queues discovery/indexing. Returns `201 Created`.

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Project API key for this organization and project. Format: `bot_live_…`
</ParamField>

## Path parameters

<ParamField path="organization_id" type="string" required>
  Organization ID. Must match the API key.
</ParamField>

<ParamField path="project_id" type="string" required>
  Project ID. Must match the API key.
</ParamField>

## Body

<ParamField body="domain" type="string" required>
  Domain or site root to crawl (for example `https://example.com`).
</ParamField>

<ParamField body="crawling_strategy" type="string" default="deep_crawl">
  `sitemap` or `deep_crawl`.
</ParamField>

<ParamField body="max_pages" type="integer" default="50">
  Maximum pages to crawl. Range: `1`–`1000`.
</ParamField>

<ParamField body="max_depth" type="integer" default="3">
  Maximum crawl depth. Range: `1`–`10`.
</ParamField>

<ParamField body="include_patterns" type="array">
  Whitelist regex/glob patterns; only matching URLs are crawled.
</ParamField>

<ParamField body="exclude_patterns" type="array">
  Patterns to exclude from the crawl.
</ParamField>

<ParamField body="frequency_days" type="integer" default="30">
  Automatic recrawl interval in days (`1`–`365`).
</ParamField>

<ParamField body="crawler" type="string" default="crawl4ai">
  Crawler engine: `crawl4ai` or `apify`.
</ParamField>

## Response

Success message confirming the domain crawl was queued. `data` is typically `null`.

## Errors

<ResponseField name="401" type="Unauthorized">
  Missing, invalid, or revoked API key.
</ResponseField>

<ResponseField name="403" type="Forbidden">
  API key is not authorized, or link quota exceeded.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/sources/domains" \
    -H "X-API-Key: bot_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "domain": "https://example.com",
      "crawling_strategy": "deep_crawl",
      "max_pages": 50,
      "max_depth": 3,
      "include_patterns": ["/docs/.*"],
      "exclude_patterns": ["/blog/.*"],
      "frequency_days": 30,
      "crawler": "crawl4ai"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://backend.botcadence.com/organizations/${organizationId}/projects/${projectId}/sources/domains`,
    {
      method: "POST",
      headers: {
        "X-API-Key": process.env.BOTCADENCE_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        domain: "https://example.com",
        crawling_strategy: "deep_crawl",
        max_pages: 50,
        max_depth: 3,
        include_patterns: ["/docs/.*"],
        exclude_patterns: ["/blog/.*"],
        frequency_days: 30,
        crawler: "crawl4ai",
      }),
    }
  );
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      f"https://backend.botcadence.com/organizations/{organization_id}/projects/{project_id}/sources/domains",
      headers={
          "X-API-Key": os.environ["BOTCADENCE_API_KEY"],
          "Content-Type": "application/json",
      },
      json={
          "domain": "https://example.com",
          "crawling_strategy": "deep_crawl",
          "max_pages": 50,
          "max_depth": 3,
          "include_patterns": ["/docs/.*"],
          "exclude_patterns": ["/blog/.*"],
          "frequency_days": 30,
          "crawler": "crawl4ai",
      },
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "status": "success",
    "message": "Domain added successfully",
    "data": null,
    "status_code": 201
  }
  ```
</ResponseExample>