Developers

Appearance

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