Get design details
Sample request
curl -X GET "https://api.abyssale.com/designs/$DESIGN_ID" \
-H "x-api-key: $ABYSSALE_API_KEY"import abyssale from '@abyssale/sdk';
const designId = 'YOUR_DESIGN_ID';
const { data, error } = await abyssale.getDesign(designId);
if (error) console.error(error.id, error.message);
else console.log(data);from abyssale import Abyssale
design_id = "YOUR_DESIGN_ID"
with Abyssale() as client:
result = client.get_design(design_id)
print(result)Example 200 response
{
"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",
"dpi": 300
}
],
"elements": [
{
"name": "element-name",
"type": "text",
"layout": {
"<format-id>": {
"x": 0,
"y": 0,
"width": 3333,
"height": 666
}
},
"layer_ids": [
"string"
],
"hidden": {
"<format-id>": false
},
"locked": {
"<format-id>": false
},
"group": {
"<format-id>": {
"auto_layout": false,
"direction": "string",
"placement": "string",
"gap": 0
}
},
"mask": {
"<format-id>": {
"shape": "string",
"width": 0,
"height": 0,
"center_x": 0,
"center_y": 0,
"rx": 0,
"ry": 0,
"rotation": 0,
"radius": 0
}
},
"attributes": [
{
"id": "payload",
"help": "Text content (i.e. Lorem ipsum)",
"values": {
"facebook-post": "My image title"
}
}
]
}
],
"variables": {
"name": "{name}",
"title": "{title}"
},
"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"template_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",
"version": "v2026-08-21"
}Example 401 error response
{
"message": "Unauthorized: missing or invalid API key.",
"id": "unauthorized"
}Retrieve the full specification of a design: its formats (dimensions and preview URLs), all configurable elements with their properties, and any template variables defined in text layers. Use this endpoint to discover what data to send in a generation request.
Behaviour, limits and caveats
For printer designs, each format additionally carries its print settings read-only: dpi (integer render DPI computed at import time, capped at 300), and bleed_size / safe_size (floats in the design's unit). All three are always present on a printer format — a design with no stored print settings, or with a zone disabled, reports the values the renderer itself uses: dpi: 300 and bleed_size / safe_size of 0, where 0 means the zone is off. Read them unconditionally; there is no need to test for the keys.
For animated designs, the response additionally carries the animation model: a top-level animation object (duration — timeline length in seconds; screenshot_at_s — the HTML5 backup-screenshot moment, null on designs created before it was recorded), a per-element animation object (start_at_s, end_at_s, tweens [{id, type, keyframes}] with raw keyframe objects) on elements that carry timing or tweens, and video/audio media attributes (video_url/audio_url, video_duration, video_muted/audio_muted, max_volume) in the standard attribute shape.
Multipage print designs (printer_multipage) return a different shape. A multipage design has no formats — each page is one format row — so the response carries pages and elements_per_page instead of formats, elements and variables. A client coded against formats[] will not work on a multipage design, and because a dynamic image is minted per format, a multipage design has no dynamic_image_url anywhere in the response (it is a static-only feature in any case).
pages[] items are DesignPage objects, not formats: id (page_1 … page_N), width, height, unit and preview_url — no format uid. elements_per_page is an object keyed by page id (not an array), each value being that page's element list.
The print settings are returned once, at the root — dpi, bleed_size and safe_size describe the document, not a page, because a multipage design has a single print setup. That is the same reason the import declares them at the top level. A page does not repeat them.
Group layers require ?i=advanced. By default this endpoint returns its original released shape, in which no group layer appears at all — its children are listed individually and the group itself is invisible. Pass i=advanced to have them injected (into elements, or into each page's list in elements_per_page on a multipage design). Each one carries layer_ids (one list for the whole design — a group holds the same children in every format), a per-format layout, its computed hidden / locked, and, except on animated designs, a per-format group block of auto-layout settings (auto_layout / direction / placement / gap).
A masked group — one whose members are clipped to a shape — is still type: "group" and additionally carries mask, keyed by format. The geometry can differ per format, but a group is masked in all of its formats or in none, so the presence of mask is what distinguishes a masked group from a plain one.
The per-format read GET /designs/{designId}/formats/{formatSpecifier} is always the advanced view and needs no parameter; there layout, mask and group are flattened to the single format.
Path parameters
designId string (uuid) required
Unique identifier (UUID) of the design. A value that is not a UUID does not match the route and answers 404 with id: endpoint_not_found.
Query parameters
i string
Pass advanced to receive the design's full layer set and property set — notably group layers, which are omitted from the default response. Any other value (or none) returns the default shape. One of "advanced".
Response 200
The design's formats, elements and variables.
formats array of DesignFormat
The list of formats available in the design.
More about formats
The list of formats available in the design.
The id property can be used to specify the format you would like to generate in the generation API call.
Show child attributes
id string always
Unique identifier (name) of the format.
uid string (uuid) always
Unique UUID of the format
width number always
Width of the format
height number always
Height of the format
unit string
Unit of measurement for dimensions
preview_url string (uri)
Preview Image URL of the format
dynamic_image_url string (uri)
URL of the existing dynamic image for this format.
dpi integer
Printer designs only. Render DPI of the format, computed at import time (capped at 300; large formats degrade to stay within the renderer's pixel budget). Read-only — not an import field.
bleed_size number
Printer designs only. Bleed size as a float in the design's unit (mm/in). Always present on a printer format; 0 means the zone is off.
safe_size number
Printer designs only. Safe-zone size as a float in the design's unit (mm/in). Always present on a printer format; 0 means the zone is off.
elements array of DesignElement
The list of all elements (& customizable properties) contained in the design.
More about elements
The list of all elements (& customizable properties) contained in the design.
name is the layer name (root is a special element that allows to customize the image background color.)
attributes contains the list of all customizable properties:
id: The attribute IDvalues: the related value for this attribute in each format (if defined)
Show child attributes
name string always
Layer name (root is a special element that allows to customize the image background color.)
type string always
Layer type. One of "container", "text", "button", "image", "logo", "shape", "illustration", "rating", "qrcode", "video", "audio", "group", "code".
More about type
Layer type. container is the design's own root wrapper, not a layer you can author or override — skip it when walking the tree. group elements are injected only on the platform advanced view (i=advanced); a masked group reports group too, with a mask block. code is listed last because it is marginal: a custom HTML/JS layer that exists only on animated designs, read-only like container — it carries no customisable attributes, so it can never be targeted in a generation request.
layout object
The element's box, keyed by format name.
Show child attributes
<format-id> ElementLayout
One entry per format id.
Show child attributes
x number
y number
width number
height number
layer_ids array of string
group layers only — the names of the layers this group contains.
hidden object
group layers only — computed visibility, keyed by format name.
Show child attributes
<format-id> boolean
One entry per format id.
locked object
group layers only — computed lock state, keyed by format name.
Show child attributes
<format-id> boolean
One entry per format id.
group object
group layers only — auto-layout settings, keyed by format name.
Show child attributes
<format-id> GroupLayout
One entry per format id.
Show child attributes
auto_layout boolean
direction string
placement string
gap number
Pixels on static/animated; a physical-unit float on printer.
mask object
Masked group layers only — the mask geometry, keyed by format name. Presence is a layer-level fact: a layer is a masked group in every format or in none.
Show child attributes
<format-id> GroupMask
One entry per format id.
Show child attributes
shape string always
width number
height number
center_x number
center_y number
rx number
ry number
rotation number
radius number | object
animation object
Animated designs only; present when the element carries timeline timing or tweens. An injected group layer carries start_at_s / end_at_s only — never tweens.
Show child attributes
start_at_s number | null
end_at_s number | null
tweens array of object
attributes array of object always
List of all attributes
Show child attributes
id string always
The attribute name
help string
An helper to understand what is this attribute
values object always
variables DesignVariables
Variables used within the text layers of the design. Keys are variable names (without braces), values are the placeholder as written in the design (e.g. "{name}").
Show child attributes
<variable-name> string
One entry per variable name.
animation DesignAnimation
Animated designs only. The design's timeline, read-only (all values in seconds).
Show child attributes
duration number | null
Timeline length in seconds.
screenshot_at_s number | null
The moment the HTML5 backup screenshot is taken (seconds). Null on designs created before it was recorded that never stored it; always set on imported designs.
dpi integer
printer_multipage designs only — the document's render DPI, computed at import time and capped at 300. Read-only.
bleed_size number
printer_multipage designs only — the document's bleed, a float in the design's unit; 0 means the zone is off.
More about bleed_size
printer_multipage designs only — the document's bleed, a float in the design's unit; 0 means the zone is off.
Declared once, here, because a multipage document has a single print setup — the same reason the import declares unit / width / height / bleed_size / safe_size / dpi at the top level and leaves a page carrying only background_color and layers. A page does not repeat it.
safe_size number
printer_multipage designs only — the document's safe zone, a float in the design's unit; 0 means the zone is off.
pages array of DesignPage
printer_multipage designs only — returned instead of formats. The document's ordered pages. Every page shares the document's dimensions and print settings, so a page carries neither: read those from the root.
Show child attributes
id string always
Page identifier, page_1 … page_N, in document order.
width number always
Page width as a float in unit. Every page of the document shares it.
height number always
Page height as a float in unit. Every page of the document shares it.
unit string
The document's physical authoring unit. One of "mm", "in".
preview_url string (uri)
Preview image URL of this page.
elements_per_page object
printer_multipage designs only — returned instead of elements.
More about elements_per_page
printer_multipage designs only — returned instead of elements. An object keyed by page id (page_1 … page_N), each value being that page's element list (group layers included only when i=advanced is passed). Defaults to {}.
Items are DesignPageElement, not DesignElement: a page is a single format, so values are flat rather than keyed by format name. Note also that its attributes is an object, where every other read returns an array — see the schema.
Show child attributes
<page-id> array of DesignPageElement
One entry per page id.
id string (uuid) always
Unique identifier (UUID) of the design.
template_id string (uuid)
Deprecated duplicate of id, equal to it. Present on the single-design read; not emitted by the GET /designs listing. Kept for existing clients — read id.
name string always
Name of the design.
type string always
Type of the design One of "static", "printer", "animated", "printer_multipage".
created_at integer always
Timestamp of when the design has been created.
updated_at integer always
Timestamp of when the design has been updated for the last time.
project_id string (uuid) | null always
Unique identifier (UUID) of the project the design belongs to. null when the project cannot be resolved.
project_name string | null always
Name of the project the design belongs to. null when the project cannot be resolved.
category_id string (uuid) | null
Deprecated. Deprecated, superseded by project_id, and always equal to it on a design. category_id properly names the grouping of a WORKSPACE TEMPLATE — a design belongs to a project, so read project_id.
category_name string | null
Deprecated. Deprecated, superseded by project_name, which it mirrors on every read — the platform reads both from the same company_template_category row, the table that holds projects.
More about category_name
Deprecated, superseded by project_name, which it mirrors on every read — the platform reads both from the same company_template_category row, the table that holds projects. null when the design is in no project. category_* names the grouping of a WORKSPACE TEMPLATE — a design belongs to a project, so read project_name.
version string
The API version that produced this response, named by release date (vYYYY-MM-DD). Pattern ^v\d{4}-\d{2}-\d{2}$.
More about version
The API version that produced this response, named by release date (vYYYY-MM-DD). Stamped as a top-level field on JSON object bodies, success and error alike, so a client can always tell which contract answered. There is no version-selection parameter — a single version is maintained at a time.
Two kinds of body are not stamped. Array bodies (the listings) carry no envelope. And a body that already has a version key of its own is left alone — which in practice means Banner, whose version is the generated file's integer counter. So GET /banners/{bannerId} and the synchronous generate are the two responses that do not tell you which contract answered.
The value changes when a new version is released. Match the vYYYY-MM-DD shape rather than pinning today's literal, or your client breaks on the next release.
Errors
Every failure uses the shared error envelope — {id, message, errors?}. Branch on id, never on message. See Errors.
| Status | When |
|---|---|
401 | Unauthorized — missing or invalid API key. |
404 | Design not found (template_not_found). |
429 | Too Many Requests. |
500 | Internal Server Error — an unexpected error occurred on our side. |