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

# Store AI Recommendation

> Record an AI recommendation (bot visit) from your optimized site

Public webhook endpoint for storing AI recommendations from tracking scripts embedded in AI-optimized sites.

**1 AI recommendation = 1 AI bot visiting your site**

When GPTBot, ClaudeBot, or any other AI crawler visits your AI site, that counts as one AI recommendation.

**No authentication required** - this is a public webhook similar to the Stripe webhook.

## How It Works

1. AI-optimized sites include a dynamic tracking script loaded from `/tracking.js`
2. The script detects AI bots via user-agent patterns
3. When an AI bot is detected, the script sends the visit to this endpoint
4. We record it as an AI recommendation in the `ai_recommendations` table

## Supported AI Platforms

| Platform   | Detection Patterns                  |
| ---------- | ----------------------------------- |
| ChatGPT    | gptbot, chatgpt-user, oai-searchbot |
| Claude     | claudebot, claude-web, anthropic    |
| Gemini     | google-extended, gemini             |
| Perplexity | perplexitybot                       |
| Copilot    | bingbot, bingpreview, copilot       |
| DeepSeek   | deepseekbot                         |
| Grok       | xai-bot, grok                       |
| Google AI  | googlebot, googleother              |

## Request Body

<ParamField body="page_url" type="string" required>
  Full URL of the page visited (entity is looked up from the domain
  automatically)
</ParamField>

<ParamField body="page_type" type="string" default="ai_site">
  Type of page: `ai_site` or `boosted_page`
</ParamField>

<ParamField body="page_title" type="string">
  Title of the page
</ParamField>

<ParamField body="user_agent" type="string" required>
  User-Agent header from the request
</ParamField>

<ParamField body="ip_address" type="string">
  IP address of the visitor
</ParamField>

<ParamField body="referrer" type="string">
  Referrer URL if available
</ParamField>

<ParamField body="screen_width" type="integer">
  Screen width in pixels
</ParamField>

<ParamField body="screen_height" type="integer">
  Screen height in pixels
</ParamField>

<ParamField body="language" type="string">
  Browser language (e.g., `en-US`)
</ParamField>

<ParamField body="timezone" type="string">
  Browser timezone (e.g., `America/New_York`)
</ParamField>

## What Gets Stored

The backend automatically adds:

* **created\_at**: Timestamp when the recommendation was recorded (UTC)
* **entity\_id**: Looked up from the page\_url domain
* **ai\_site\_id**: The AI site associated with the entity
* **platform\_id**: Detected from user\_agent (or `unknown` if not recognized)
* **platform\_name**: Human-readable platform name

## Response

<ResponseField name="status" type="string">
  `"success"`, `"ignored"`, or `"error"`
</ResponseField>

<ResponseField name="platform_id" type="string">
  ID of the detected AI platform (e.g., `chatgpt`, `claude`)
</ResponseField>

<ResponseField name="platform_name" type="string">
  Display name of the AI platform (e.g., `ChatGPT`, `Claude`)
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable status message
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://searchcompany-main.up.railway.app/webhooks/ai-recommendation-store \
    -H "Content-Type: application/json" \
    -d '{
      "page_url": "https://alphax-inc.searchcompany.dev/",
      "page_type": "ai_site",
      "page_title": "AlphaX Technologies - AI Profile",
      "user_agent": "Mozilla/5.0 (compatible; GPTBot/1.0; +https://openai.com/gptbot)",
      "ip_address": "52.167.144.0",
      "referrer": "https://chat.openai.com/",
      "screen_width": 1920,
      "screen_height": 1080,
      "language": "en-US",
      "timezone": "America/New_York"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json AI Bot Detected theme={null}
  {
    "status": "success",
    "platform_id": "chatgpt",
    "platform_name": "ChatGPT",
    "message": "AI recommendation from ChatGPT recorded"
  }
  ```

  ```json Unknown Bot (still stored) theme={null}
  {
    "status": "success",
    "platform_id": "unknown",
    "platform_name": "Unknown",
    "message": "AI recommendation from Unknown recorded"
  }
  ```
</ResponseExample>