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

# Migrate from Legacy to V1

> Move an existing Viggle integration from the Legacy API to V1.

<Warning>
  **Legacy is deprecated.** New integrations must use V1. Keep the old endpoint only while you complete this migration.
</Warning>

## Endpoint mapping

| Legacy                            | V1                               |
| --------------------------------- | -------------------------------- |
| `POST /api/characters/preprocess` | `POST /v1/characters`            |
| `/api/scenes/*`                   | `/v1/motions/*`                  |
| `POST /api/render`                | `POST /v1/renders`               |
| `GET /api/render/{job_id}`        | `GET /v1/renders/{render_id}`    |
| `DELETE /api/render/{job_id}`     | `DELETE /v1/renders/{render_id}` |
| `GET /api/credits`                | `GET /v1/credits`                |
| `/api/extract/static-bin`         | `POST /v1/avatars`               |
| `/api/extract/dynamic-fbx`        | `POST /v1/animations`            |

## Response mapping

| Legacy                 | V1                                                             |
| ---------------------- | -------------------------------------------------------------- |
| `scene_id`             | `motion_id`                                                    |
| `job_id`               | `id` with a `render_` prefix                                   |
| `complete`             | `ready`                                                        |
| `cdn_url`              | `video_url`                                                    |
| `mask_cdn_url`         | `alpha_url`                                                    |
| top-level error fields | nested `error` object with `code`, `message`, and `request_id` |

## Recommended migration sequence

1. Update request paths and form-field names.
2. Store V1 prefixed IDs instead of mixing UUIDs and job IDs.
3. Update polling to check for `ready`, `failed`, and `cancelled`.
4. Update error handling to use `error.code`.
5. Verify transparent-output consumers use `alpha_url`.