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

# Migration guide

> Move from the legacy endpoints to the new versioned base URL

## Why migrate?

Aurigin now exposes versioned endpoints at `https://api.aurigin.ai/{version}`. Moving from the legacy `https://aurigin.ai/api-ext` base URL to the new versioned endpoints gives you:

* A stable base URL shared by every version (`https://api.aurigin.ai`)
* A richer prediction payload with global + per-segment insights
* New endpoints for larger uploads and storage management
* Backwards-compatible timelines so you can cut over safely

This guide compares responses, highlights breaking changes, and shows how to update clients.

## Base URL changes

| Legacy                       | New versioned                         |
| ---------------------------- | ------------------------------------- |
| `https://aurigin.ai/api-ext` | `https://api.aurigin.ai/v1` (current) |

Update any hard-coded URLs and SDK configuration to point at the new base URL plus the desired version.

```diff theme={null}
- const BASE_URL = "https://aurigin.ai/api-ext";
+ const BASE_URL = "https://api.aurigin.ai/v1";

- await fetch(`${BASE_URL}/predict`, …)
+ await fetch(`${BASE_URL}/predict`, …)
```

## Response payload differences

### v0 (chunk arrays)

```json theme={null}
{
  "predictions": ["fake", "fake", "real"],
  "global_probability": [0.9912, 0.9889, 0.9824],
  "error": [null, null, null],
  "model": "apollo-4-2026-01-16",
  "processing_time": 1.35,
  "audio_duration": 69.91
}
```

### v1 (rich objects)

```json theme={null}
{
  "prediction_id": "pred_abc123def456",
  "global": {
    "confidence": 0.9921,
    "result": "spoofed",
    "reason": null
  },
  "segments": [
    {
      "index": 0,
      "start": 0.0,
      "end": 5.0,
      "confidence": 0.9898,
      "result": "spoofed"
    }
  ],
  "model": "apollo-4-5-2026-03-26",
  "processing_time": 1.23,
  "audio_duration": 10.0,
  "warnings": []
}
```

**Key differences**

* v0 returns parallel arrays (`predictions`, `global_probability`, `error`).
* v1 wraps results into structured objects: a `global` verdict and a `segments` array with timing metadata.
* v1 responses always include a `prediction_id` you can use for auditing or async lookups.
* The `warnings` array replaces per-chunk error strings.

## Request changes

* **Upload formats**: both versions accept `multipart/form-data` uploads. v1 also accepts a JSON payload with a `presigned_url`.
* **Device + model metadata**: v1 adds optional `device` and `model` fields for tagging requests. `model` accepts `apollo-4-5-2026-03-26` (latest) or `apollo-4-2026-01-16`, and can be omitted to use the latest available model.

## Endpoint mapping

| v0 endpoint                | v1 replacement             | Notes                                                                     |
| -------------------------- | -------------------------- | ------------------------------------------------------------------------- |
| `POST /predict`            | `POST /predict`            | Same behaviour with richer response fields.                               |
| `POST /file` / `GET /file` | `POST /file` / `GET /file` | Storage workflows remain, but now surfaced in the `Prediction` tag group. |

> Async uploads via pre-signed URLs are now handled outside of the public v1 spec. Reach out to support if you depend on the old async flow.

## Migration checklist

1. **Switch base URL** to `https://api.aurigin.ai/v1`.
2. **Update response parsing**:
   * Map `predictions[n]` -> `segments[n].result`
   * Map `global_probability[n]` -> `segments[n].confidence`
   * Use `global.confidence` / `global.result` for overall status.
3. **Handle `prediction_id`** for logging or follow-up status checks.
4. **Retire deprecated fields**:
   * `error[]` is replaced by `warnings[]`.
   * `global_probability[]` is no longer returned.

## Rollout tips

* **Dual-write strategy**: call both v0 and v1 in parallel, compare outputs, then flip traffic once results align.
* **Monitor warnings**: v1 warnings highlight partial failures that used to surface as `error[i]` entries.
* **SDK regeneration**: regenerate clients from the v1 OpenAPI spec to pick up the new response schema automatically.

Still need help? Reach out at [support@aurigin.ai](mailto:support@aurigin.ai).