> ## 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 API: Audit, Rewrite, Publish

> Run a multi-stage pipeline that audits pages, rewrites content for AI search visibility, and publishes optimized versions to AXP from one API call.

## One endpoint to rule them all

The Optimize and Deploy API lets you run a multi-stage pipeline that audits your pages, optimizes their content for AI search visibility, and optionally stages or deploys the results to AXP — all from a single API call. One endpoint to bind your audit, optimization, staging, and deployment workflows together.

Each pipeline is asynchronous. You submit URLs, receive tracking tokens, and then poll for status or receive webhook callbacks as each stage completes.

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

***

## How it works

The pipeline chains three Scrunch products together. Each stage is optional — use only what you need.

```mermaid theme={null}
flowchart LR
    A["Submit URLs"] --> B["🔍 Site Audit"]
    B --> C{"optimize?"}
    C -- "true" --> D["✨ Content Optimizer"]
    C -- "false" --> G["✅ Done"]
    D --> E{"stage_axp or<br/>deploy_axp?"}
    E -- "stage_axp" --> H["📥 Stage to AXP"]
    E -- "deploy_axp" --> F["🚀 AXP Deploy"]
    E -- "neither" --> G
    H --> G
    F --> G
```

| Product               | Pipeline stage             | What it does                                                                            | Required?                          |
| --------------------- | -------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------- |
| **Site Audit**        | `audit`                    | Evaluates AI discoverability: robots.txt, bot access, content quality, content delivery | Always runs                        |
| **Content Optimizer** | `optimizing`               | Rewrites page content to improve AI visibility for target prompts and personas          | Set `optimize: true`               |
| **AXP (stage only)**  | `optimizing` → `completed` | Stages optimized content on your AXP site without publishing it live                    | Set `stage_axp: true` + `site_id`  |
| **AXP (deploy live)** | `deploying`                | Publishes optimized content to your AXP site as a new live version                      | Set `deploy_axp: true` + `site_id` |

### Configuration per product

Each product in the pipeline has its own configuration:

* **Site Audit** — runs automatically on each URL, no extra config needed
* **Content Optimizer** — optionally configure `target_prompts`, `target_personas`, `target_sources`, and `override_suggestions` at the batch level or per-URL
* **AXP** — requires a `site_id` (the RegisteredSite ULID). All URLs must belong to the site's domain. Use `stage_axp: true` to stage content for review without going live, or `deploy_axp: true` to publish a new live version. The two flags are mutually exclusive.

***

## Pipeline stages

Every URL you submit moves through these stages in order:

| Stage        | `orchestration_status` | What happens                                                                                                                                                                          |
| ------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Audit**    | `audit`                | Page is fetched and evaluated for AI discoverability (robots.txt, content quality, bot access)                                                                                        |
| **Optimize** | `optimizing`           | Content is analyzed and rewritten to improve AI visibility for your target prompts and personas. If `stage_axp: true`, the optimized content is also staged to AXP during this stage. |
| **Deploy**   | `deploying`            | Optimized content is published to AXP as a new live version                                                                                                                           |
| **Done**     | `completed`            | All stages finished successfully                                                                                                                                                      |
| **Error**    | `failed`               | Pipeline stopped at the failing stage                                                                                                                                                 |

```mermaid theme={null}
stateDiagram-v2
    [*] --> audit
    audit --> optimizing : optimize = true
    audit --> completed : optimize = false
    audit --> failed : error
    optimizing --> deploying : deploy_axp = true
    optimizing --> completed : deploy_axp = false<br/>(includes stage_axp = true)
    optimizing --> failed : error
    deploying --> completed : success
    deploying --> failed : error
```

<Note>
  The optimize and deploy stages only run if you set `optimize: true` and `deploy_axp: true` in the request. With defaults, only the audit stage runs. Set `stage_axp: true` instead of `deploy_axp: true` when you want optimized content staged on AXP for review without going live.
</Note>

***

## When to use it

* You want to audit, optimize, and deploy pages without multiple API calls
* You need batch processing across many URLs
* You want webhook notifications when stages complete
* You're building automated content optimization pipelines

## When not to use it

* You only need audit results — use the **Site Audit API** directly
* You want to query existing visibility data — use the **Query API**
* You need manual control over each optimization — use the Scrunch dashboard

***

## Request patterns

### Simple: list of URLs

Pass `urls` when every URL should use the same optimization 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,
    "deploy_axp": true,
    "site_id": "01JEXAMPLE00000000000000"
  }'
```

### Detailed: per-URL overrides

Pass `requests` when individual URLs need different prompts, personas, or sources:

```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/page-a",
        "target_prompts": ["best budget airlines"],
        "target_personas": [{"name": "Budget Traveler"}]
      },
      {
        "url": "https://example.com/page-b",
        "target_prompts": ["luxury travel options"]
      }
    ],
    "optimize": true,
    "deploy_axp": true,
    "site_id": "01JEXAMPLE00000000000000"
  }'
```

<Warning>
  Provide either `urls` or `requests`, not both. The API will reject requests that include both fields.
</Warning>

### Stage to AXP without going live

Use `stage_axp: true` to run audit + optimize + stage content to AXP without publishing a live version. This is useful when you want to review optimized content in the Scrunch dashboard before manually deploying it.

```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,
    "stage_axp": true,
    "site_id": "01JEXAMPLE00000000000000"
  }'
```

The pipeline ends in `orchestration_status: completed` once content is staged. The response includes an `optimization_run_id`, but `axp_version_id` stays `null` because no live version is published.

| Flags                                           | Pipeline result                                                                            |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `optimize: true`                                | Audit + optimize. Optimization markdown saved on the run, AXP untouched.                   |
| `optimize: true`, `stage_axp: true`, `site_id`  | Audit + optimize + stage to AXP. **No live deploy.** Review and deploy from the dashboard. |
| `optimize: true`, `deploy_axp: true`, `site_id` | Audit + optimize + stage + publish a new live AXP version.                                 |

<Note>
  `stage_axp` and `deploy_axp` are mutually exclusive — passing both returns a `422` validation error. `stage_axp: true` also requires `optimize: true` and a valid `site_id` whose AXP integration is `active`.
</Note>

***

## Tracking progress

Each URL gets its own tracking token. Use it to poll for status:

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

The response includes the current `orchestration_status`, timestamps, and result data as it becomes available.

For real-time updates without polling, configure webhooks to receive callbacks at each stage transition.

<Card title="Set up webhooks" icon="bell" href="/api-reference/webhooks/overview">
  Get notified when audits, optimizations, and deployments complete.
</Card>

***

## Error codes

When a pipeline fails, the response includes a structured error code. Use these to identify what went wrong and where:

| Prefix        | Stage            | Example codes                                                  |
| ------------- | ---------------- | -------------------------------------------------------------- |
| `ORCH-INIT`   | Initialization   | Invalid URL, missing site\_id, domain mismatch, quota exceeded |
| `ORCH-AUDIT`  | Audit            | Fetch failed, timeout, page not found                          |
| `ORCH-OPT`    | Optimization     | No content to optimize, LLM failure, source fetch failed       |
| `ORCH-DEPLOY` | Deployment       | Site not found, AXP publish failed                             |
| `ORCH-HOOK`   | Webhook delivery | Delivery failed, SSRF blocked, timeout                         |

Each error includes a human-readable message and a short `error_hash` you can reference when contacting support.

***

## Relationship to other Scrunch products

The Optimize and Deploy API is a composition layer that chains together three standalone Scrunch products:

```mermaid theme={null}
flowchart TB
    subgraph "Optimize and Deploy API"
        direction LR
        SA["Site Audit API<br/><i>Audit pages for<br/>AI discoverability</i>"]
        CO["Content Optimizer<br/><i>Rewrite content for<br/>AI visibility</i>"]
        AXP["AXP<br/><i>Deploy optimized<br/>content at the edge</i>"]
        SA --> CO --> AXP
    end
    API["POST /orchestration/optimize-and-deploy"] --> SA
    AXP --> DONE["Results + Webhooks"]
```

* **Site Audit** is always the first stage. It runs the same checks as `POST /{brand_id}/page-audits`.
* **Content Optimizer** uses audit results plus your target prompts and personas to generate optimized content.
* **AXP** deploys the optimized content as a new version to your registered site.

Each product can also be used independently outside of this pipeline.

### Dashboard visibility

Everything the pipeline does is fully visible in the Scrunch dashboard — audit results, optimization runs, and AXP deployments all appear in their respective pages exactly as if they had been performed manually. AXP deployments are tracked in the **Version History** with full change tracking, and you can compare original vs. optimized content side by side.

<Card title="Run your first pipeline" icon="box-open" href="/getting-started/quickstart-orchestration">
  Go to the Optimize and Deploy Quickstart
</Card>