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

# Optimize and Deploy Pipeline Lifecycle Guide

> Walk through every stage of the Optimize and Deploy pipeline — submitting URLs, tracking progress, polling status, handling errors, and processing results.

<Warning>
  The Optimize and Deploy API is currently in **early access**. Contact your Customer Success representative to get access enabled for your organization.
</Warning>

## Overview

This guide walks through the complete lifecycle of an Optimize and Deploy pipeline — from submitting URLs to handling results. By the end, you'll understand how to track progress, handle errors, and integrate the pipeline into your workflow.

### Pipeline flow

Each URL cascades through up to three stages. At every stage transition, a webhook fires so you can react in real time. Stages are optional — the pipeline exits early when the last enabled stage completes.

Regardless of which stage is the final one, you always receive:

1. The **stage-specific webhook** for the last stage that ran (e.g., `audit.completed` if audit-only)
2. The **`pipeline.completed`** webhook once all URLs in the batch have finished

```mermaid theme={null}
sequenceDiagram
    participant You
    participant API as Optimize & Deploy API
    participant Audit as 🔍 Site Audit
    participant Opt as ✨ Content Optimizer
    participant AXP as 🚀 AXP Deploy
    participant Hook as 🔔 Your Webhook

    You->>API: POST /orchestration/optimize-and-deploy/{brand_id}
    API-->>You: tokens[] + pipeline_id

    rect rgb(240, 248, 255)
    Note over Audit: Stage 1 — Always runs
    API->>Audit: Run audit for each URL
    Audit-->>API: Audit scores + checks
    API->>Hook: audit.completed (score, issues)
    Note over Hook: If optimize=false → pipeline ends here
    end

    alt optimize = true
    rect rgb(240, 255, 240)
    Note over Opt: Stage 2 — Only if optimize=true
    API->>Opt: Optimize content with prompts & personas
    Opt-->>API: Optimized title, description, content
    opt stage_axp = true
        API->>AXP: Stage optimized content (no live deploy)
    end
    API->>Hook: optimization.completed (optimization_run_id)
    Note over Hook: If neither deploy_axp nor stage_axp → pipeline ends here<br/>If stage_axp=true → status="staged", pipeline ends here
    end
    end

    alt deploy_axp = true
    rect rgb(255, 248, 240)
    Note over AXP: Stage 3 — Only if deploy_axp=true
    API->>AXP: Deploy optimized content
    AXP-->>API: AXP version ID
    API->>Hook: deployment.completed (axp_version_id)
    end
    end

    rect rgb(245, 245, 245)
    Note over Hook: Always fires when all URLs finish
    API->>Hook: pipeline.completed (summary counts)
    end

    Note over You,API: Poll anytime with GET .../token
    You->>API: GET .../token
    API-->>You: Current status + results
```

### Webhook events per configuration

| Configuration                                  | Webhooks fired (per URL)                                              | Final webhook (per batch) |
| ---------------------------------------------- | --------------------------------------------------------------------- | ------------------------- |
| Audit only (default)                           | `audit.completed`                                                     | —                         |
| Audit + optimize                               | `audit.completed` → `optimization.completed`                          | —                         |
| Audit + optimize + stage (`stage_axp: true`)   | `audit.completed` → `optimization.completed` (`status: "staged"`)     | —                         |
| Audit + optimize + deploy (`deploy_axp: true`) | `audit.completed` → `optimization.completed` → `deployment.completed` | `pipeline.completed`      |

`pipeline.completed` fires only for `deploy_axp: true` batches — other configurations end with the last per-URL webhook.

### What gets configured at each stage

| Stage                 | Triggered by                                      | Webhook event                                    | Key data returned                                |
| --------------------- | ------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------ |
| **Site Audit**        | Always runs                                       | `audit.completed`                                | `score`, `issues`, `recommendations`             |
| **Content Optimizer** | `optimize: true`                                  | `optimization.completed`                         | `optimization_run_id`, `title`, `description`    |
| **AXP Stage**         | `stage_axp: true` + `site_id`                     | `optimization.completed` with `status: "staged"` | `optimization_run_id`, `title`, `description`    |
| **AXP Deploy**        | `deploy_axp: true` + `site_id`                    | `deployment.completed`                           | `axp_version_id`, `site_id`                      |
| **Pipeline done**     | All URLs finish (`deploy_axp: true` batches only) | `pipeline.completed`                             | `completed_count`, `failed_count`, `total_count` |

***

## 1. Submit a pipeline

### Simple mode: shared configuration

```bash theme={null}
curl -X POST "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/1234" \
  -H "Authorization: Bearer $SCRUNCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/page-a", "https://example.com/page-b"],
    "optimize": true,
    "target_prompts": ["best budget airlines", "cheap flights comparison"],
    "target_personas": [{"name": "Budget Traveler", "description": "Price-sensitive consumer"}]
  }'
```

### Stage-only mode: review before going live

Set `stage_axp: true` to run the full audit and optimize pipeline and push the optimized content to AXP as a staged change — without deploying a live version. Reviewers can then approve and publish from the Scrunch dashboard.

```bash theme={null}
curl -X POST "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/1234" \
  -H "Authorization: Bearer $SCRUNCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/page-a"],
    "optimize": true,
    "stage_axp": true,
    "site_id": "01JEXAMPLE00000000000000"
  }'
```

The pipeline finishes at `orchestration_status: completed` after staging, and the final per-URL webhook is `optimization.completed` with `status: "staged"`. `stage_axp` and `deploy_axp` are mutually exclusive.

### Detailed mode: per-URL overrides

```bash theme={null}
curl -X POST "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/1234" \
  -H "Authorization: Bearer $SCRUNCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "url": "https://example.com/budget-page",
        "target_prompts": ["best budget airlines"],
        "target_personas": [{"name": "Budget Traveler"}]
      },
      {
        "url": "https://example.com/luxury-page",
        "target_prompts": ["luxury travel options"],
        "override_suggestions": true
      }
    ],
    "optimize": true,
    "deploy_axp": true,
    "site_id": "01JEXAMPLE00000000000000"
  }'
```

### What gets returned

```json theme={null}
{
  "pipeline_id": "01JPIPELINE000000000000",
  "tokens": [
    {"token": "01JABC001", "url": "https://example.com/budget-page", "status": "pending", "orchestration_status": "audit"},
    {"token": "01JABC002", "url": "https://example.com/luxury-page", "status": "pending", "orchestration_status": "audit"}
  ],
  "status": "pending"
}
```

`pipeline_id` is only set when `deploy_axp` is true — it groups all URLs into a single AXP deployment batch.

***

## 2. Track progress

### Option A: Polling

```bash theme={null}
curl "https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/1234/01JABC001" \
  -H "Authorization: Bearer $SCRUNCH_API_KEY"
```

| `orchestration_status` | Meaning                               |
| ---------------------- | ------------------------------------- |
| `audit`                | Page audit running                    |
| `optimizing`           | Content optimization running          |
| `deploying`            | AXP deployment running                |
| `completed`            | All stages finished successfully      |
| `failed`               | Pipeline stopped at the failing stage |

<Tip>
  Poll every 5–10 seconds. Audits typically complete in under 30 seconds; optimization may take 1–2 minutes depending on page complexity.
</Tip>

### Option B: Webhooks

Configure a webhook URL for your brand and receive HTTP callbacks at each stage transition.

<Card title="Webhook setup guide" icon="bell" href="/api-reference/webhooks/overview">
  Configure webhooks and verify signatures.
</Card>

***

## 3. Handle stage transitions

### Audit → Optimizing

```json theme={null}
{
  "orchestration_status": "optimizing",
  "result": {
    "access_controls_score": 100,
    "content_delivery_score": 90,
    "content_quality_score": 85
  }
}
```

### Optimizing → Deploying

```json theme={null}
{
  "orchestration_status": "deploying",
  "optimization_run_id": "01JOPTRUN0000000000000"
}
```

### Deploying → Completed

```json theme={null}
{
  "orchestration_status": "completed",
  "axp_version_id": 42
}
```

***

## 4. Handle errors

| Prefix          | Stage                |
| --------------- | -------------------- |
| `ORCH-INIT-*`   | Request validation   |
| `ORCH-AUDIT-*`  | Page audit           |
| `ORCH-OPT-*`    | Content optimization |
| `ORCH-DEPLOY-*` | AXP deployment       |
| `ORCH-HOOK-*`   | Webhook delivery     |

| Code              | Cause                                        | Fix                                                        |
| ----------------- | -------------------------------------------- | ---------------------------------------------------------- |
| `ORCH-INIT-004`   | URL domain doesn't match the registered site | Ensure all URLs belong to the site's domain                |
| `ORCH-AUDIT-002`  | Page fetch failed (404, timeout, blocked)    | Verify the URL is accessible and not blocked by robots.txt |
| `ORCH-OPT-002`    | No content available to optimize             | Ensure the page has substantial text content               |
| `ORCH-DEPLOY-002` | Site not found for the given site\_id        | Verify the site\_id is correct and belongs to your brand   |

***

## 5. Full working example

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

API_KEY = "your-api-key"
BRAND_ID = 1234
SITE_ID = "01JEXAMPLE00000000000000"
BASE = f"https://api.scrunchai.com/v2/orchestration/optimize-and-deploy/{BRAND_ID}"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

urls = [
    "https://example.com/page-a",
    "https://example.com/page-b",
    "https://example.com/page-c",
]

resp = requests.post(BASE, headers=HEADERS, json={
    "urls": urls,
    "optimize": True,
    "deploy_axp": True,
    "site_id": SITE_ID,
}, timeout=30)
resp.raise_for_status()
pipeline = resp.json()

print(f"Pipeline started: {pipeline.get('pipeline_id')}")
pending = {r["token"]: r["url"] for r in pipeline["tokens"]}
while pending:
    for token in list(pending.keys()):
        status = requests.get(f"{BASE}/{token}", headers=HEADERS, timeout=30).json()
        stage = status["orchestration_status"]
        if stage in ("completed", "failed"):
            result = "OK" if stage == "completed" else "FAILED"
            print(f"  [{result}] {pending[token]}")
            if status.get("axp_version_id"):
                print(f"    AXP version: {status['axp_version_id']}")
            del pending[token]
    if pending:
        time.sleep(5)
```

***

## 6. Viewing results in the Scrunch dashboard

Everything the pipeline does is visible in the Scrunch dashboard — exactly as if each step had been performed manually.

* **Site Audit results** — **Your Brand → Site Audits**
* **Content Optimizer results** — **Your Brand → Optimizer → History**
* **AXP deployments** — **Your Brand → AXP → \[site] → Version History**

<Tip>
  To roll back a deployment, use the **Redeploy** option on any previous version in the AXP version history.
</Tip>

***

## Best practices

* **Use webhooks for production** — more efficient and lower latency than polling
* **Handle partial failures** — in a batch, some URLs may succeed while others fail; check each token individually
* **Set `override_suggestions: true` carefully** — only your explicitly provided prompts and personas are used
* **Start with audit-only** — validate URLs and check audit scores before committing to optimization and deployment

<CardGroup cols={2}>
  <Card title="Orchestration API reference" icon="sitemap" href="/api-reference/optimize-deploy">
    Endpoint details, error codes, and schema reference.
  </Card>

  <Card title="Webhooks reference" icon="bell" href="/api-reference/webhooks/overview">
    Event types, payload schemas, and signature verification.
  </Card>
</CardGroup>