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

# Version Pinning

> How Reducto model versioning works and how to pin versions

Reducto continuously improves the models powering document processing. This page explains how versioning works and how to control which version you use. For the current status of each model version, see [Model Versions](/reference/model-versions).

## How Versioning Works

Each model version progresses through four stages:

1. **Alpha**: New version available for opt-in testing via the `alpha` config
2. **Default**: Automatically used for all requests
3. **Deprecated**: Old default, still accessible via `alpha` config
4. **Removed**: No longer available

Requesting an unknown or removed version returns an error listing the available versions.

## Rollout Process

New model versions follow a 4-week rollout window:

1. **Weeks 1-2 (Alpha)**: The new version is available for opt-in testing. You can pin to the new version via the `alpha` config to evaluate it against your workloads before it becomes the default.
2. **Week 3 (Default)**: The new version becomes the default for all requests. The previous default is demoted to deprecated status.
3. **Weeks 3-4 (Deprecated)**: The previous default remains accessible via version pinning for 2 weeks after being replaced. Use this window to migrate any workflows that depend on the old version's behavior.

This gives you a guaranteed 4-week window, 2 weeks before and 2 weeks after a version becomes the default, to test and transition between versions.

<Note>
  Reducto is deployed as a monolith, so fully frozen snapshots of previous versions are not available outside of on-prem/VPC deployments. Version pinning during the rollout window is the supported mechanism for managing behavioral changes.
</Note>

## Pinning a Version

To pin a specific version, pass it in your request's `settings.alpha` config:

<CodeGroup>
  ```python Python theme={null}
  # Layout version pinning (parse)
  result = client.parse.run(
      input="https://example.com/document.pdf",
      settings={
          "alpha": {
              "layout_model": "v2"
          }
      }
  )

  # Extract version pinning (requires citations enabled)
  result = client.extract.run(
      input="https://example.com/document.pdf",
      instructions={"schema": {...}},
      settings={
          "citations": {"enabled": True},
          "alpha": {
              "extract_model": "v2"
          }
      }
  )
  ```

  ```javascript Node.js theme={null}
  // Layout version pinning (parse)
  const result = await client.parse.run({
    input: 'https://example.com/document.pdf',
    settings: {
      alpha: {
        layout_model: 'v2'
      }
    }
  });

  // Extract version pinning (requires citations enabled)
  const extractResult = await client.extract.run({
    input: 'https://example.com/document.pdf',
    instructions: { schema: {...} },
    settings: {
      citations: { enabled: true },
      alpha: {
        extract_model: 'v2'
      }
    }
  });
  ```

  ```bash cURL theme={null}
  # Layout version pinning (parse)
  curl -X POST https://platform.reducto.ai/parse \
    -H "Authorization: Bearer $REDUCTO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": "https://example.com/document.pdf",
      "settings": {
        "alpha": {
          "layout_model": "v2"
        }
      }
    }'

  # Extract version pinning (requires citations enabled)
  curl -X POST https://platform.reducto.ai/extract \
    -H "Authorization: Bearer $REDUCTO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": "https://example.com/document.pdf",
      "instructions": {"schema": {...}},
      "settings": {
        "citations": {"enabled": true},
        "alpha": {
          "extract_model": "v2"
        }
      }
    }'
  ```
</CodeGroup>

<Note>
  Model versioning only changes processing behavior. It does not break the API contract. If a pinned version is unknown or has been removed, the request returns an error listing the available versions.
</Note>