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.
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.
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.
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 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.