# Migrating from v1 to v2

v2 is the current version of the Layer REST API and the default across these docs. v1 remains live under its existing `/v1` prefix. A sunset date for v1 has not been announced yet; v1 will be deprecated as a whole (all endpoints at once), not endpoint-by-endpoint.

**Most endpoints are drop-in.** Of the 43 v1 operations, 38 have identical request and response schemas in v2 — for those, migration is changing the `/v1` prefix to `/v2`, and nothing else. Only the endpoints listed on this page actually changed.

## What changed, at a glance

| v1                                                 | v2                                                    | What changed                                           |
| -------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------ |
| POST /v1/workspaces/{id}/inferences                | POST /v2/workspaces/{id}/inferences                   | New request body (base models + reference sets)        |
| POST /v1/workspaces/{id}/inferences/estimate       | POST /v2/workspaces/{id}/inferences/estimate          | Same request change; response adds auto\_picked        |
| GET /v1/workspaces/{id}/inferences/{inference\_id} | GET /v2/workspaces/{id}/inferences/{inference\_id}    | Response gains base-model / reference-set fields       |
| GET /v1/workspaces/{id}/models                     | GET /v2/workspaces/{id}/base-models                   | Renamed resource; response envelope and fields changed |
| GET /v1/workspaces/{id}/models/{model\_id}         | GET /v2/workspaces/{id}/base-models/{base\_model\_id} | Renamed resource; response unwrapped, fields changed   |

Everything else — Workspaces, Projects, Members, Groups, Files, Scoring, Training, Workflows, Usage — is unchanged.

## 1\. Running inferences: `model_id` → `base_model_id` \+ `reference_sets`

The inference request body moved from a single trained model to a **base model + optional reference sets**.

**v1**

```json
{
  "model_id": "mdl_…",
  "prompt": "…",
  "weight": 0.8
}
```

**v2**

```json
{
  "base_model_id": "bfl-flux-1-dev",
  "prompt": "…",
  "reference_sets": [{ "set_id": "rs_…" }]
}
```

* `model_id` (required) and `weight` were **removed** from the request.
* `base_model_id` was **added**. `reference_sets` is a new optional array, each entry a `set_id` with an optional per-set `weight`. `modality` is optional — it only disambiguates reference-set translation when no `base_model_id` is given.
* Responses gain `base_model_id`, `reference_set_contributions`, `reference_sets_degraded`, and `reference_sets_warning`. The `…/inferences/estimate` response additionally gains `auto_picked` (whether the base model was chosen automatically).

The same change applies to both `POST …/inferences` and `POST …/inferences/estimate`.

## 2\. Inference detail responses: new fields only

`GET /v2/workspaces/{id}/inferences/{inference_id}` returns the same shape as v1 plus the four fields above. If you parse responses leniently (as the [versioning policy](/docs/versioning) recommends), no client change is required.

## 3\. Models → Base Models

The model catalog endpoints were renamed to reflect that v2 works with **base models** directly:

* `GET /v1/workspaces/{id}/models` → `GET /v2/workspaces/{id}/base-models`
* `GET /v1/workspaces/{id}/models/{model_id}` → `GET /v2/workspaces/{id}/base-models/{base_model_id}`

The response shape changed too, so this is more than a path rename:

|                 | v1                                                                                                     | v2                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| List envelope   | { "models": \[...\] }                                                                                  | { "base\_models": \[...\] }                                         |
| Detail envelope | { "model": { ... } }                                                                                   | the model object, unwrapped                                         |
| Removed fields  | —                                                                                                      | model\_id, base\_model\_name, prompt\_format                        |
| Added fields    | —                                                                                                      | aliases, price\_per\_unit, price\_unit                              |
| Query filters   | modality, search, plus per-capability flags (inpainting, supports\_reference\_images, text\_to\_3d, …) | modality, search only — narrow on each model’s capabilities instead |

Use `base_model_id` where you previously read `model_id`.

## New in v2

These have no v1 equivalent — adopt them when you need them, they’re not migration work:

* `GET /v2/workspaces/{id}/base-models/{slug}/inference-schema` — the per-model inference parameter schema
* `POST /v2/workspaces/{id}/base-models/{slug}/inferences` — run an inference against a base model by slug
* `GET /v2/workspaces/{id}/reference-sets` and `GET /v2/workspaces/{id}/reference-sets/{reference_set_id}` — list and fetch reference sets

## Checklist

1. Update your base URL from `/api/v1` to `/api/v2`.
2. If you start or estimate inferences: switch the request body to `base_model_id` (+ optional `reference_sets`) and drop `model_id`/`weight`.
3. If you list or fetch models: rename `…/models` to `…/base-models`, read `base_models` instead of `models`, drop the `{ "model": … }` unwrapping on detail responses, and replace any per-capability query filter with a `capabilities` check.
4. Everything else works by changing the prefix alone.

Note

No v1 endpoint was removed without a v2 equivalent. If you rely on a v1 path that 404s under v2, it’s one of the renamed endpoints above — check the table.