Tools reference
Every tool the server exposes, grouped the way it's grouped in the changelog: identity, discovery, generation, and design import. Each tool's required scope and Abyssale role are noted beside it — the Owner can always use every tool regardless of role. See Permissions for a single table of what every tool can actually do before you authorize one.
Reading a design before generating from it is worth doing every time: an unknown layer or attribute name in a generation call is silently accepted and does nothing — there is no error to tell you the name was wrong.
Identity
get_me
Look up who you're signed in as and which Abyssale workspace you're connected to.
Read-only. No scope required beyond being signed in · role Admin, Manager, Designer, or Operator
This tool has no parameters.
Example
// Result
{
"user_uuid": "6b1f7e3a-2e77-4f2a-9a5b-9c1f9d6a2b10",
"company_uuid": "0e5a2c9d-8b4a-4a3d-9e6f-1a2b3c4d5e6f",
"company_name": "Acme Inc."
}Discovery
get_remaining_credits
Shows how many generation credits (image/video renders) and AI credits (text-to-image, remove-background, etc.) this workspace has left this billing period.
Read-only · scope read:credits · role Admin, Manager, Designer, or Operator
This tool has no parameters.
Example
// Result
{
"generation_credits": { "available": 842, "limit": 1000, "consumed": 158, "extra": 0 },
"ai_credits": { "available": 88, "limit": 100, "consumed": 12, "extra": 0 }
}list_designs
List the designs in your workspace, alphabetically. Use this to browse what exists, or to get a design id — the generation tools need an id, not a name. Prefer search_designs if you already know the design's name.
Excludes: designs in projects you can't open, shared workspace templates (copy them into the workspace first), designs with no project or a deleted project, and drafts.
Read-only · scope read:design · role Admin, Manager, Designer, or Operator
| Parameter | Type | Required | Description |
|---|---|---|---|
type | enum: static, animated, printer, printer_multipage | No | Only designs of this kind. |
page | integer, min 1 | No | 1-based page number. Defaults to 1. |
per_page | integer, 1–100 | No | Designs per page. Defaults to 25. |
Example
// Call
{ "type": "static", "per_page": 2 }// Result
{
"designs": [
{
"id": "8f2c1a3e-4b5d-4e6f-9a8b-7c6d5e4f3a2b",
"name": "Black Friday banner",
"type": "static",
"project_name": "Q4 Campaign",
"project_id": "1a2b3c4d-5e6f-4a3b-8c9d-0e1f2a3b4c5d",
"updated_at_ts": 1767222000,
"preview_url": "https://cdn.abyssale.com/previews/8f2c1a3e.png"
}
],
"total_count": 46,
"page": 1,
"per_page": 2
}search_designs
Find designs by name when the user describes which one they want — "the black friday banner", "my instagram design". Matches anywhere in the name, case-insensitively. name searches the design itself, project searches the campaign/folder it lives in. Returns design ids, which the generation tools require.
Read-only · scope read:design · role Admin, Manager, Designer, or Operator
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string, min 1 char | No | Text appearing in the design's name. |
project | string, min 1 char | No | Text appearing in the project name. |
type | enum: static, animated, printer, printer_multipage | No | Only designs of this kind. |
page | integer, min 1 | No | 1-based page number. Defaults to 1. |
per_page | integer, 1–100 | No | Designs per page. Defaults to 25. |
Example
// Call
{ "name": "black friday" }// Result — same shape as list_designs
{
"designs": [
{
"id": "8f2c1a3e-4b5d-4e6f-9a8b-7c6d5e4f3a2b",
"name": "Black Friday banner",
"type": "static",
"project_name": "Q4 Campaign",
"project_id": "1a2b3c4d-5e6f-4a3b-8c9d-0e1f2a3b4c5d",
"updated_at_ts": 1767222000,
"preview_url": "https://cdn.abyssale.com/previews/8f2c1a3e.png"
}
],
"total_count": 1,
"page": 1,
"per_page": 25
}list_projects
List the projects (campaigns/folders that group designs) in your workspace, alphabetically. Only projects you can open are listed.
Read-only · scope read:project · role Admin, Manager, Designer, or Operator
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string, min 1 char | No | Only projects whose name contains this text. |
page | integer, min 1 | No | 1-based page number. Defaults to 1. |
per_page | integer, 1–100 | No | Projects per page. Defaults to 25. |
Example
// Result
{
"projects": [
{ "id": "1a2b3c4d-5e6f-4a3b-8c9d-0e1f2a3b4c5d", "name": "Q4 Campaign", "created_at_ts": 1755000000 }
],
"total_count": 5,
"page": 1,
"per_page": 25
}create_project
Create a new project (folder for designs) in your workspace. Fails if a project with this name already exists — it does not overwrite one.
Mutates state — creates a new project. Scope write:project · role Admin or Manager
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string, 2–100 characters | Yes | The project's name. |
Example
// Call
{ "name": "Q1 Campaign" }// Result
{ "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "name": "Q1 Campaign", "created_at_ts": 1767312000 }list_fonts
List fonts available for text and button elements — roughly 1,149 Google Fonts (always available) plus this workspace's own custom uploads. Prefer filtering by name over browsing all of them. The returned id is the value to set under a text/button element's font attribute when generating.
Read-only · scope read:font · role Admin, Manager, Designer, or Operator
| Parameter | Type | Required | Description |
|---|---|---|---|
type | enum: google, custom | No | Only fonts of this kind. Omit for both. |
name | string, min 1 char | No | Only fonts whose name contains this text (case-insensitive). |
page | integer, min 1 | No | 1-based page number. Defaults to 1. |
per_page | integer, 1–100 | No | Fonts per page. Defaults to 25. |
Example
// Call
{ "name": "roboto" }// Result
{
"fonts": [
{ "id": "font_roboto", "name": "Roboto", "available_weights": [100, 300, 400, 500, 700, 900, "700-italic"], "type": "google" }
],
"total_count": 1,
"page": 1,
"per_page": 25
}Italic weights arrive as strings shaped like "700-italic", not a separate boolean.
get_design
Look up a design's layers and which attributes can be overridden — call this beforegenerate_static_banner rather than guessing. Works on any design type, but generation only works once type comes back static.
Read-only · scope read:design · role Admin, Manager, Designer, or Operator
| Parameter | Type | Required | Description |
|---|---|---|---|
design_id | string, min 1 char | Yes | Design id from list_designs or search_designs. |
Example
// Call
{ "design_id": "8f2c1a3e-4b5d-4e6f-9a8b-7c6d5e4f3a2b" }// Result
{
"id": "8f2c1a3e-4b5d-4e6f-9a8b-7c6d5e4f3a2b",
"name": "Black Friday banner",
"type": "static",
"formats": [
{ "id": "facebook-post", "uid": "fmt_9a1b", "width": 1200, "height": 630, "unit": "px", "preview_url": "https://cdn.abyssale.com/previews/fb-post.png" }
],
"elements": [
{ "name": "title", "type": "text", "attributes": [{ "id": "payload" }, { "id": "font" }, { "id": "color" }] },
{ "name": "background", "type": "image", "attributes": [{ "id": "src" }] }
]
}printer_multipage designs come back with only id/name/type/note — per-page detail isn't exposed by this tool; use get_design_as_import instead.
get_design_as_import
Return a design's entire structure — every format, layer, animation tween, printer bleed/safe DPI, or every page for printer_multipage designs — in the exact shape a design-import payload takes. Different from get_design/get_design_format, which trim to what generation can override: this is the full, unfiltered structure. Works on every design type, including printer_multipage. Useful for explaining how a design is built, as a worked example, or as the payload import_design_from_json accepts to recreate/duplicate the design.
Read-only · scope read:design · role Admin, Manager, Designer, or Operator
| Parameter | Type | Required | Description |
|---|---|---|---|
design_id | string, min 1 char | Yes | Design id from list_designs or search_designs. |
Example
// Result (trimmed)
{
"payload": { "name": "Black Friday banner", "type": "static", "formats": ["…"] },
"warnings": [],
"version": "1"
}get_design_format
Look up the current values, layout and overridable attributes for one format of a design, flattened. Call get_design first to see which formats and layers exist; use this once you've picked a format_specifier to see its concrete current state before overriding anything.
Read-only · scope read:design · role Admin, Manager, Designer, or Operator
| Parameter | Type | Required | Description |
|---|---|---|---|
design_id | string, min 1 char | Yes | Design id from list_designs or search_designs. |
format_specifier | string, min 1 char | Yes | A format's id (slug) or uid, from get_design's formats[]. |
Example
// Call
{ "design_id": "8f2c1a3e-4b5d-4e6f-9a8b-7c6d5e4f3a2b", "format_specifier": "facebook-post" }// Result (trimmed)
{
"id": "facebook-post",
"uid": "fmt_9a1b",
"width": 1200,
"height": 630,
"unit": "px",
"elements": [
{ "name": "title", "type": "text", "attributes": [{ "id": "payload", "value": "Up to 50% off" }] }
]
}printer_multipage designs have no formats — expect format_not_found for any format_specifier on one of those.
get_design_import_example
Returns one full worked payload for import_design_from_json's payload argument, downloaded verbatim from developers.abyssale.com's own example gallery — not hand-written. Use static-multi-format when the design needs more than one format: it's the only example that shows the format-keyed layout/properties shape a single-format example can't teach.
The same examples are also published as MCP resources under abyssale://design-import-examples/*; use this tool instead if your client doesn't surface MCP resources.
Read-only · scope read:design (no live data — bundled static examples, grouped here for consistency) · role: any signed-in role — not role-gated
| Parameter | Type | Required | Description |
|---|---|---|---|
type | enum: static, static-multi-format, animated, animated-video, printer, printer-multipage | Yes | Which example to fetch. |
Example
// Call
{ "type": "static" }// Result (trimmed)
{ "slug": "static", "title": "Static — single format", "payload": { "name": "…", "type": "static" } }Generation
Every tool in this group spends credits — see Permissions for what and how much. Call get_design (and get_design_format for one specific format) first to find valid template_format_name and elements keys — an unknown layer or attribute name is silently accepted and does nothing, with no error.
generate_static_banner
Generate a single image from a static design, synchronously — you get the file URL back immediately, no polling. Only works on static designs; animated, printer and printer_multipage designs fail with template_not_static. Rendering is capped at 10 seconds server-side; most renders finish in a few hundred milliseconds.
Mutates state, spends generation credits (amount varies — see Understanding Abyssale credits) · scope generate:banner · role Admin, Manager, Designer, or Operator
| Parameter | Type | Required | Description |
|---|---|---|---|
design_id | string, min 1 char | Yes | Must be a static design. |
template_format_name | string, min 1 char | No | Format to generate, e.g. facebook-post. Omit for the design's first format. |
elements | object of objects | No | Overrides keyed by layer name, e.g. {"title": {"payload": "Sale"}}. Every value must be an object. |
image_file_type | enum: png, jpeg, webp, avif, pdf, auto | No | Omitted/auto picks jpeg, or png for a transparent background. |
original_visual_id | uuid | No | Regenerate an existing visual in place, keeping its share URL. |
file_compression_level | integer, 1–100 | No | Higher is better quality (less compression). |
Example
// Call
{
"design_id": "8f2c1a3e-4b5d-4e6f-9a8b-7c6d5e4f3a2b",
"template_format_name": "facebook-post",
"elements": { "title": { "payload": "Up to 50% off" } }
}// Result
{
"id": "b2d4e6f8-1a3c-4e5f-8a9b-2c3d4e5f6a7b",
"version": 3,
"sharing_id": "c3d5e7f9-2b4d-4e5f-9a0b-3c4d5e6f7a8b",
"file": {
"type": "jpeg",
"url": "https://api.abyssale.com/files/b2d4e6f8.jpeg",
"cdn_url": "https://cdn.abyssale.com/files/b2d4e6f8.jpeg",
"filename": "black-friday-banner.jpeg"
},
"format": { "id": "facebook-post", "unit": "px", "width": 1200, "height": 630 }
}generate_banners_async
Generate one or more formats of a static, animated, or printer design asynchronously — video, HTML5, GIF, multi-format in one call, and AI image properties (text_to_image, remove_bg) that generate_static_banner doesn't support. printer_multipage designs aren't supported here — use generate_multipage_pdf.
By default this waits internally up to ~60 seconds and returns the finished result directly if it lands in time — most single/simple-format jobs do. If it's still not done, you get back generation_request_id with is_finalized: false; poll it with check_generation_status.
Mutates state, spends generation credits (amount varies — see Understanding Abyssale credits; and AI credits if elements uses text_to_image or remove_bg) · scope generate:banner · role Admin, Manager, Designer, or Operator
| Parameter | Type | Required | Description |
|---|---|---|---|
design_id | string, min 1 char | Yes | Static, animated, or printer — not printer_multipage. |
template_format_names | array of strings | No | Which formats to generate. Omit for every format. |
elements | object of objects | No | Overrides keyed by layer name; image elements also accept AI properties. |
image_file_type | enum: png, jpeg, webp, avif, gif, pdf, html5, mp4, auto | No | Must match the design's type. |
file_compression_level | integer, 1–100 | No | Higher is better quality. |
html5 | object: page_title, click_tag, ad_network, include_backup_image, repeat | No | Animated designs only. |
gif | object: max_fps (2–9), repeat | No | Animated designs only. |
video | object: fps (2–30) | No | Animated designs only. |
print | object: color_profile (uuid), display_crop_marks | No | Printer designs only. |
original_visual_id | uuid | No | Regenerate an existing visual in place — requires exactly one resulting format. |
callback_url | url | No | Webhook notified when done, instead of polling. Not useful from a chat session. |
wait_for_result | boolean, default true | No | false skips the internal wait and returns the id immediately. |
Example
// Call
{ "design_id": "9c3d2b1a-...", "image_file_type": "mp4", "wait_for_result": false }// Result — not finalized yet
{
"generation_request_id": "d4e6f8a0-3c5e-4f60-9a1b-4c5d6e7f8a9b",
"is_finalized": false,
"banners": [],
"errors": []
}generate_multipage_pdf
Generate a print-ready multi-page PDF from a printer_multipage design — the only generation tool that works on that design type. Pages have no id/name of their own: call get_design_as_import first and address the Nth entry of payload.pages[] here as pages.page_N (1-indexed).
Same internal wait/fallback behavior as generate_banners_async. Deliberately does not accept original_visual_id — unsafe on this endpoint.
Mutates state, spends generation credits (amount varies — see Understanding Abyssale credits) · scope generate:banner · role Admin, Manager, Designer, or Operator
| Parameter | Type | Required | Description |
|---|---|---|---|
design_id | string, min 1 char | Yes | Must be a printer_multipage design. |
pages | object of objects of objects | Yes | Per-page element overrides, keyed page_1, page_2, … (1-indexed). |
print | object: color_profile (uuid), display_crop_marks | No | Print output options. |
callback_url | url | No | Webhook notified when done, instead of polling. |
wait_for_result | boolean, default true | No | false skips the internal wait and returns the id immediately. |
Example
// Call
{
"design_id": "0d4e3c2b-...",
"pages": { "page_1": { "headline": { "payload": "Catalog 2027" } } }
}// Result — same shape as check_generation_status
{
"generation_request_id": "e5f7a9b1-4d6f-4a71-9b2c-5d6e7f8a9b0c",
"is_finalized": true,
"banners": [
{ "id": "…", "version": 1, "sharing_id": "…", "file": { "type": "pdf", "url": "…", "filename": "catalog-2027.pdf" }, "format": { "unit": "mm", "width": 210, "height": 297 } }
],
"errors": []
}check_generation_status
Check the status of a generation started by generate_banners_async or generate_multipage_pdf. is_finalized: false means still rendering — call again later rather than in a tight loop. Once is_finalized: true, every requested format is accounted for as either a success (banners) or a failure (errors, with a reason). Results are kept for 7 days; after that this answers generation_request_gone.
Read-only · scope generate:banner (same scope as the tools it polls — a client that can't generate has no legitimate reason to poll a job it couldn't have started) · role Admin, Manager, Designer, or Operator
| Parameter | Type | Required | Description |
|---|---|---|---|
generation_request_id | string, min 1 char | Yes | The id returned by generate_banners_async or generate_multipage_pdf. |
Example
// Result
{
"generation_request_id": "d4e6f8a0-3c5e-4f60-9a1b-4c5d6e7f8a9b",
"is_finalized": true,
"banners": [
{ "id": "…", "version": 1, "sharing_id": "…", "file": { "type": "mp4", "url": "…", "cdn_url": "…", "filename": "banner.mp4" }, "format": { "id": "facebook-post", "unit": "px", "width": 1200, "height": 630 } }
],
"errors": []
}Design import
import_design_from_json
Create a design (or workspace template) from a JSON structure — the same shape get_design_as_import returns. By default waits internally up to ~60 seconds and returns the finished result if it lands in time; otherwise hands back import_id with is_finalized: false for check_design_import_status to poll.
Mutates state — creates a new design or template. Scope import:design · role Admin, Manager, or Designer
| Parameter | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The design to create, in the shape get_design_as_import returns. |
validate_only | boolean | No | Check the payload without creating anything. |
strict | boolean | No | Loosen minor shape issues from hard failures to warnings. |
wait_for_result | boolean, default true | No | false skips the internal wait and returns the id immediately. |
How to supply an image
payload images can be (1) an already-hosted https URL — preferred, atomic; (2) an inline data:image/…;base64,… URI, atomic, kept to 100 KB or less; or (3) a bare filename for a file on the caller's own machine, which is not atomic — it returns WAITING_FOR_VALIDATION with one presigned upload command per layer, and only resolves once those uploads run. Prefer (1) or (2) whenever possible.
Example
// Call
{ "payload": { "name": "New banner", "type": "static", "formats": ["…"] } }// Result — created immediately
{
"import_id": "f6a8b0c2-5e70-4b82-ac3d-6e7f8a9b0c1d",
"status": "DONE",
"is_finalized": true,
"name": "New banner",
"warnings": [],
"result": { "kind": "design", "uuid": "a1b2c3d4-...", "project_uuid": "1a2b3c4d-..." }
}// Result — waiting on a local-file upload
{
"import_id": "f6a8b0c2-5e70-4b82-ac3d-6e7f8a9b0c1d",
"status": "WAITING_FOR_VALIDATION",
"is_finalized": false,
"warnings": [],
"uploads": [
{
"layer_name": "background",
"max_bytes": 5000000,
"upload_command": "curl -sf -F 'key=...' -F 'policy=...' -F 'file=@<LOCAL_FILE_PATH>' https://s3.amazonaws.com/..."
}
]
}check_design_import_status
Check the status of a design import started by import_design_from_json. WAITING_FOR_VALIDATION means at least one image upload command hasn't been run yet — run it and check again; the import proceeds on its own. Once is_finalized: true, status is DONE (result.uuid is the created design's id) or FAILED (error has the reason).
Read-only · scope import:design (same scope as the tool it polls) · role Admin, Manager, or Designer
| Parameter | Type | Required | Description |
|---|---|---|---|
import_id | string, min 1 char | Yes | The id returned by import_design_from_json. |
Example
// Result
{
"import_id": "f6a8b0c2-5e70-4b82-ac3d-6e7f8a9b0c1d",
"status": "DONE",
"is_finalized": true,
"warnings": [],
"result": { "kind": "design", "uuid": "a1b2c3d4-...", "project_uuid": "1a2b3c4d-..." }
}Upload commands from import_design_from_json stay valid for one hour from when the import was created; after that the import is dead and has to be started over.