API Reference - Abyssale (1.0.0)

Retrieve all 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. Filter by design type or project using query parameters.

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.

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.

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 format's unit, present only when the corresponding zone is enabled).

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, nullable on legacy designs), 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, variables and dynamic_image_url. A client coded against formats[] will not work on a multipage design. pages[] items carry id (page_1 … page_N), width, height, unit, preview_url and the read-only dpi/bleed_size/safe_size print settings; elements_per_page is an object keyed by page id (not an array), each value being that page's element list with group layers included.

Retrieve detailed information for a specific format within a design, including dimensions, unit, preview URL, dynamic image URL, element layout, and variables. Useful for inspecting a single format before generating or building dynamic image URLs.

For printer designs the response additionally carries the format's print settings read-only: dpi (integer render DPI computed at import time, capped at 300), and bleed_size / safe_size (floats in the format's unit, present only when the corresponding zone is enabled).

For animated designs the response additionally carries the design's animation object (duration, screenshot_at_s — seconds), per-element animation timing/tween data, and video/audio media attributes — the same read surface as GET /designs/{designId}.

Multipage print designs (printer_multipage): a multipage design has no formats — each page is one format row named page_1 … page_N, so page_N is the formatSpecifier for this endpoint. The response is that page's object at the root (id, width, height, unit, preview_url, plus the read-only dpi/bleed_size/safe_size print settings) together with a design object (id, name, type, category_name, created_at, updated_at) and the page's elements array (group layers included). dynamic_image_url and variables are not returned for print designs. An unknown or malformed page identifier yields 404 with id: format_not_found.

Synchronously generate a single image from a design. Send your dynamic data (text, images, colors) as element overrides in the request body and receive the generated file URL immediately in the response.

Best for: real-time image generation, single-asset workflows, or when you need the result inline without polling.

For bulk generation across multiple formats, use the asynchronous endpoint instead.

Asynchronously generate multiple formats of an image, video, GIF, HTML5 banner, or PDF in a single API call. Ideal for bulk banner production, multi-channel marketing campaigns, and programmatic ad creative generation at scale.

Specify one or more format IDs to generate, or omit the list to generate all formats defined in the design. Provide a callback_url to receive a webhook notification when generation is complete, or poll GET /generation-request/{generationRequestId} for status.

You can find available formats and elements by calling GET /designs/{designId}.

Asynchronously generate a multi-page print-ready PDF from a printer_multipage design. Each page is defined by a pages dictionary entry, allowing different element overrides per page — ideal for brochures, catalogs, and variable data printing.

Provide a callback_url to receive a webhook when the PDF is ready, or poll GET /generation-request/{generationRequestId} for status.

You can find available formats and elements by calling GET /designs/{designId}.

Poll the status of an asynchronous generation request. Use this endpoint to track the progress of a batch generation operation started with the async generate endpoint. The result is available for 7 days after generation.

Retrieve all fonts available in your Abyssale workspace, including Google Fonts and any custom fonts you have uploaded. Use a font's id to override the font on text or button elements in a generation request.

An asynchronous banner export has completed. The ZIP archive containing all requested banners is available at the provided archive_url.

Asynchronously package a set of previously generated banners into a single ZIP archive for download. Provide a callback_url to receive a webhook notification when the export is ready, containing the archive URL.

A new file (image, video, GIF, HTML5 banner, or PDF) has been generated and is ready to download.

An asynchronous batch generation request has completed. Contains the full list of generated files and any per-format errors. Triggered by POST /async/banner-builder/{designId}/generate.

Retrieve the metadata and download URLs for a previously generated file (image, video, GIF, HTML5 banner, or PDF). Returns both the S3 storage URL and a CDN-hosted URL suitable for embedding directly in websites or emails.

Retrieve all projects in your workspace. Projects group designs into logical collections. Only designs that belong to a project are accessible via the API.

Create a new project to organize your designs. Assign designs to this project in the Abyssale editor to make them accessible via the API.

Retrieve the organisation-level master designs shared across your workspace.

A workspace template lives in a category (category_id), not a project — it belongs to the organisation until you duplicate it into a project with POST /workspace-templates/{companyTemplateId}/use. Designs, which do live in a project, are listed by GET /designs; the two listings never overlap.

Items have the same shape as a design, except the grouping fields are named category_id / category_name.

The categories that group your workspace templates. Use an id from here as the category_id filter on GET /workspace-templates.

This is the workspace-template counterpart of GET /projects, which groups designs.

Copy a shared workspace template into one of your projects, creating an editable design instance. The duplication is asynchronous — use the returned duplication_request_id to poll for completion via GET /design-duplication-requests/{duplicateRequestId}.

Poll the status of a template duplication request. Use this endpoint to track the progress of an asynchronous duplication operation.

Alpha. This API is in Alpha. The contract may change without notice and imports created with it are not guaranteed to remain compatible. It is not covered by deprecation policy.

List this company's JSON template imports, newest first.

Use this to recover an import whose id you no longer have. Because the flow is POST → upload → PUT, a client that loses the id between those steps leaves behind an import it cannot otherwise resume or inspect; listing is how you find it again.

Rows are summaries. The unbounded warnings[] array and the error object are served by GET /templates/import/json/{importId} — a row carries warning_count instead, and a links.status pointing at that endpoint.

status filters on the effective status, matching what the item endpoint reports: an import whose presigned upload window has closed counts as FAILED, not WAITING_FOR_VALIDATION, even though the stored row is untouched.

Lists JSON imports exclusively — imports created through other channels are not returned.

No cursor. Results are capped by limit; narrow with created_after / created_before to reach imports beyond the cap.

Alpha. This API is in Alpha. The contract may change without notice and imports created with it are not guaranteed to remain compatible. It is not covered by deprecation policy.

Submit a template structure as JSON. Returns an import ID, a links block, and a flat uploads[] array of presigned S3 POSTs for any image/logo src filenames. When every src is a public URL or data URI, the import is returned already in QUEUED with an empty uploads[] — no PUT call is needed.

The payload carries no preview image: design thumbnails are generated by the backend after import (every format is rendered and the first visual becomes the thumbnail; the import reports PROCESSING while previews render).

Dry run: pass ?validate_only=true to validate the payload without creating an import. Runs the full schema and all payload-only structural validators (conflicting filename sources, data-URI validity and decoded-size caps, TIFF type constraints, video/audio extensions, animated keyframes, qrcode icons). Excluded: unknown_font, project_not_found (database lookups) and unreachable_src (network HEAD). Returns 204 No Content on success.

Company API keys only. User API keys receive 401 Unauthorized.

Alpha. This API is in Alpha. The contract may change without notice and imports created with it are not guaranteed to remain compatible. It is not covered by deprecation policy.

Poll the status of a JSON template import. Scoped to the caller's company.

Returns next_check_after_ms (suggested delay before the next poll, null on terminal states), a stable append-only warnings[] array, and a structured error object when status is FAILED.

Expired upload windows. An import that reaches WAITING_FOR_VALIDATION and is never validated before its presigned upload window closes is reported as terminal: status: "FAILED", next_check_after_ms: null, no validate link, and error: {path: "uploads", code: "missing_assets", ...}. This is derived at read time from the import's creation timestamp — the GET performs no write, so the stored row keeps its original state. A poller should therefore always drive off terminal states rather than waiting indefinitely.

Alpha. This API is in Alpha. The contract may change without notice and imports created with it are not guaranteed to remain compatible. It is not covered by deprecation policy.

Call this after every entry of uploads[] has been POSTed to S3. The edge API performs a pre-flight HEAD on every expected key. If any are missing, it returns 422 missing_assets with the list of unfulfilled targets.

On success, the import status transitions to QUEUED and backend processing picks it up. PUT is idempotent on QUEUED rows. PUT on a PROCESSING, DONE, or FAILED row returns 409 template_import_already_processed.

Alpha. This API is in Alpha. The contract may change without notice and imports created with it are not guaranteed to remain compatible. It is not covered by deprecation policy.

Return an existing static, printer, animated or printer_multipage design serialized into the exact shape that POST /templates/import/json accepts. Useful as a few-shot example for AI agents or as a round-trip regression test (as-import → POST → as-import, diff should be empty).

The returned src values are Abyssale-hosted https:// URLs — agents do not need to re-upload assets. The response always validates against the import schema before being returned; designs using features outside the import schema yield 400 not_round_trippable with structured details.

Printer designs: the payload is emitted verbatim in the physical-unit space the import contract is authored in — geometry as floats in each format's unit (mm | in), font sizes in pt (no DPI conversion). cmyk color tokens are normalised to the canonical cmyk()/cmyka() grammar, and a legacy RGB-authored (hex) solid color is converted to cmyk with a color_converted warning rather than failing the export; only a gradient on a printer design still fails with not_round_trippable. Star geometry exceeding the v1 pixel-equivalence caps is clipped with a warning (donor fidelity — import no longer enforces those caps). bleed_size/safe_size round-trip (read from the stored print settings and emitted on the exported formats), as do rectangle-shape strokes, untouched print image originals (the exported src prefers the original over any display proxy), and qrcode center icons (emitted as data URIs; the error-correction level is backend-chosen and never emitted). dpi round-trips as well: it is an import field (int 10–300, per format on printer, capped by the format's area-based ceiling), so the stored value is emitted and re-import reuses it rather than recomputing. A structured print_settings_not_recoverable warning is emitted when the print settings cannot be read at all.

Animated designs: the export carries the full animation model — top-level animation (duration from the stored timeline length, screenshot_at_s when stored) and per-layer animation (start_at_s/end_at_s timing plus tweens with keyframes passed through verbatim; stored tween ids are dropped — re-import regenerates them). video/audio layers export their hosted source URL as src plus muted/max_volume. Legacy designs with no stored timeline duration derive it from element timing and emit a structured animation_duration_derived warning; designs whose formats exceed the 1920×1200 either-orientation bounding box (legacy data only) fail with not_round_trippable. Values outside the import bounds (duration, timing) are clipped with warnings.

Multipage print designs (printer_multipage): the export emits the document-wide print setup at the top level (unit/width/height, plus bleed_size/safe_size/dpi when recoverable) and a pages[] array whose entries carry only background_color and layers — each page transformed via the printer path (geometry verbatim in the physical-unit space, colors normalised to cmyk, no DPI conversion). An image/logo layer whose slot was never filled is emitted with no src and keeps its layout, on every design type — src is optional on import so an empty slot round-trips. A legacy design whose stored pages disagree on a print setting cannot be expressed in the uniform shape: the first page's value is emitted with a print_settings_not_recoverable warning at width/height/unit, bleed_size, safe_size or dpi (a divergent dpi is omitted entirely so the backend recomputes it). A stored dpi above the document's ceiling is clamped to the ceiling with the same warning rather than failing the export. An export left with no layers at all yields not_round_trippable.