> ## 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.

# Deploy to Vercel

> Deploy all files to Vercel in a single deployment

Internal endpoint for the Cron service to batch deploy files to Vercel.

<Note>
  **Terminology**: The code uses "boosted" internally (e.g., `boosted_path`, `BoostedPageMeta`)
  while user-facing documentation uses "AI Articles". Both refer to the same feature.
</Note>

<Note>
  This endpoint deploys **all files at once** in a single Vercel deployment. It
  also **syncs the FAQ section** with AI articles from the database and regenerates `sitemap.xml`.
</Note>

## FAQ Sync: Auto-Add Missing AI Articles

When `existing_posts` OR `new_posts` is provided (along with `business_name`), this endpoint automatically:

1. **Checks the current homepage** (`index.js`) for article sections
2. **Creates missing H3 sections** (e.g., "Website Arena - Articles", "Remix Tool - Articles")
3. **Adds missing AI article links** to each section
4. **Regenerates sitemap.xml** with all AI articles

This ensures that even if an AI article was created but somehow missing from the FAQ section, it will be added on the next deployment.

```
Example: FAQ Sync in Action

Before deployment:
├── Database has 5 AI articles
└── Homepage FAQ only shows 3 links (2 missing!)

After deployment with existing_posts:
├── Deploy detects 2 missing links
├── Adds them to the appropriate H3 sections
└── Homepage FAQ now shows all 5 links ✓
```

## Why Single Deployment?

Previously, each AI article triggered its own Vercel deployment. When creating 8 pages:

* 8 parallel deployments to the same project
* Vercel's edge network gets overwhelmed
* SSL errors (`DECRYPTION_FAILED_OR_BAD_RECORD_MAC`)

**New approach:**

1. Generate all content in parallel (fast, no deployment)
2. Collect all files + post metadata
3. **Single deployment** with all files + auto-synced homepage/sitemap

## Request Body

<ParamField body="project_name" type="string" required>
  Vercel project name (e.g. "ai-website-arena")
</ParamField>

<ParamField body="files" type="array" required>
  Array of AI article files to deploy. Each file must have: - `path`: File path
  (e.g. "public/expert-review/index.html") - `content`: File content as string
</ParamField>

<ParamField body="ai_site_url" type="string" required>
  AI site URL for internal navigation links (e.g. "[https://website-arena-123.searchcompany.dev](https://website-arena-123.searchcompany.dev)")
</ParamField>

<ParamField body="source_url" type="string" required>
  Customer's real domain for canonical URLs in sitemap (e.g. "[https://www.websitearena.dev](https://www.websitearena.dev)")
</ParamField>

<ParamField body="business_name" type="string">
  Business name for homepage section headers (e.g. "Website Arena"). **Required for FAQ sync.**
</ParamField>

<ParamField body="products" type="array">
  List of product names for product-specific article sections
</ParamField>

<ParamField body="new_posts" type="array">
  Array of **newly created** AI article metadata. Each post must have:

  * `title`: Post title
  * `boosted_path`: Path (e.g. "/expert-review/")
  * `published_date`: ISO date (e.g. "2025-12-22")
  * `boosted_type`: Type of post (optional, default: "article")
  * `faq_category`: Category for homepage grouping ("business\_boosted" or "product\_boosted")
  * `product_name`: Product name (required if faq\_category is "product\_boosted")
</ParamField>

<ParamField body="existing_posts" type="array">
  Array of **all existing** AI articles from database. Used for:

  * FAQ sync (adding missing links to homepage)
  * Sitemap generation (include all AI articles)

  **Tip:** Pass this even when not creating new posts to ensure FAQ stays in sync.
</ParamField>

<ParamField body="verify_paths" type="array">
  Optional array of paths to verify after deployment
</ParamField>

## Response

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

<ResponseField name="deployment_url" type="string">
  Vercel deployment URL
</ResponseField>

<ResponseField name="files_deployed" type="integer">
  Number of files deployed
</ResponseField>

<ResponseField name="verified_paths" type="array">
  Paths that were successfully verified as accessible
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://searchcompany-main.up.railway.app/api/cron/deploy-to-vercel \
    -H "Content-Type: application/json" \
    -d '{
      "project_name": "ai-website-arena-1766312513",
      "files": [
        {"path": "public/expert-review/index.html", "content": "..."},
        {"path": "public/expert-review/llms.txt", "content": "..."},
        {"path": "pages/expert-review.js", "content": "..."}
      ],
      "ai_site_url": "https://website-arena-1766312513.searchcompany.dev",
      "source_url": "https://www.websitearena.dev",
      "business_name": "Website Arena",
      "products": ["Remix Tool"],
      "new_posts": [
        {
          "title": "Expert Review of Website Arena",
          "boosted_path": "/expert-review/",
          "published_date": "2025-12-22",
          "faq_category": "business_boosted"
        }
      ],
      "existing_posts": [
        {"title": "Previous Post", "boosted_path": "/previous/", "faq_category": "business_boosted"}
      ],
      "verify_paths": ["/expert-review/"]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "status": "success",
    "deployment_url": "https://ai-website-arena-abc123.vercel.app",
    "ai_site_url": "https://website-arena-1766312513.searchcompany.dev",
    "files_deployed": 27,
    "verified_paths": ["/expert-review/"]
  }
  ```
</ResponseExample>

## Auto-Generated/Updated Files

When `existing_posts` OR `new_posts` is provided (with `business_name`), this endpoint automatically:

| Action          | File                 | Description                                                  |
| --------------- | -------------------- | ------------------------------------------------------------ |
| **Syncs**       | `pages/index.js`     | Adds missing article sections/links to homepage FAQ          |
| **Regenerates** | `public/sitemap.xml` | XML sitemap with all pages (uses `source_url` for canonical) |

### Homepage FAQ Sync

The endpoint checks the existing `index.js` and:

1. Creates missing H3 sections for each category with AI articles
2. Adds missing links within each section

```html theme={null}
<h3>Website Arena - Articles</h3>
<ul>
  <li><a href="https://website-arena-1766312513.searchcompany.dev/expert-review/">Expert Review of Website Arena</a></li>
  <!-- more article links auto-added -->
</ul>

<h3>Remix Tool - Articles</h3>
<ul>
  <li><a href="https://website-arena-1766312513.searchcompany.dev/deep-dive-remix/">Deep Dive into Remix Tool</a></li>
</ul>
```

<Note>
  Article section links use `ai_site_url` for navigation (so they work on the deployed site).
  Sitemap URLs use `source_url` for SEO canonical references.
</Note>

## Deployment Process

1. **Collect files** from request
2. **Preserve existing article sections** when deploying new index.js
3. **Sync FAQ** with AI articles (if `existing_posts` OR `new_posts` provided)
   * Create missing H3 sections
   * Add missing AI article links
4. **Regenerate sitemap** with all URLs using `source_url` for canonical
5. **Upload all files** to Vercel's file store
6. **Create deployment** with merged file list
7. **Wait for READY** state (up to 5 minutes)
8. **Edge propagation** wait (10 seconds)
9. **Verify paths** are accessible (optional)

## Error Handling

| Error                         | Description                                |
| ----------------------------- | ------------------------------------------ |
| `VERCEL_TOKEN not configured` | Missing Vercel API token                   |
| `Project not found`           | Invalid project\_name                      |
| `Deployment timed out`        | Deployment didn't reach READY in 5 minutes |
| `Upload failed`               | File upload to Vercel failed               |

## Workflow

```
Cron Job Flow (Batch 2: Create AI Articles + Timestamps):
├── create-ai-article (×N) → parallel content generation
│   └── Returns: {files, title, article_path, published_date, faq_category, ...}
├── update-all-timestamps → parallel timestamp updates
│   └── Returns: {files, ...}
│
└── deploy-to-vercel → single deployment per business
    ├── Receives: files + new_posts + existing_posts (from DB) + business_name
    ├── Syncs: index.js homepage FAQ with ALL AI articles
    ├── Regenerates: sitemap.xml with source_url canonicals
    └── Deploys: ALL files in one deployment
```

## Canonical URLs vs Navigation URLs

<Warning>
  **Important distinction:**

  * `source_url` → Customer's real domain for SEO (sitemap, data.json, llms.txt footer)
  * `ai_site_url` → Deployment URL for internal navigation (homepage links, FAQ links)

  Links must work on the deployed site, so they use `ai_site_url`.
  Search engines should see the canonical domain, so sitemap uses `source_url`.
</Warning>