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

# Register Competitor

> Register a competitor to monitor (subject to the per-workspace slot limit)

Register a competitor to monitor. Enforces the per-workspace slot limit and returns `409` when no active slot is available. Requires the competitor-monitoring entitlement (`403` when the feature is off).

<Info>
  **Registering starts the competitor's first scan.** That is the point of this endpoint being the only way in: a scan fires when a competitor is added or when [the weekly schedule](/api-reference/get-monitoring-schedule) fires, and at no other time. There is no on-demand trigger.

  The scan starts in the background, so the response comes back immediately with the created competitor. Watch it with [GET /competitor-runs](/api-reference/list-competitor-runs). If the scan fails to start the competitor still exists and the weekly run picks it up.
</Info>

## Body

<ParamField body="company_name" type="string" required>
  Competitor company name.
</ParamField>

<ParamField body="domain" type="string">
  Company domain. Recommended for accurate account matching.
</ParamField>

<ParamField body="linkedin_url" type="string">
  LinkedIn company page URL.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.clustr-ai.com/api/public/competitors \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "company_name": "Globex Inc",
      "domain": "globex.com",
      "linkedin_url": "https://www.linkedin.com/company/globex"
    }'
  ```

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

  requests.post(
      "https://api.clustr-ai.com/api/public/competitors",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      json={
          "company_name": "Globex Inc",
          "domain": "globex.com",
          "linkedin_url": "https://www.linkedin.com/company/globex",
      },
  )
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://api.clustr-ai.com/api/public/competitors", {
    method: "POST",
    headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
    body: JSON.stringify({
      company_name: "Globex Inc",
      domain: "globex.com",
      linkedin_url: "https://www.linkedin.com/company/globex",
    }),
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "data": {
      "competitor": {
        "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "company_name": "Globex Inc",
        "domain": "globex.com",
        "linkedin_url": "https://www.linkedin.com/company/globex",
        "status": "active",
        "created_at": "2026-06-30T09:00:00Z",
        "updated_at": "2026-06-30T09:00:00Z"
      },
      "slot_usage": { "used": 3, "active": 3, "limit": 5 }
    }
  }
  ```

  ```json 409 theme={null}
  {
    "success": false,
    "error": {
      "message": "Competitor monitoring slot limit reached",
      "code": "CONFLICT"
    }
  }
  ```

  ```json 403 theme={null}
  {
    "success": false,
    "error": {
      "message": "Competitor monitoring is not enabled for this tenant",
      "code": "FORBIDDEN"
    }
  }
  ```
</ResponseExample>