List Designs

Return the designs in your workspace as a flat array — each item carries the design's identity (id, name, type), its project and a preview thumbnail. Search by words; filter by project, design type, format and date; sort, and page. The listing stays shallow: it carries no formats or elements — fetch a design's full structure with Design Details, and pick the right design for a generation from its id.

GET/designsAPI Reference

Query parameters

All parameters are optional. Without any, the answer is every design, ordered by name.

Parameter	Type	Description
`query`	`string`	Words to find, in any order. Every word must appear in the design name or the project name. See Search.
`name`	`string`	One exact phrase that must appear in the design name.
`project`	`string`	One exact phrase that must appear in the project name. Several projects can match.
`project_id`	`string (uuid)`	Only designs in this project. List projects with `GET /projects`.
`type`	`string`	One type or several, comma-separated: `static`, `animated`, `printer`, `printer_multipage`. An unknown value is ignored — with none left, the full unfiltered list is returned, never a `400`.
`orientation`	`string`	`portrait`, `landscape` or `square`: designs with at least one format of that shape. See Filter by format.
`size`	`string`	`<width>x<height>`, one or several comma-separated, in the design's unit: `1080x1920`, `210x297` (mm), `8.5x11` (in).
`format`	`string`	One format name or several, comma-separated — the format id generation takes as `template_format_name`.
`updated_since`	`string`	Designs last saved in the editor at or after this date: ISO 8601, e.g. `2026-09-28` or `2026-09-28T14:00:00Z`.
`created_since`	`string`	Designs created at or after this date, same format.
`sort`	`string`	`name` (default), `updated` or `created`. See Ordering.
`order`	`string`	`asc` or `desc`. Defaults to `asc` for `name`, `desc` for the dates.
`page`	`integer`	1-based page number. Sending `page` or `per_page` turns paging on.
`per_page`	`integer`	Designs per page when paging: 25 by default, at most 100.

A parameter this endpoint does not define is ignored. A wrong value for any other new parameter answers 400 — see Errors.

Filter examples

Every filter combines with the others (a design must match all of them), and type, size and format take several values, comma-separated — a design matches any of them.

To list	Request
Designs with a story (portrait) format	`GET /designs?orientation=portrait`
Square static designs	`GET /designs?orientation=square&type=static`
Print designs only	`GET /designs?type=printer,printer_multipage`
A4 print designs	`GET /designs?size=210x297`
Designs in 1080×1080 or 1200×628	`GET /designs?size=1080x1080,1200x628`
Designs with a given format	`GET /designs?format=facebook-post,instagram-story`
Designs edited since 28 Sept 2026, latest first	`GET /designs?updated_since=2026-09-28&sort=updated`
Designs created since a moment	`GET /designs?created_since=2026-09-30T00:00:00Z`
"Black Friday" story designs, page 2	`GET /designs?query=black friday&orientation=portrait&page=2&per_page=25`

A full request — static or animated designs with a portrait format, edited since 28 Sept 2026, latest first, 25 per page:

bash

curl -G -i -H "x-api-key: {YOUR-API-KEY}" "https://api.abyssale.com/designs" \
  --data-urlencode "type=static,animated" \
  --data-urlencode "orientation=portrait" \
  --data-urlencode "updated_since=2026-09-28" \
  --data-urlencode "sort=updated" \
  --data-urlencode "per_page=25"
# X-Total-Count: <how many designs match, across all pages>

Filter by format

orientation, size and format look at a design's formats: a design matches when one of its formats satisfies all three — orientation=portrait&format=a5,facebook-post keeps the A5 designs (portrait) and drops the facebook-post ones (square).

Parameter	Matches a format	Values
`orientation`	whose height is greater (`portrait`), smaller (`landscape`) or equal (`square`) to its width	one of `portrait`, `landscape`, `square`
`size`	of exactly that size, in the design's own unit	`<width>x<height>`, several comma-separated: pixels (`1080x1920`), mm for print (`210x297`), inches (`8.5x11`)
`format`	of that name — the format `id` that generation takes as `template_format_name`	format names, several comma-separated

The listing does not return the formats themselves. To see every format of a design, with its exact size and name, use Design Details.

Filter by date

updated_since and created_since take an ISO 8601 date (2026-09-28, read as midnight UTC) or date-time (2026-09-28T14:00:00+02:00; UTC when there is no offset). updated_since is the last time the design was saved in the editor — renaming or moving it does not count.

Search

Text matching ignores case and accents. query splits on spaces and on - _ | / ·, so black friday story finds Black-Friday – Story, and summer story finds a Story design in a Summer project. At most 8 words.

name and project match one exact phrase each: name=gradient audit does not find fixture-gradient-audit, query=gradient audit does. Use query unless you need the phrase.

TIP

project can match several projects whose names share a word. To list exactly one project's designs, pass its id as project_id.

Ordering

`sort`	Orders by
`name`	Design name (the default).
`updated`	The last time the design was saved in the editor. Renaming or moving a design does not count.
`created`	The design's creation.

Use sort=updated to find someone's latest design.

Pagination

Without page or per_page the whole list comes back in one response, as before. With either, you get one page. The number of matching designs, across all pages, is always in the X-Total-Count response header.

bash

curl -i -H "x-api-key: {YOUR-API-KEY}" \
  "https://api.abyssale.com/designs?query=black%20friday&sort=updated&page=1&per_page=25"
# X-Total-Count: 66

A page past the end is an empty array; X-Total-Count still gives the real total.

Visibility

The listing returns every design in your workspace, minus:

Deleted designs — a deleted design is gone from the listing immediately.
Designs whose project was deleted — a design is only listed while its project exists.
Workspace templates — never listed here; they have their own listing. See Designs vs Workspace Templates.

Sample request

Replace {YOUR-API-KEY} before running.

cURLNode.jsPython

bash

curl -G -H "x-api-key: {YOUR-API-KEY}" "https://api.abyssale.com/designs" \
  --data-urlencode "type=static,animated" \
  --data-urlencode "orientation=portrait" \
  --data-urlencode "sort=updated"

javascript

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

const { data, error, response } = await abyssale.listDesigns({
  type: ['static', 'animated'],
  orientation: 'portrait',
  sort: 'updated',
});

if (error) console.error(error);
else console.log(data.map((d) => `${d.id}  ${d.name}`).join('\n'), abyssale.totalCount(response));

python

from abyssale import Abyssale
# Set ABYSSALE_API_KEY env var before running

with Abyssale() as client:
    designs = client.list_designs(type=["static", "animated"], orientation="portrait", sort="updated")

for design in designs:
    print(design.id, design.name)

The SDKs take every parameter on this page from @abyssale/sdk 1.7.0 and abyssale 1.5.0; type, size and format take a list there.

Response

Returns an array of design objects.

Field	Type	Description
`id`	`string (uuid)`	Unique identifier of the design.
`name`	`string`	Name of the design.
`type`	`string`	Design type: `"static"`, `"animated"`, `"printer"`, or `"printer_multipage"`.
`created_at`	`integer`	Unix timestamp of creation.
`updated_at`	`integer`	Unix timestamp of last update.
`project_id`	`string (uuid)`	Project the design belongs to. Always present — every design lives in a project.
`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`.
`preview_url`	`string (uri)`	Design thumbnail: a static PNG rendering of the design's first format (the first one created), at that format's full dimensions. Every design type gets one — an `animated` design yields a still frame, `printer` / `printer_multipage` a rasterized page. The URL is always present, but the image behind it may not exist yet for a design whose preview was never generated. Per-format previews come from Design Format Details.

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",
    "preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/a9b3c668-7b84-4924-adf0-815dae727d32.png"
  },
  {
    "id": "bdf9ab44-f5fd-47ad-881d-a45906901233",
    "name": "Summer video ads",
    "type": "animated",
    "created_at": 1663767647,
    "updated_at": 1663767647,
    "project_id": "2f6b8d10-7c31-4e59-b0a4-6c1e93f2d885",
    "project_name": "Summer 2025",
    "category_id": "2f6b8d10-7c31-4e59-b0a4-6c1e93f2d885",
    "category_name": "Summer 2025",
    "preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/f1a302g3-dd32-22f0-b640-4d519cf05266/b0c4d779-8c95-5035-beg1-926ebf838e43.png"
  }
]

Errors

`id`	When
`invalid_payload`	`project_id` (or `category_id`) is not a UUID.
`unknown_enum_value`	`orientation`, `sort` or `order` is not one of its values. The error's `expected` lists them.
`out_of_range`	More than 8 `query` words, more than 10 `type` / `size` / `format` values, or `page` / `per_page` below 1.
`wrong_type`	A `size` that is not `<width>x<height>`, a date that is not ISO 8601, or a `page` / `per_page` that is not a number.

Design Details — fetch one design's formats and elements
Projects — list the projects you can filter by
Designs vs Workspace Templates — which listing to use
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

List Designs

Query parameters

Filter examples

Filter by format

Filter by date

Search

Ordering

Visibility

Sample request

Response

Response example

Errors

Design Details

Design Import

Layer Types

Asynchronous

Element Properties

List Designs ​

Query parameters ​

Filter examples ​

Filter by format ​

Filter by date ​

Search ​

Ordering ​

Pagination ​

Visibility ​

Sample request ​

Response ​

Response example ​

Errors ​

Related ​

List Designs

Query parameters

Filter examples

Filter by format

Filter by date

Search

Ordering

Pagination

Visibility

Sample request

Response

Response example

Errors

Related