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

# API Versioning

> How RawUGC uses date-based API versioning to evolve the API without breaking your integration

## Overview

RawUGC uses **date-based API versioning**, similar to Stripe. When we make breaking changes to the API, we release them under a new version. Your integration stays on its pinned version until you explicitly upgrade -- no surprises.

Non-breaking changes (new optional fields, new endpoints) are available to all versions immediately.

The current latest version is **`2026-03-06`**.

## How version resolution works

Every API request resolves to a specific version using this priority:

1. **`RawUGC-Version` request header** -- per-request override
2. **API key pinned version** -- set when creating the key in the dashboard
3. **Latest version** -- fallback default (`2026-03-06`)

Every response includes a `RawUGC-Version` header confirming which version was used.

## Setting your version

### Per-request header

Override the version for a single request by including the `RawUGC-Version` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://rawugc.com/api/v1/videos/generate \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "RawUGC-Version: 2026-03-06" \
    -H "Content-Type: application/json" \
    -d '{"model": "sora-2-text-to-video", "prompt": "A serene beach at sunset"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://rawugc.com/api/v1/videos/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'RawUGC-Version': '2026-03-06',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'sora-2-text-to-video',
      prompt: 'A serene beach at sunset',
    }),
  });
  ```

  ```python Python theme={null}
  response = requests.post(
      'https://rawugc.com/api/v1/videos/generate',
      headers={
          'Authorization': f'Bearer {API_KEY}',
          'RawUGC-Version': '2026-03-06',
          'Content-Type': 'application/json',
      },
      json={
          'model': 'sora-2-text-to-video',
          'prompt': 'A serene beach at sunset',
      },
  )
  ```
</CodeGroup>

### API key pinning

When you create an API key in [Account Settings](https://rawugc.com/account), you can pin it to a specific version. All requests made with that key will default to the pinned version unless overridden with the `RawUGC-Version` header.

This is the recommended approach for production integrations -- pin your key to the version you've tested against.

### Response header

Every API response includes the `RawUGC-Version` header:

```
RawUGC-Version: 2026-03-06
```

Use this to confirm which version your request resolved to.

## Available versions

| Version      | Summary                                                      |
| ------------ | ------------------------------------------------------------ |
| `2026-03-06` | REST cleanup, unified `/tasks` endpoint, media version chain |
| `2025-11-10` | Initial version -- original API behavior                     |

See the [Changelog](/changelog) for detailed changes in each version.

## Upgrading

To upgrade to a new version:

1. Read the [Changelog](/changelog) for the target version
2. Test your integration by setting the `RawUGC-Version` header to the new version
3. Once confirmed working, update your API key's pinned version in the dashboard

<Tip>
  Always test with the header first before re-pinning your API key. This lets you verify compatibility without affecting your production traffic.
</Tip>

## Backwards compatibility

<Note>
  **Additive changes are not versioned.** New optional response fields, new endpoints, and new optional parameters are shipped to all versions. Only breaking changes (field removals, type changes, behavioral changes) are gated behind a new version.
</Note>