# API changelog Dated changes to the Layer REST API, newest first. This changelog covers API-surface changes (new versions, new endpoints, breaking changes, deprecations). For SDK and MCP changes, see their own release notes. ## 2026-10-20: refusal codes and error codes in every error body * **New:** a failed inference run carries `refusal` when a guardrail or the model provider refused it: its `code`, and for a guardrail block every guardrail that blocked it with its `guardrail_id`, `name`, `reason` and `category`. A failed workflow run lists every refused generation in `refusals`. Webhook deliveries carry both. See [Refused generations](/docs/errors#refused-generations). * **New:** every error body carries `error_code`, the code that ends its `type`, so you can branch on it without parsing the URI. ## 2026-10-20: workflow names belong to the workflow * **Changed:** `name` and `description` in the workflows list (`GET …/workspaces/{id}/workflows`, MCP `list_workflows`) are the workflow’s current details, not the published version’s. A workflow renamed in Layer shows its new name here at once, without a new publish. The response shape is unchanged. ## 2026-10-18: annotate your images * **New:** a guidance file of type `init_image` or `reference_image` takes `annotations`: numbered marks (boxes, ellipses, arrows, freehand paths and pins) that say what to change where, or what to use from a reference, each with an optional `note`. Arrows can move what a box or ellipse marks, and a mark can ask for what it encloses to be removed. See [Annotating images](/docs/files#annotating-images). * **New:** a model’s `capabilities` object reports `visual_annotations`: `RENDERED` for models that read the marks from a copy of the image with them drawn on, `NATIVE_BOXES` for models that take boxes as input. A model without it ignores the marks, and the run reports that it did. ## 2026-10-15: tile, 9-slice and sprite sheet data on outputs * **New:** every output file of an inference run, a workflow run and a session object carries an optional `metadata` object. Its `tile` holds a game tile sprite’s grid placement (shape, orientation, footprint, anchor, cell centre, base outline) and its `nine_slice` holds a UI element’s stretch insets, so an engine can build a TileSet or 9-slice resource without measuring the image. Each is null when the file has no such data, and `metadata` is null when it has neither. Webhook deliveries carry it too, since their `data` is the matching `GET` body. * **New:** `metadata.sprite_sheet` holds a sprite sheet’s frame grid (columns, rows, cell size, margin, spacing), each frame’s rect and anchor, and its named animations, so an engine can build an animated sprite resource without measuring the sheet. Sheets packed by the sprite sheet tool or a workflow’s image grid step carry it. With no animations, play every frame in order at 12 fps, looping. ## 2026-09-07: audio clip length is discoverable * **New:** a model’s `capabilities` object carries `duration_seconds_min`, `duration_seconds_max` and `duration_seconds_required` in **v1** as well as v2\. Audio models report their selectable clip length there; v1 previously exposed only `duration_seconds`, the list of discrete video lengths, which is empty for audio and read as “this model takes no duration”. See [Output length](/docs/models#output-length). * **Changed:** the `duration_seconds` request field is documented as an output length for audio as well as video. The field itself is unchanged: it always accepted an audio clip length. ## 2026-08-26: v2 is now the default **v2 of the Layer REST API is live and is the default across these docs.** Every endpoint is available under `/v2`; v1 remains live under `/v1` and will be deprecated as a whole later. * **Changed:** inference endpoints move from `model_id` \+ `weight` to `base_model_id` \+ `modality` \+ optional `reference_sets`, and inference responses gain base-model/reference-set fields. Models endpoints are renamed to Base Models. See the [v1 → v2 migration guide](/docs/migration) for the full list. * **New:** `…/base-models/{slug}/inference-schema`, `…/base-models/{slug}/inferences`, and `…/reference-sets` endpoints. * **Unchanged:** all other endpoints are drop-in: identical schemas in v1 and v2. The docs now carry the version in the URL (`/docs/v2/…`, `/docs/v1/…`), and v1 pages point at their v2 equivalents. Note Earlier API changes predate this changelog. The full v1 surface remains documented under while v1 is live.