Migrating from v1 to v2

Viewing v2— current version

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.

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

{
  "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 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

Update your base URL from /api/v1 to /api/v2.
If you start or estimate inferences: switch the request body to base_model_id (+ optional reference_sets) and drop model_id/weight.
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.
Everything else works by changing the prefix alone.