List and search designs
Sample request
# Static or animated designs that have a portrait (story) format, edited since
# 28 Sept 2026, latest first, 25 per page.
curl -G -H "x-api-key: $ABYSSALE_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"import abyssale from '@abyssale/sdk';
const { data, error } = await abyssale.listDesigns();
if (error) console.error(error.id, error.message);
else console.log(data);from abyssale import Abyssale
with Abyssale() as client:
result = client.list_designs()
print(result)Example 200 response
[
{
"preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/a9b3c668-7b84-4924-adf0-815dae727d32.png",
"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-10-21"
}
]Example 400 error response
{
"id": "invalid_payload",
"message": "malformed id category_id",
"errors": [
{
"path": "category_id",
"code": "invalid_payload",
"message": "malformed"
}
]
}Retrieve the designs available in your Abyssale workspace. Each design defines the visual layout, available formats (dimensions), and configurable elements (text, images, shapes, etc.) that can be overridden during image generation.
Behaviour, limits and caveats
Filter by design type, project, format (orientation, size, format) or date (updated_since, created_since), search by words (query) or exact phrases (name, project), sort, and page. Every one of these is optional: without them the answer is unchanged — every design, ordered by name, as a bare array. The number of matches is in the X-Total-Count header.
A design lives in a project. Organisation-level master designs are workspace templates, live in a category, and are listed by GET /workspace-templates instead — they never appear here.
Query parameters
project_id string (uuid)
Unique identifier (UUID) of a project. Filter designs by project.
type comma-separated list of string
Filter designs by type — one, or several comma-separated (type=printer,printer_multipage). An unknown value is ignored (and with no known value left, the full unfiltered list is returned) — this never answers 400 (long-standing behavior existing integrations rely on). At most 10 items. Each one of "static", "animated", "printer", "printer_multipage".
orientation string
Only designs with at least one format of this shape. An unknown value answers 400 unknown_enum_value. One of "portrait", "landscape", "square".
size comma-separated list of string
Only designs with at least one format of this size — <width>x<height>, one or several comma-separated (at most 10), in the design's own unit: pixels for screen designs, mm or inches for print (210x297 is an A4, 8.5x11 a US Letter). At most 10 items. Each matching ^\d+(\.\d+)?x\d+(\.\d+)?$.
More about size
Only designs with at least one format of this size — <width>x<height>, one or several comma-separated (at most 10), in the design's own unit: pixels for screen designs, mm or inches for print (210x297 is an A4, 8.5x11 a US Letter). A value that is not <width>x<height> answers 400 wrong_type.
format comma-separated list of string
Only designs with a format of this name — the format id that generation takes as template_format_name. One or several, comma-separated (at most 10). At most 10 items.
updated_since string (date-time)
Only designs last saved in the editor at or after this moment: an ISO 8601 date (midnight UTC) or date-time (UTC when it has no offset). Anything else answers 400 wrong_type.
created_since string (date-time)
Only designs created at or after this moment, in the same format as updated_since.
query string
Words to find, in any order.
More about query
Words to find, in any order. Every word must appear in the design name or the project name, ignoring case and accents. Words are split on spaces and on - _ | / ·, so black friday matches Black-Friday – Story. At most 8 words; more answers 400 out_of_range.
name string
One exact phrase that must appear in the design name (case- and accent-insensitive).
project string
One exact phrase that must appear in the project name. Several projects can match; use project_id for exactly one.
sort string
updated is the last time the design was saved in the editor (renaming or moving a design does not count); created is its creation. An unknown value answers 400 unknown_enum_value. One of "name", "updated", "created". Defaults to "name".
order string
Defaults to asc (A to Z) for name and desc (newest first) for updated and created. An unknown value answers 400 unknown_enum_value. One of "asc", "desc".
page integer
1-based page number. Sending page or per_page turns paging on; without either, the listing returns every match, as it always has. Below 1 answers 400 out_of_range. Defaults to 1. Minimum 1.
per_page integer
Items per page when paging (see page). Values above 100 are treated as 100; below 1 answers 400 out_of_range. Defaults to 25. Range 1–100.
Response 200
The matching designs — every one, or one page when page / per_page is sent.
Errors
Every failure uses the shared error envelope — {id, message, errors?}. Branch on id, never on message. See Errors.
| Status | When |
|---|---|
400 | project_id is not a UUID; or a filter, search, sort or paging parameter is invalid — orientation, sort or order unknown (unknown_enum_value); more than 8 query words, more than 10 size / format / type values, or page / per_page below 1 (out_of_range); 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 (wrong_type). |
401 | Unauthorized — missing or invalid API key. |
429 | Too Many Requests. |
500 | Internal Server Error — an unexpected error occurred on our side. |