API Changelog

The API is versioned by release date — vYYYY-MM-DD, never a counter. Every JSON object response, success and error alike, carries a top-level version field naming the version that answered it, so you can always tell which contract produced a response.

v2026-09-02

No breaking changes.

Added

• GET /credits returns your workspace's remaining credits for the current billing period — generation_credits and ai_credits, each with available, limit, consumed and extra. available and limit are null on an unlimited plan, so branch on null before comparing numbers. The read costs no credits and is on the Read budget.

v2026-08-31

Everything below is on the Alpha design import surface (POST /designs/import/json, GET /designs/{designId}/as-import). No stable endpoint changed. As stated when that surface shipped, its contract may change without notice and is not covered by the deprecation policy — these are the changes.

Breaking Action required if you author animations

• Animation keyframe values are validated. Every attr a tween animates used to be passed straight through, so a value the renderer cannot use was stored and simply never played. Each is now checked, and the units are not the same for every one:

  attr	Range	Unit
  opacity	0 … 1	fraction
  volumeEffect	0 … 1	fraction
  scale	0 … 100	percent, 100 = as designed
  angle	no bound	signed degrees (1140 = four clockwise turns)
  left, top	no bound	signed px
  typewriting	0 or 100 only	—

  A non-number is invalid_payload, a number outside its range is out_of_range, and a typewriting other than 0/100 is unknown_enum_value — all at layers[i].animation.tweens[j].keyframes[k].attr.<name>.

  Check opacity first. Inside a keyframe it is a 0–1 fraction, but a layer's properties.opacity is an integer 0–100. Same word, two scales, so {"opacity": 100} in a keyframe is now out_of_range rather than "fully opaque". volumeEffect is a fraction for the same reason, and typewriting is not a range at all — the effect types the text in whole, so 50 is not "half typed".

• A keyframe must sit inside its layer's visible window. data.time is absolute seconds on the timeline and must fall within the layer's start_at_s … end_at_s (defaulting to 0 and animation.duration), otherwise out_of_range at …keyframes[k].data.time. A layer's effects cannot run outside the window in which the layer exists, so such a keyframe was never reached and imported as an animation that never played. Keyframes are still not required to be ordered.

• GET /designs/{designId}/as-import fails on a design that breaks either rule. The export is validated against the import before it is returned, so a design holding an out-of-range keyframe value answers not_round_trippable instead of handing back a payload the import would reject. If you hit this on a design you did not create through the API, its stored animation is the problem — send us the design id.

Added

• A format's background_color is optional and defaults to white — #FFFFFF on static and animated, cmyk(0,0,0,0) on printer. Same for a printer_multipage page. Omitting it emits no color_converted warning.
• A button layer's alignment accepts the single-token shorthand every other layer type already accepted: one token names one axis and the other takes its middle, so center is middle center and top is top center. Exports still return the two-token form.

v2026-08-21

No breaking changes.

Added

• Webhook deliveries are signed — every delivery carries X-Abyssale-Signature: t=<unix>,v1=<hex>, an HMAC-SHA256 over "v1:webhook:" + t + "." + raw_body, plus X-Abyssale-Delivery-Id for deduplication. Signing is opt-in: a workspace that has never fetched its secret keeps receiving unsigned deliveries. Additive — no payload field and no status code changed. See Signature verification.
• GET /signing-secret returns the workspace's signing secret, minting it on the first call. One secret covers every webhook in the workspace. It is not the API key and cannot replace one.
• POST /signing-secret/rotate issues a new secret and keeps the previous one valid for 24 hours, signing each delivery with both. A second rotate inside that window answers 409 previous_secret_still_active unless you pass ?force=true.
• POST /signing-secret/revoke ends the overlap early, leaving the current secret in place.

v2026-08-20

No breaking changes.

Fixed

• group layers carry attributes — always empty ({} on a printer_multipage page, [] everywhere else). Nothing on a group is customisable; the key exists so every element has the same shape.
• Repeating a query parameter no longer changes the response — a duplicated ?i=advanced fell back to the plain read, and a duplicated ?version= answered 500.
• Error messages name the offending field — name: Missing data for required field. rather than "One or more request fields are invalid.", including errors relayed from the generation engine. errors and id are unchanged.

Reference corrections

The API is unchanged — the reference described these wrongly, so a client validating responses against it rejected valid payloads.

• code, an animated-only read-only layer type, is documented. Skip it as you skip container.
• A keyframe's attr is an object ({"left": 1021, "top": 347}), not a string.
• mask_properties and filter_properties values are objects, not scalars.

v2026-08-17

Breaking Action required

• One error envelope on every endpoint and every status — {id, message, errors?}. errors is now a flat array, and the code moved to top-level id. Migration steps.
• Framework failures answer real codes — method_not_allowed, invalid_json, internal_error — instead of the placeholder error.
• Three misspelled 404 codes are corrected, each of which held a literal space: project_not found → project_not_found, and likewise for workspace_template_not_found and duplication_request_not_found.
• Every JSON object response carries a top-level version. Clients that reject unknown fields must accept it.
• GET /designs and GET /projects hide deleted records — a design whose project was deleted is no longer listed, and only CREATED projects are returned.
• message no longer begins with the HTTP status number — "404 Design … not found" is now "Design … not found". A client that slices or matches that prefix breaks silently. Branch on id instead; see Errors.
• An unknown format answers 404, not 400, on synchronous generation — matching every other endpoint and the reference.
• Per-workspace rate limiting, with a new 429 code. Endpoints now carry a per-minute and per-hour budget by route class and answer 429 request_rate_limited when you exceed it. This is a different id from rate_limit_exceeded, which keeps its meaning — out of credits, or the global ceiling. A client that branches on rate_limit_exceeded alone will not recognise a throttle. Retry request_rate_limited. rate_limit_exceeded covers two situations and message tells them apart — back off when it is the global ceiling, top up or upgrade when it is credits or plan, which no amount of retrying fixes. feature_not_in_plan is never worth retrying. Every response now carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refusal adds Retry-After — pace against those rather than retrying blind. The budget is per workspace, so extra API keys do not raise it.

Added

• Design import Alpha — POST /designs/import/json builds a design or workspace template from JSON (static, animated, printer, printer_multipage), with GET/PUT /designs/import/json/{importId} to poll and validate. The design type is checked against your plan before anything is created — animated needs MP4, printer and printer_multipage need Printable PDF — and a workspace without it gets a new 429 feature_not_in_plan, on ?validate_only=true as well.
• GET /designs/{designId}/as-importAlpha — export any design in the exact shape the import accepts.
• GET /workspace-templates and GET /workspace-template-categories list the workspace's shared templates and their categories.
• Designs report their project — project_id / project_name on the listing and detail endpoints, plus a project_id filter. category_id / category_name remain as deprecated aliases.
• GET /designs/{designId} returns the full design model — print geometry (dpi, bleed_size, safe_size), the animated animation block with per-element timing and tweens, and pages[] plus elements_per_page (keyed page_1…page_N) for multi-page print designs.
• ?i=advanced returns group layers, with layer_ids, per-format layout, and auto-layout settings. Without the parameter the response keeps its previous shape.
• Webhook payloads carry event_type — route on it instead of inferring the event from the payload's shape.

Fixed

• A deleted design answers 404, not 400, on the generation endpoints, with the same template_not_found code a design that never existed already returned.
• No error response is empty. GET /banners/{bannerId}, the banner listing, ZIP export with unknown ids, a failed workspace-template duplication and the public renderer all returned a JSON content type with no body.
• POST /public/asset/import answers 400, not 500, when asset_name is missing.
• Field-level detail always uses {path, code, message} — errors relayed from the generation engine used to arrive as {field, message}, and now carry an id rather than prose alone.
• Plan and credit gates on asynchronous generation answer 429 rate_limit_exceeded instead of a 400 whose message merely started with "429".

Deprecated Plan a migration

• remove_bg on synchronous generation — still works, but it can push the call past the endpoint's 10-second cap. Remove backgrounds asynchronously. auto_focus is unaffected.
• text_to_image is gone from the synchronous schema. It was always rejected there.
• The category_id query parameter on GET /designs — filter with project_id. Existing requests keep working.
• auto_focus_properties.model: "face" — use "people" with focus_framing: "face". It detects faces with the same model and also honours focus_zoom and focus_target, which "face" ignores. focus_framing already defaults to "face", so switching to "model": "people" is usually the whole migration. "face" keeps working.

Changed

• GET /fonts sorts case-insensitively.

Before v2026-08-17

Releases before the versioning scheme carried no version name and no version payload field.