Design Details

Retrieve all details for a specific design: its name, type, available formats, and — once created — its dynamic_image_url.

Use the designId from the List Designs endpoint or from the Abyssale dashboard URL.

GET/designs/{designId}API Reference

Sample request

cURLNode.jsPython

bash

curl -H "x-api-key: {YOUR-API-KEY}" \
  "https://api.abyssale.com/designs/{designId}?i=advanced"

javascript

import abyssale from '@abyssale/sdk';
// Set ABYSSALE_API_KEY env var before running

// Omit the options object for the default view, which hides group layers
const { data, error } = await abyssale.getDesign('{designId}', { advanced: true });

// A printer_multipage design has no `formats` — it carries `pages` instead
if (error) console.error(error);
else console.log(data.type, data.formats?.map((f) => f.id));

python

from abyssale import Abyssale
# Set ABYSSALE_API_KEY env var before running

with Abyssale() as client:
    # Omit advanced=True for the default view, which hides group layers
    design = client.get_design("{designId}", advanced=True)

# A printer_multipage design has no `formats` — it carries `pages` instead
print(design.type, [f.id for f in design.formats or []])

Path parameters

Parameter	Type	Required	Description
`designId`	`string (uuid)`	Yes	Unique identifier of the design.

Query parameters

Parameter	Type	Required	Description
`i`	`string`	No	Pass `advanced` to get the full layer and property set — see below.

Pass ?i=advanced to get every layer and property

Without it you get the original released shape, which omits group layers — a group's children are listed individually and the group itself is invisible. See Group layers.

Design Format Details is always the advanced view and needs no parameter.

Response

The response shape depends on the design type. printer_multipage designs are page-oriented and return a different set of fields — see Multi-page print designs.

`static` · `animated` · `printer`

Field	Type	Description
`id`	`string (uuid)`	Unique identifier of the design.
`name`	`string`	Name of the design.
`type`	`string`	Design type: `"static"`, `"animated"`, or `"printer"`.
`created_at`	`integer`	Unix timestamp of creation.
`updated_at`	`integer`	Unix timestamp of last update.
`project_id`	`string (uuid)`	Project the design belongs to.
`project_name`	`string`	Name of that project.
`category_id`	`string (uuid) \| null`	Deprecated alias of `project_id`.
`category_name`	`string \| null`	Deprecated alias of `project_name`.
`formats`	`array`	List of available formats (dimensions). Each item includes `id`, `uid`, `width`, `height`, `unit`, `preview_url`, and `dynamic_image_url`. On `printer` designs, each format additionally carries its print settings read-only, and all three are always present: `dpi` (integer render DPI resolved at import time, capped at 300 — large formats get a proportionally lower value; `300` when the design has none stored), plus `bleed_size` and `safe_size` (floats in the format's unit, `0` when the zone is off). Read them unconditionally.
`elements`	`array`	All configurable elements and their properties. Each item includes `name` (layer name), `type`, and `attributes`. `group` layers appear only with `?i=advanced`.
`animation`	`object`	`animated` designs only. The design's timeline (`duration`, `screenshot_at_s`).
`variables`	`object`	Template variables defined in text layers (e.g. `{ "name": "{name}" }`).

Response example

json

{
  "id": "64238d01-d402-474b-8c2d-fbc957e9d290",
  "name": "Ad campaign fall 2025",
  "type": "static",
  "created_at": 1649942114,
  "updated_at": 1649942114,
  "project_id": "9d1f2b7c-5a44-4c3e-9f21-0b8e6d4a1c73",
  "project_name": "Fall campaigns",
  "category_id": "9d1f2b7c-5a44-4c3e-9f21-0b8e6d4a1c73",
  "category_name": "Fall campaigns",
  "formats": [
    {
      "id": "facebook-post",
      "uid": "9b57d65e-eb2c-4a74-a51e-4482917c248a",
      "width": 1200,
      "height": 1200,
      "unit": "px",
      "preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/a9b3c668-7b84-4924-adf0-815dae727d32.png",
      "dynamic_image_url": "https://img.abyssale.com/ecf1fe8c-5392-48c2-b6d2-665183a18fe5/9b57d65e-eb2c-4a74-a51e-4482917c248a"
    }
  ],
  "elements": [
    {
      "name": "root",
      "type": "container",
      "attributes": [
        { "id": "background_color", "help": "Background color of the banner", "values": { "facebook-post": "#FFFFFF" } }
      ]
    },
    {
      "name": "text_title",
      "type": "text",
      "attributes": [
        { "id": "payload", "help": "Text content", "values": { "facebook-post": "My image title" } }
      ]
    }
  ],
  "variables": {
    "name": "{name}",
    "title": "{title}"
  }
}

Group layers

A group layer is a container that holds other layers and can lay them out automatically. Request it explicitly:

GET /designs/{designId}?i=advanced

This applies to every design type, printer_multipage included — there the groups are injected into each page's own list inside elements_per_page.

Why it is not returned by default

The original released shape of this endpoint has no group element, so adding one unconditionally would change the response of every existing client.

Each injected group is an element of type: "group" carrying:

Field	Type	Description
`name`	`string`	Layer name of the group.
`type`	`string`	Always `"group"` — including for a masked group. See Masked groups.
`attributes`	`array`	Always empty. Nothing on a group is customisable — the fields below describe structure, and `hidden` / `locked` are derived from its members — so there is nothing to override in a generation request. Present so every element has the same shape. An object (`{}`) on a `printer_multipage` page, where attributes are keyed by id.
`layer_ids`	`string[]`	Names of the layers that belong to the group. One list for the whole design — a group holds the same children in every format — so it sits on the element, not inside the per-format block.
`layout`	`object`	`{x, y, width, height}` keyed by format name on this endpoint. Pixels on `static`/`animated`; floats in the design's unit (mm/in) on print.
`mask`	`object`	Present only on a masked group, keyed by format name. See Masked groups.
`group`	`object`	The group's auto-layout settings, keyed by format name. See below. Absent on `animated` designs, which have no per-format group settings at all.
`hidden`	`object`	Keyed by format name. `true` only when every member is hidden in that format.
`locked`	`object`	Keyed by format name. `true` only when every member is locked in that format.
`animation`	`object`	`animated` designs only, and only when the group carries timing: `{ "start_at_s": …, "end_at_s": … }`. A flat object, not keyed by format.

Each per-format group block:

Field	Type	Description
`auto_layout`	`boolean`	Whether the group positions its children automatically. Not returned on `animated` designs — auto-layout does not apply there.
`direction`	`string`	`"vertical"` or `"horizontal"`. Auto-layout only.
`placement`	`string`	Where children are anchored, e.g. `"top-left"`. Auto-layout only.
`gap`	`number`	Spacing between children — an integer in px on `static`, a float in the design's unit on print. Auto-layout only.

json

{
  "name": "cta-block",
  "type": "group",
  "layout": {
    "facebook-post": { "x": 40, "y": 820, "width": 420, "height": 160 }
  },
  "layer_ids": ["cta-label", "cta-button"],
  "group": {
    "facebook-post": {
      "auto_layout": true,
      "direction": "vertical",
      "placement": "top-left",
      "gap": 12
    }
  },
  "hidden": { "facebook-post": false },
  "locked": { "facebook-post": false },
  "attributes": []
}

Masked groups

A group whose members are clipped to a shape is still a group — there is no separate layer type, exactly as on import. What makes it masked is a mask object:

json

"mask": {
  "facebook-post": {
    "shape": "circle",
    "width": 696, "height": 142,
    "center_x": 529, "center_y": 414,
    "rx": 348, "ry": 71
  }
}

mask is keyed by format because the geometry can differ per format, but its presence is a property of the layer: a group is masked in every one of its formats or in none. Use the key's presence to tell a masked group from a plain one — mask absent means no clip.

On print designs the lengths are floats in the design's unit; rx and ry are already in that unit and are returned as stored.

hidden and locked are computed, not stored

A group is reported hidden (or locked) only when all of its members are. A group with no members is neither.

On a printer_multipage design, groups are appended to their own page's list inside elements_per_page and are already flattened to that page — as on the per-format read, layout, group, hidden and locked are plain values.

On Design Format Details the same group is returned already flattened to that one format — layout, group, hidden and locked are plain values rather than objects keyed by format name.

Multi-page print designs

This section covers the design-level response (GET /designs/{designId}) — the full page list. For the response of one specific page, see Design Format Details → Multi-page print designs.

A printer_multipage design is page-oriented, not format-oriented. Its response replaces formats with pages, and elements with elements_per_page:

A client coded against formats[] will break

printer_multipage returns no formats, no top-level elements, no variables, and no dynamic_image_url — print designs have no dynamic image. Branch on type before reading the response.

Field	Type	Description
`id`	`string (uuid)`	Unique identifier of the design.
`name`	`string`	Name of the design.
`type`	`string`	Always `"printer_multipage"`.
`template_id`	`string (uuid)`	Underlying template identifier.
`created_at`	`integer`	Unix timestamp of creation.
`updated_at`	`integer`	Unix timestamp of last update.
`project_id`	`string (uuid)`	Project the design belongs to.
`project_name`	`string`	Name of that project.
`category_id`	`string (uuid) \| null`	Deprecated alias of `project_id`.
`category_name`	`string \| null`	Deprecated alias of `project_name`.
`pages`	`array`	Ordered pages — array order is print order. See the item shape below.
`elements_per_page`	`object`	Elements keyed by page id: `{ "page_1": [ … ], "page_2": [ … ] }`. Note this is an object, not an array. Group layers appear in each page's list only with `?i=advanced`. On this read each element's `attributes` is also an object, keyed by attribute id, and each attribute carries a single `value` — every other read returns an array. Normalise with `Object.values(attributes)` / `list(attributes.values())` so your code tolerates both.

Each pages[] item:

Field	Type	Description
`id`	`string`	Page identifier — `page_1` … `page_N`, matching print order.
`width`	`number`	Page width, a float in `unit`.
`height`	`number`	Page height, a float in `unit`.
`unit`	`string`	`"mm"` or `"in"`.
`preview_url`	`string (uri)`	Preview thumbnail for this page.

A page carries no print settings. dpi, bleed_size and safe_size describe the whole document and are returned once, at the root of the response — the same place the import declares them. All three are always present on a printer design, so read them unconditionally. width / height / unit are repeated on every page and are identical across them, because every page of a multi-page design shares one size. See Multi-Page Print Imports.

Response Example — `printer_multipage`

json

{
  "id": "8b1f4c02-3d77-4a19-9f2e-6a1c0b7d5e34",
  "name": "Product Brochure",
  "type": "printer_multipage",
  "template_id": "8b1f4c02-3d77-4a19-9f2e-6a1c0b7d5e34",
  "created_at": 1749827734,
  "updated_at": 1749827902,
  "project_id": "5e8a2c41-9b70-4f36-8d12-3c6f0a94b7e5",
  "project_name": "Print collateral",
  "category_id": "5e8a2c41-9b70-4f36-8d12-3c6f0a94b7e5",
  "category_name": "Print collateral",
  "pages": [
    {
      "id": "page_1",
      "width": 210,
      "height": 297,
      "unit": "mm",
      "preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/…/page-1.png"
    },
    {
      "id": "page_2",
      "width": 210,
      "height": 297,
      "unit": "mm",
      "preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/…/page-2.png"
    }
  ],
  "elements_per_page": {
    "page_1": [
      {
        "name": "cover-title",
        "type": "text",
        "attributes": {
          "payload": { "id": "payload", "help": "Text content", "value": "2026 Collection" }
        }
      }
    ],
    "page_2": [
      {
        "name": "body",
        "type": "text",
        "attributes": {
          "payload": { "id": "payload", "help": "Text content", "value": "Everything you need for the season ahead." }
        }
      }
    ]
  }
}

Design Format Details — a single format, or a single page of a multi-page design
Export a Design — the same design as a re-importable payload
Multi-Page Print Imports — the authoring contract behind pages[]
Node.js SDK · Python SDK — every method, config, retries and the polling helpers

Designs

Design Details

Design Import

Layer Types

Workspace Templates

Generation

Asynchronous

Element Properties

Design Details

Sample request

Path parameters

Query parameters

Response

`static` · `animated` · `printer`

Response example

Group layers

Masked groups

Multi-page print designs

Response Example — `printer_multipage`

Design Details

Design Import

Layer Types

Asynchronous

Element Properties

Design Details ​

Sample request ​

Path parameters ​

Query parameters ​

Response ​

static · animated · printer ​

Response example ​

Group layers ​

Masked groups ​

Multi-page print designs ​

Response Example — printer_multipage ​

Related ​

Design Details

Sample request

Path parameters

Query parameters

Response

`static` · `animated` · `printer`

Response example

Group layers

Masked groups

Multi-page print designs

Response Example — `printer_multipage`

Related