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

# Pipeline API Overview

> REST endpoints for triggering Bronze → Silver → Gold pipeline stages and managing workspace pipeline settings.

## Overview

The **Pipeline API** provides programmatic control over the Bronze, Silver, and Gold processing stages for product data. Use these endpoints to trigger normalization and scoring in bulk, monitor job progress, and configure pipeline behavior.

***

## Architecture

The pipeline follows a three-stage medallion architecture (see [Data Pipeline](/concepts/data-pipeline) for the full conceptual overview):

```
Bronze (ingest) → Silver (normalize) → Gold (score) → Repository
```

Each stage is independently triggerable. Bronze is automatic on import; Silver and Gold require explicit triggering unless auto-trigger is configured.

### ADR reference

Pipeline architecture is documented in **ADR-015** (Bronze/Silver/Gold Medallion Architecture), available in the internal architecture decision record log.

***

## Base URL

All Pipeline API endpoints are scoped to a workspace and catalog:

```
https://app.alana.shopping/api/workspace/{workspaceId}/catalogs/{catalogId}/
```

For pipeline settings (workspace-level):

```
https://app.alana.shopping/api/workspace/{workspaceId}/settings/pipeline
```

***

## Authentication

All endpoints require a Bearer token:

```
Authorization: Bearer sk_live_your_api_key_here
```

API keys are scoped to a workspace. The key must have `catalogs:write` permission to trigger pipeline stages, and `settings:write` to modify pipeline settings.

See [API Keys](/api-reference/api-keys/list-keys) for details on creating and managing keys.

***

## Rate limits

| Tier       | Requests per minute |
| ---------- | ------------------- |
| Free       | 20                  |
| Pro        | 120                 |
| Business   | 600                 |
| Enterprise | Custom              |

Pipeline batch operations (Silver and Gold) consume additional quota based on the number of products processed:

* Each product processed via Silver = 1 request unit
* Each product processed via Gold = 2 request units

***

## Endpoints

<CardGroup cols={2}>
  <Card title="Batch Silver" icon="filter" href="/api-reference/pipeline/batch-silver">
    `POST /batch/silver` — normalize a selection or entire catalog
  </Card>

  <Card title="Batch Gold" icon="star" href="/api-reference/pipeline/batch-gold">
    `POST /batch/gold` — score a selection or entire catalog
  </Card>

  <Card title="Pipeline Settings" icon="settings" href="/api-reference/pipeline/settings">
    `GET/PUT /settings/pipeline` — configure mappings and weights
  </Card>
</CardGroup>

***

## Score function

The Gold score is a weighted sum across 7 stages:

```
score = Σ (stage_weight × stage_score) / 100
```

Where `stage_score` for each stage is 0–100 based on field completeness and quality.

Default weights:

| Stage      | Weight |
| ---------- | ------ |
| Identity   | 20     |
| Taxonomy   | 15     |
| Content    | 25     |
| Media      | 20     |
| Pricing    | 10     |
| Attributes | 5      |
| SEO        | 5      |

Weights are customizable via [Pipeline Settings](/api-reference/pipeline/settings).

***

## Error responses

All pipeline endpoints return standard error shapes:

```json theme={null}
{
  "error": {
    "code": "CATALOG_NOT_FOUND",
    "message": "Catalog cat_xyz does not exist in this workspace",
    "details": null
  }
}
```

Common error codes:

| Code                       | HTTP status | Description                                         |
| -------------------------- | ----------- | --------------------------------------------------- |
| `CATALOG_NOT_FOUND`        | 404         | Catalog ID not found in workspace                   |
| `INSUFFICIENT_PERMISSIONS` | 403         | API key lacks required permission                   |
| `RATE_LIMIT_EXCEEDED`      | 429         | Too many requests — back off and retry              |
| `JOB_ALREADY_RUNNING`      | 409         | A batch job is already in progress for this catalog |
| `VALIDATION_ERROR`         | 422         | Request body failed validation                      |