> ## 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 Settings API

> GET and PUT endpoints for managing workspace-level pipeline settings — Silver field mappings, Gold scoring weights, and behavior flags.

## Endpoints

```
GET  /api/workspace/{workspaceId}/settings/pipeline
PUT  /api/workspace/{workspaceId}/settings/pipeline
```

Read and update workspace-level pipeline configuration, including Silver field mappings, Gold scoring weights, auto-trigger behavior, and preview mode.

***

## Path parameters

| Parameter     | Type   | Required | Description       |
| ------------- | ------ | :------: | ----------------- |
| `workspaceId` | string |    Yes   | Your workspace ID |

***

## GET — Read settings

Returns the current pipeline configuration for the workspace.

### Response

```json theme={null}
{
  "silverMappings": [
    {
      "sourceField": "product_name",
      "targetField": "title",
      "transform": "trim"
    },
    {
      "sourceField": "item_code",
      "targetField": "sku"
    }
  ],
  "goldWeights": {
    "identity": 20,
    "taxonomy": 15,
    "content": 25,
    "media": 20,
    "pricing": 10,
    "attributes": 5,
    "seo": 5
  },
  "autoTriggerSilver": false,
  "autoTriggerGold": false,
  "previewMode": false,
  "updatedAt": "2026-03-15T10:30:00Z",
  "updatedBy": "user_abc"
}
```

***

## PUT — Update settings

Updates pipeline configuration. All fields are optional — only include fields you want to change.

### Request body

```json theme={null}
{
  "silverMappings": [
    {
      "sourceField": "product_name",
      "targetField": "title",
      "transform": "trim"
    },
    {
      "sourceField": "item_code",
      "targetField": "sku"
    },
    {
      "sourceField": "cat",
      "targetField": "categoryPath",
      "transform": "prefix:Apparel > "
    }
  ],
  "goldWeights": {
    "identity": 20,
    "taxonomy": 15,
    "content": 25,
    "media": 20,
    "pricing": 10,
    "attributes": 5,
    "seo": 5
  },
  "autoTriggerSilver": true,
  "autoTriggerGold": false,
  "previewMode": false
}
```

### FieldMapping object

| Field         | Type   | Required | Description                                                                                 |
| ------------- | ------ | :------: | ------------------------------------------------------------------------------------------- |
| `sourceField` | string |    Yes   | Source column name as it appears in the import file                                         |
| `targetField` | string |    Yes   | Target Alana schema field                                                                   |
| `transform`   | string |    No    | Optional transformation: `"trim"`, `"uppercase"`, `"lowercase"`, `"prefix:X"`, `"suffix:X"` |

### ScoringWeights object

| Field        | Type   | Description                                              |
| ------------ | ------ | -------------------------------------------------------- |
| `identity`   | number | Weight for SKU, GTIN, brand (default: 20)                |
| `taxonomy`   | number | Weight for category depth (default: 15)                  |
| `content`    | number | Weight for title, description, bullets (default: 25)     |
| `media`      | number | Weight for images and video (default: 20)                |
| `pricing`    | number | Weight for price, currency, original price (default: 10) |
| `attributes` | number | Weight for category-specific attributes (default: 5)     |
| `seo`        | number | Weight for slug, meta, keywords (default: 5)             |

<Warning>
  All `goldWeights` values must sum to exactly 100. A 422 error is returned if the sum is incorrect.
</Warning>

### Behavior flags

| Field               | Type    | Default | Description                                           |
| ------------------- | ------- | ------- | ----------------------------------------------------- |
| `autoTriggerSilver` | boolean | `false` | Run Silver automatically after every Bronze ingest    |
| `autoTriggerGold`   | boolean | `false` | Run Gold automatically after Silver completes         |
| `previewMode`       | boolean | `false` | Simulate pipeline changes without writing to products |

***

## Examples

### Read current settings

<CodeGroup>
  ```bash curl theme={null}
  curl "https://app.alana.shopping/api/workspace/ws_123/settings/pipeline" \
    -H "Authorization: Bearer sk_live_your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/settings/pipeline`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.ALANA_API_KEY}`,
      },
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  const settings = await response.json();
  console.log('Current Gold weights:', settings.goldWeights);
  console.log('Auto-trigger Silver:', settings.autoTriggerSilver);
  ```

  ```python Python theme={null}
  import requests
  import os

  response = requests.get(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/settings/pipeline",
      headers={"Authorization": f"Bearer {os.environ['ALANA_API_KEY']}"}
  )

  response.raise_for_status()
  settings = response.json()
  print("Silver mappings:", settings["silverMappings"])
  print("Gold weights:", settings["goldWeights"])
  ```
</CodeGroup>

### Update Silver mappings

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT "https://app.alana.shopping/api/workspace/ws_123/settings/pipeline" \
    -H "Authorization: Bearer sk_live_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "silverMappings": [
        { "sourceField": "product_name", "targetField": "title", "transform": "trim" },
        { "sourceField": "item_code", "targetField": "sku" },
        { "sourceField": "vendor", "targetField": "brand" }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/settings/pipeline`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${process.env.ALANA_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        silverMappings: [
          { sourceField: 'product_name', targetField: 'title', transform: 'trim' },
          { sourceField: 'item_code', targetField: 'sku' },
          { sourceField: 'vendor', targetField: 'brand' },
        ],
      }),
    }
  );
  const updated = await response.json();
  console.log('Mappings updated. Modified at:', updated.updatedAt);
  ```

  ```python Python theme={null}
  import requests, os

  response = requests.put(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/settings/pipeline",
      headers={
          "Authorization": f"Bearer {os.environ['ALANA_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "silverMappings": [
              {"sourceField": "product_name", "targetField": "title", "transform": "trim"},
              {"sourceField": "item_code", "targetField": "sku"},
          ]
      }
  )
  updated = response.json()
  print(f"Updated at: {updated['updatedAt']}")
  ```
</CodeGroup>

### Update Gold weights for media-heavy catalog

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT "https://app.alana.shopping/api/workspace/ws_123/settings/pipeline" \
    -H "Authorization: Bearer sk_live_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "goldWeights": {
        "identity": 15,
        "taxonomy": 10,
        "content": 20,
        "media": 35,
        "pricing": 10,
        "attributes": 5,
        "seo": 5
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://app.alana.shopping/api/workspace/${workspaceId}/settings/pipeline`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${process.env.ALANA_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        goldWeights: {
          identity: 15, taxonomy: 10, content: 20,
          media: 35, pricing: 10, attributes: 5, seo: 5,
        },
      }),
    }
  );
  ```

  ```python Python theme={null}
  import requests, os

  response = requests.put(
      f"https://app.alana.shopping/api/workspace/{workspace_id}/settings/pipeline",
      headers={"Authorization": f"Bearer {os.environ['ALANA_API_KEY']}"},
      json={
          "goldWeights": {
              "identity": 15, "taxonomy": 10, "content": 20,
              "media": 35, "pricing": 10, "attributes": 5, "seo": 5,
          }
      }
  )
  print(response.json())
  ```
</CodeGroup>

***

## Error responses

| HTTP status | Code                       | Description                              |
| ----------- | -------------------------- | ---------------------------------------- |
| 403         | `INSUFFICIENT_PERMISSIONS` | API key lacks `settings:write`           |
| 404         | `WORKSPACE_NOT_FOUND`      | Workspace ID not found                   |
| 422         | `WEIGHTS_SUM_INVALID`      | Gold weights do not sum to 100           |
| 422         | `VALIDATION_ERROR`         | Invalid field mapping or transform value |