Kalpana Docs

Every tool of the Kalpana designer MCP, with the arguments it takes and what it returns.

The designer MCP at https://mcp.kalpana.one/mcp/designer exposes 39 tools in five groups: Templates, Build, Check, Measure and Motion. Agents receive each tool's JSON Schema from tools/list; this page documents the same arguments for people.

page_id: the page of a template a design tool works on. create_design returns it, and pages list gives the page ids of an existing template.
template_id: the template; the batch server takes the same value as templateId.
intent: every tool that changes a design requires one short sentence of what changes and why, kept in the design's history. Reads take an optional one.
Units: positions and sizes are px in the page, relative to the parent layer. Times are seconds from the start of the page's timeline. Angles are degrees, clockwise.
Unknown fields are refused, and the error lists the valid ones.
Cost: tools marked Free cost nothing. Every other call is paid from the workspace's render credits, one credit per block of 20 calls. See Access and Cost.

Types such as fill, flow and layer are described under Shared Types.

Tool Overview

Tool	Group	Changes the design	Cost	Description
`design_guide`	Templates	No	Free	How designs, layers, inputs and the tools fit together.
`list_workspaces`	Templates	No	Free	The connected workspace and whether its designer subscription is active.
`search_templates`	Templates	No	Free	The workspace's templates, newest first or by query, with previews.
`pages`	Templates	Rename, delete	Paid	List, rename or delete a template's pages.
`duplicate`	Templates	Adds pages	Paid	Copy pages into a template or a new one, optionally at a new size.
`set_template_info`	Templates	Saves	Paid	Name and describe the template and its inputs, and save it.
`undo`	Templates	Yes	Paid	Revert a design's latest change.
`create_design`	Build	Creates	Paid	A new page at a given size and background.
`create_layers`	Build	Yes	Paid	Add a whole layer tree in one call.
`update_layers`	Build	Yes	Paid	Change many existing layers in one call.
`edit_structure`	Build	Yes	Paid	Move, delete, copy, wrap, mask, combine, scale, align and distribute layers.
`get_design`	Build	No	Paid	Every layer with its laid-out box, text, colours, flow and etag.
`list_fonts`	Build	No	Paid	Font families and styles the workspace may use.
`find_images`	Build	No	Paid	The workspace's images, by collection or file name, with a preview sheet.
`upload_images`	Build	No	Paid	Bring the user's own images into the workspace.
`check_layout`	Check	No	Paid	Overlapping text, cut-off layers, small text and low contrast.
`render_design`	Check	No	Paid	A preview PNG, zoomed to a layer, region or moment.
`calculate`	Measure	No	Free	Exact arithmetic.
`measure_text`	Measure	No	Free	Real text size, or the largest size that fits a box.
`color_math`	Measure	No	Free	Contrast, readable colours, tint scales and mixes.
`make_chart`	Measure	Yes	Paid	A chart from numbers, as editable layers.
`shape_path`	Measure	No	Paid	Exact SVG path data for shapes.
`place_items`	Measure	No	Paid	Positions for items on a circle, arc, grid, line or path.
`animate`	Motion	Yes	Paid	Motion presets, keyframes, text reveals, morphs and staggers.
`kinetic_type`	Motion	Yes	Paid	A phrase set word by word with motion.
`make_transition`	Motion	Yes	Paid	Circle, stripe, blade and burst transitions.
`camera`	Motion	Yes	Paid	A camera move across the design.
`make_particles`	Motion	Yes	Paid	A field of small shapes with motion.
`make_cursor`	Motion	Yes	Paid	A pointer that glides and clicks.
`make_list`	Motion	Yes	Paid	Rows of UI that spring in, with a moving highlight.
`make_carousel`	Motion	Yes	Paid	Cards on a 3D track inside one design.
`stagger_times`	Motion	No	Free	Start times for a cascade.
`set_timeline`	Motion	Yes	Paid	Length, frame rate and still time.
`set_choreography`	Motion	Yes	Paid	Camera moves and morphs between layers.
`edit_keyframes`	Motion	Yes	Paid	Add, move, change or delete single keyframes.
`clear_animation`	Motion	Yes	Paid	Remove motion from layers or the whole page.
`get_timeline`	Motion	No	Paid	What moves on each layer, and when.
`render_timeline`	Motion	No	Paid	The timeline drawn as a diagram.
`render_contact_sheet`	Motion	No	Paid	Frames of the animation tiled in one PNG.

Template Tools

`design_guide`

The guide to designing with this server: getting a brief, the model of designs, pages and inputs, the working loop, placing layers, structure, building for every row and size, numbers and geometry, motion, going from a design to a batch, and what to do when something goes wrong. Agents read it before their first design.

Input Parameters: None ({})
Returns: The guide as text.

`list_workspaces`

The one workspace this connection designs in, chosen when the user connected. No tool takes a workspace id.

Input Parameters: None ({})
Returns: The workspace's id, name and designer_subscription (whether its organization's plan is active).

`search_templates`

The workspace's templates, still and animated, newest first, or those matching query.

Parameter	Type	Required	Default	Description
`query`	`string`	No	—	An exact template id, or words of a name, description or campaign topic. 3 to 100 characters; omit to list the newest.
`page`	`integer`	No	`1`	Page of results, from 1.
`limit`	`integer`	No	`10`	1 to 20.

Returns: Each template's template_id, name, size, whether it is animated, a preview image URL and a link that opens it in Kalpana. pages list gives its page ids.

`pages`

Work with a template's pages. Each page is a design with its own size and layers, and its id is a page_id the design tools take.

Parameter	Type	Required	Default	Description
`action`	`"list"` \| `"rename"` \| `"delete"`	Yes	—	What to do.
`template_id`	`string`	`list`	—	The template whose pages to list.
`page_id`	`string`	`rename`, `delete`	—	The page. A template keeps at least one page.
`name`	`string`	`rename`	—	The page's new name.

Returns: list gives the template and each page's page_id, name and size. To add an empty page, use create_design with template_id; to copy pages, use duplicate.

`duplicate`

Copy pages. Each copy keeps its layers, names, motion and input descriptions, and never replaces a page or a template.

Parameter	Type	Required	Default	Description
`page_ids`	`string[]`	Yes	—	The pages to copy, in order. To copy a whole template, give all its pages from `pages` `list`.
`template_id`	`string`	No	A new template	Add the copies to this template (it can be the pages' own).
`name`	`string`	No	Source name + " copy"	The new template's name, when one is made.
`width`	`integer`	With `height`	Each page's own	Page width of each copy, 1 to 8000 px.
`height`	`integer`	With `width`	Each page's own	Page height of each copy, 1 to 8000 px.

With a new size, the flows and constraints place the layers again; render the copy and adjust what the size needs.

`set_template_info`

The name and description a template is saved with, and what each input may hold. It also saves every change still waiting to be saved, so it is the last call of a design.

Parameter	Type	Required	Default	Description
`template_id`	`string`	Yes	—	The template.
`name`	`string`	No	—	Short and specific, e.g. "Ember Roasters autumn menu".
`description`	`string`	No	—	A sentence on what it is and where it is used: intent, audience and platforms.
`inputs`	`Record<string, string>`	No	—	Layer id or name to what it holds and its length limit ("Headline: up to 2 lines, about 45 characters"). `""` clears one. Batches show these to whoever fills the rows.

`undo`

Reverts the latest change of a design.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.

Returns: The revision the design is now at.

Build Tools

`create_design`

Start a new page: a canvas of the given size with a background. It is saved in the workspace at once.

Parameter	Type	Required	Default	Description
`width`	`number`	Yes	—	1 to 8192 px.
`height`	`number`	Yes	—	1 to 8192 px.
`intent`	`string`	Yes	—	What and why.
`name`	`string`	No	`"Untitled"`	The design's name.
`background`	fill	No	White	The canvas fill; `"none"` for transparent.
`template_id`	`string`	No	A new template	Add the page as the next page of this template.

Common sizes: 1080 × 1080 or 1080 × 1350 feed post, 1080 × 1920 story, 1920 × 1080 or 1200 × 628 landscape.

Returns: The new page's page_id and its template_id.

`create_layers`

Add layers to a page, nested with their children, in one call.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`intent`	`string`	Yes	—	What and why.
`layers`	layer`[]`	No	—	The layers to add, each with `type` and optional `children`.
`parent_id`	`string`	No	The page	Frame or group to add into.
`index`	`integer`	No	End	Position among the parent's children (front-most last).
`replace`	`boolean`	No	`false`	A layer in `layers` whose `id` exists replaces that layer and its children in place, keeping the id.

Returns: The new layer ids.

Every text and image layer becomes an input of the template, labelled by its name. font_family must be one of the families list_fonts returns; any other is refused.

`update_layers`

Change existing layers. Only the fields given change; send every fix in one call.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`intent`	`string`	Yes	—	What and why.
`updates`	`object[]`	No	—	One per layer: its `id` (required) and any layer fields except `type` and `children`.
`if_match`	`Record<string, string>`	No	—	Layer id to the etag `get_design` returned. A layer changed since is refused with its current state. Not listed in the tool's schema.

To move, wrap, delete or align layers, use edit_structure.

`edit_structure`

Change the layer tree with a list of operations, applied in order.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`intent`	`string`	Yes	—	What and why.
`ops`	`object[]`	Yes	—	The operations below, each with its `op`.
`skip_missing`	`boolean`	No	`false`	Skip ids that are not on the page in `move`, `delete` and `unwrap` instead of failing the call; the result lists them in `skipped`.

`op`	Fields	Does
`move`	`ids` (required), `parent_id`, `index`	Move layers under another parent (the page when `parent_id` is omitted), at `index`. Their x/y stay relative to the new parent.
`delete`	`ids` (required)	Delete layers and everything inside them.
`duplicate`	`id` (required), `count` (1), `offset_x` (0), `offset_y` (0)	Copy a layer with its children and motion next to the original; each copy shifts by the offsets from the previous one.
`wrap`	`ids` (required), `name`, `flow`	Wrap siblings in a new group, or in a frame with a layout flow when `flow` is given.
`frame`	`ids` (required), `name`	Wrap siblings in a frame fitted around them, without a flow.
`boolean`	`ids` (required), `operation` (required: `union`, `subtract`, `intersect`, `exclude`), `name`	Combine shapes into one boolean layer that takes the bottom shape's fills; the shapes stay inside it, editable. With one boolean layer in `ids`, only its operation changes.
`unwrap`	`id` (required)	Remove a group, frame or boolean, keeping its children in its place.
`mask`	`ids` (required), `name`	Wrap siblings in a "Mask group" whose bottom layer masks the ones above it.
`unmask`	`ids` (required)	Stop layers from masking.
`scale`	`ids` (required), `factor` (required), `about` (`origin` or `center`)	Scale layers and everything inside them: size, text, spacing, radii, strokes, effects and paths.
`align`	`ids` (required), `to` (required: `left`, `center`, `right`, `top`, `middle`, `bottom`), `relative_to` (`selection` or `parent`)	Line layers up with the box around them, or one layer with its parent. Layers a flow places cannot move.
`distribute`	`ids` (required, 3 or more), `axis` (required: `x` or `y`)	Even gaps between layers; the first and last stay.
`reorder`	`id` (required), `to` (required: `front`, `back`, `forward`, `backward`)	Change paint order among siblings.

`get_design`

An outline of a page's layers after layout. Read it before changing a design.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`node_id`	`string`	No	The whole page	Describe only this layer and what is inside it.
`depth`	`integer`	No	All	Levels of children to include.
`compact`	`boolean`	No	`false`	A shorter reply, to look rather than edit.
`time`	`number`	No	`0`	The moment of an animation to describe.
`with_preview`	`boolean`	No	`false`	Also return a small picture of the page at `time`.

Returns: Each layer's id, type, name, box [x, y, w, h] in page px, text, colours, layout flow and etag, plus the fonts used.

`list_fonts`

Font families in Kalpana's library for this workspace: the global library and the workspace's uploads. Only these can be used.

Parameter	Type	Required	Default	Description
`family`	`string`	No	—	Only families whose name contains this (case-insensitive). Each family's styles are listed when 20 or fewer match.
`limit`	`integer`	No	`200`	At most this many families.

Returns: Without family, the family names; with it, each matching family's styles (style name, weight, italic).

`find_images`

The workspace's images (photos, logos, product shots), newest first, with a numbered preview sheet. Without filters the reply also names the workspace's collections.

Parameter	Type	Required	Default	Description
`collection`	`string`	No	—	Only images in this collection, by name.
`search`	`string`	No	—	Only images whose file name contains this.
`limit`	`integer`	No	`6`	1 to 12.

Returns: Each image's image key (for designs), asset_id (for batch rows), name and pixel size, and the preview sheet.

`upload_images`

Bring the user's own images into the workspace: PNG, JPEG or WebP, up to 5 MB each.

Parameter	Type	Required	Default	Description
`collection`	`string`	No	—	Collection to put them in, by name; made when it does not exist.
`files`	`object[]`	No	—	Up to 20 files the agent will upload itself: `sha256` (lowercase hex), `content_type` (`image/png`, `image/jpeg` or `image/webp`) and `size_bytes` (at most 5,242,880).
`done`	`object[]`	No	—	Up to 20 uploaded files to record: `sha256` and the file `name`.

Without files: returns a link to the workspace's Images page (or the collection's) where the user drops the images in; afterwards find_images with that collection finds them.
With files: returns an upload_url per file. PUT each file's bytes to it with that Content-Type, then call again with done. The reply gives each image's image key and asset_id.

Image data is never sent as base64. Images already on the web can be placed straight from their https URL.

Check Tools

`check_layout`

Layout problems after layout: text over other text, layers cut off by a clipping frame or running off the canvas, text too small for the size the design is seen at, and text with too little contrast on what is behind it.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`display_width`	`number`	No	See note	How wide the design is seen on screen, px; sets the smallest readable text and what counts as large text.
`margin`	`number` \| `[l, t, r, b]`	No	—	Report layers whose painted extent, strokes included, crosses this content margin.
`allow_bleed`	`string[]`	No	—	Layers (and their children) that run past the page or their clipping frame on purpose.
`ignore`	`[string, string][]`	No	—	Pairs of layer ids whose overlap is on purpose.
`craft`	`boolean`	No	`false`	Run every craft check: `orphan`, `near_touch`, `raw_hex`, `empty_frame`, `chrome_drift`, `sliver`, `empty_band` (all `info`).
`checks`	`string[]`	No	—	Craft checks to run, by name.

display_width defaults to 400 for 1080-wide square or portrait posts, 1280 for 1920 × 1080, else the page width.

Returns: Each issue with the layers it names and a severity, error or info (info is often on purpose).

It reads laid-out boxes, not pixels, and does not find text too long for a fixed box: confirm issues with render_design, and test the longest copy by rendering it.

`render_design`

A PNG of the page as it will export, for the agent to look at.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`max_size`	`integer`	No	`800`	Longest side in px, at most 800.
`sizes`	`integer[]`	No	—	1 to 4 pictures in one call, each at most 800 px, in place of `max_size`.
`node_id`	`string`	No	—	Zoom into a layer: its laid-out box grown by `padding`.
`padding`	`number`	No	`24`	Space around `node_id`'s box, in page px.
`region`	`[x, y, w, h]`	No	—	Zoom into this part of the page, in page px.
`time`	`number`	No	`0`	The second of the animation to show.
`hide`	`string[]`	No	—	Hide these layers for this picture only.
`only`	`string[]`	No	—	Show only these layers, with their children.
`mode`	`string`	No	`"color"`	`"color"`, `"grey"` for a value study, or `"silhouette"` to judge a shape (with `only`).
`sample_points`	`[x, y][]`	No	—	Points whose colour to read, returned as `{x, y, hex, alpha}`.

Returns: The PNG, with a faint repeating "Kalpana preview" mark that is never in the design, its exports or batch renders. sample_points read the design's own colours.

Measure Tools

These compute instead of guessing, so a design needs fewer renders and fixes.

`calculate`

Exact arithmetic: + - * / % ^, parentheses, pi, trigonometry in radians (rad() and deg() convert), sqrt, abs, min, max, round, floor, ceil, clamp, lerp, pow, hypot, atan2, ln, log10, exp.

Parameter	Type	Required	Default	Description
`expression`	`string`	One of these	—	One expression, e.g. `"1080 / 3 - 24"` or `"sin(rad(30)) * r"`.
`expressions`	`{name, expression}[]`	One of these	—	Several named expressions; later ones may use earlier names.
`variables`	`Record<string, number>`	No	`{}`	Values for names used in the expressions.
`series`	`object`	No	—	Evaluate `expression` over a range: `variable`, `from`, `to` and `steps` (values = steps + 1, at most 2000).

`measure_text`

The real size of text as the renderer lays it out, or the largest size that fits a box.

Parameter	Type	Required	Default	Description
`text`	`string`	No	`""`	The text to measure (or give `texts` or `runs`).
`texts`	`string[]`	No	—	Measure many texts in one call, with the same font, size and width.
`runs`	text run`[]`	No	—	Text in differently styled runs, as `create_layers` takes them, in place of `text`.
`font_family`, `font_style`	`string`	No	—	The font, e.g. `"Bold"` for the style.
`font_size`	`number`	No	—	Measure at this size, px.
`width`	`number`	No	One line	Wrap within this width, px.
`fit_height`	`number`	No	—	Find the largest size in `[min_size, max_size]` whose text fits `width` × `fit_height`.
`min_size`, `max_size`	`number`	No	—	The range `fit_height` searches.
`line_height`, `letter_spacing`	`number` \| `string`	No	—	As `create_layers` takes them.
`wrap`	`string`	No	—	`"normal"`, `"balance"` or `"pretty"`.
`min_last_line_words`	`integer`	No	—	Fewest words a wrapped paragraph may end on.
`page_id`, `layer_id`	`string`	No	—	Measure a text layer of a page as it is set; `font_size` and `width` then try other values.
`pack`	`object`	No	—	With `texts`: lay them out as chips in rows with no overlaps. `x`, `y`, `width` (required), `gap` (`[16, 16]`), `padding` (`[24, 12]`), `align` (`left`, `center`, `right`).

Returns: Each line and its width, the height, and whether the last line is a widow; with fit_height, the size that fits; with pack, each chip's box ready for create_layers.

`color_math`

Exact colour answers. Give one op with its fields, or several in ops. Colours are hex.

`op`	Fields	Returns
`contrast`	`foreground` and `background`, or `pairs` (`[foreground, background][]`)	WCAG contrast, and whether it passes for body and large text.
`readable`	`background` (required), `candidates` (default black and white)	The most readable of the candidates on the background.
`scale`	`color` (required)	A 50 to 900 scale of tints and shades, with the colour at 500.
`mix`	`from`, `to` (required), `amount` (0 to 1) or `amounts`	The colour that far from one to the other, or one per amount.

`make_chart`

A chart drawn from numbers as editable layers. Every point, bar, tick and label is computed.

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`x`, `y`, `width`, `height`	`number`	Yes	—	Where the chart sits in its parent, and its size.
`series`	`{values, name?, color?}[]`	Yes	—	The data. Colours come from `palette` when left out.
`kind`	`string`	No	`"line"`	`line`, `bar`, `area`, `step`, `horizontal_bar`, `stacked_bar`, `scatter`, `donut`, `pie`, `sparkline`, `progress_ring`, `gauge` or `radar`.
`style`	`string`	No	`"clean"`	`clean`, `minimal`, `bold`, `editorial`, `glow` (for dark backgrounds), `blocks` or `outline`.
`labels`	`string[]`	No	—	A label per value along the x axis (per bar, segment or spoke).
`palette`	`string[]`	No	Built-in	Series colours in order, as hex.
`font_family`, `font_size`	`string`, `number`	No	Size: height ÷ 22, at least 24	Every chart label's font.
`text_color`, `grid_color`	`string`	No	—	Hex.
`axes`, `x_labels`, `y_labels`	`boolean`	No	Per style	Axis labels, both or each side.
`grid`, `ticks`	`boolean`, `integer`	No	`ticks`: 4	Grid lines; `ticks: 0` removes them and the y labels.
`legend`	`boolean`	No	With 2+ series	A key of series names.
`value_labels`	`boolean`	No	—	Label the last point, each bar's top or the ring's value.
`dots`, `smooth`	`boolean`	No	Per style	A dot on each point; curved lines.
`line_width`, `bar_width`, `corner`, `thickness`	`number`	No	Per style	Line width, bar share of its slot (0.1 to 1), bar corner radius, ring thickness.
`max`	`number`	No	`100`	Full scale for `progress_ring`, `gauge` and `radar`.
`y_min`, `y_max`	`number`	No	From the data	Fix the value range.
`x_values`, `sizes`	`number[]`	No	—	Scatter: each point's x, and sizes for a bubble chart.
`step_at`	`string`	No	`"start"`	Step charts: `start`, `middle` or `end`.
`decimals`	`integer` \| `"auto"`	No	0 or 1	Decimal places in value labels.
`prefix`, `suffix`	`string`	No	—	Around every value label.
`annotations`	`object[]`	No	—	`{kind: "callout", index, text, series?}`, `{kind: "target", value, text?}` (a dashed line) or `{kind: "range", from, to, text?}` (a shaded band).
`name`, `parent_id`	`string`	No	`"Chart"`, the page	The chart layer's name and parent.

`shape_path`

Exact SVG path data for a shape, with the box it sits in. Angles are degrees, 0 at twelve o'clock, clockwise.

`kind`	Fields	Gives
`arc`	`radius`, `start`, `end`	An open arc for a stroke, such as a gauge track.
`sector`	`radius`, `start`, `end`, `inner_radius` (0)	A filled wedge; with `inner_radius`, a ring segment.
`ring`	`radius`, `inner_radius`	A circle with a hole.
`polygon`	`sides`, `radius`, `corner` (0)	A regular polygon with rounded corners.
`star`	`points`, `radius`, `inner_ratio` (0.5), `corner` (0)	A star.
`spiral`	`radius`, `turns` (3)	An Archimedean spiral.
`wave`	`width`, `amplitude`, `wavelength`, `form` (`sine`, `zigzag`, `square`)	A wave across `width`.
`gear`	`teeth`, `radius`, `depth`	A cog.
`arrow`	`from`, `to`, `bend` (0), `head` (12)	An arrow between two points; the result says where to place it.
`blob`	`radius`, `points` (6), `wobble` (0.3), `seed` (0)	An organic blob; the same seed gives the same blob.
`points`	`points` (`[x, y][]`), `smooth`, `closed`	A line through your points.
`function`	`expression` (in `x`), `x_from`, `x_to`, `width`, `height`, `samples` (200), `y_min`, `y_max`	The graph of y = f(x), scaled into the box.
`outline`	`paths`, `width`, `join`, `cap`	The filled outline of a stroke along paths.
`combine`	`paths`, `op` (`union`, `intersect`, `subtract`, `exclude`)	Paths combined in order.
`gap`	`a`, `b` (path data lists)	The smallest gap between two shapes; 0 when they overlap.
`layer_gap`	`page_id`, `a`, `b` (layer ids)	The smallest gap between two placed layers.

Returns: paths, width and height for a vector layer in create_layers.

`place_items`

Where to put N items, with each centre, the top-left for an item of item_size, and the rotation that faces along the layout.

Parameter	Type	Required	Default	Description
`count`	`integer`	Yes	—	How many places.
`layout`	`object`	Yes	—	The layout, by `kind`: `circle` (`center`, `radius`, `start` 0 = top), `arc` (`center`, `radius`, `start`, `end`), `grid` (`origin`, `columns`, `cell`, `gap`), `line` (`from`, `to`) or `path` (`points`, `closed`).
`item_size`	`[w, h]`	No	—	The items' size, to also get each top-left x/y.

Motion Tools

Layers carry keyframes on a page's timeline. This server exports no video: agents check motion as frames, and video renders in the Kalpana app or through the batch server. Build the still layout first, then add motion.

`animate`

Add motion to layers. Motion adds to what a layer has unless replace is set, and the timeline grows to fit.

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`animations`	`object[]`	Yes	—	One per layer, with the fields below.

Each animation:

Field	Type	Default	Description
`node_id`	`string`	—	Required. The layer.
`preset`	`string`	—	`fade_in`, `slide_in_up`, `slide_in_down`, `slide_in_left`, `slide_in_right`, `scale_in`, `pop_in`, `blur_in`, `spring_in`, `bounce_in`, `tilt_in`, `draw_on`, `wipe_in_right`, `wipe_in_left`, `wipe_in_up`, `wipe_in_down`, `pulse`, `float`, `spin`, `shake`, `drift`, `count_up`, `count_down`, `orbit`, `ring_spin`, `peel`, and the outs `fade_out`, `slide_out_up`, `slide_out_down`, `slide_out_left`, `slide_out_right`, `scale_out`, `blur_out`.
`start`	`number`	`0`	When the motion starts. Before it, the layer holds the preset's first value.
`duration`	`number`	`0.6`	Seconds the preset takes.
`amount`	`number`	Per preset	Strength: px for slides, float and blur; a factor for scale and pulse; degrees for spin.
`easing`	easing	Per preset	A name (`linear`, `ease`, `ease_in`, `ease_out`, `ease_in_out`, `ease_out_quart`, `ease_out_expo`, `ease_in_cubic`, `ease_in_out_cubic`, `ease_in_back`, `ease_out_cubic`, `ease_out_back`) or bezier `[x1, y1, x2, y2]`.
`tracks`	`Record<string, keyframe[]>`	—	Keyframes per property, replacing that property's keyframes. Each keyframe: `t` (required), `value`, `easing`, `hold`, `spring` (`bounce`, `floor`); `fill_color` and `stroke_color` take `color`.
`text_reveal`, `text_exit`	`object`	—	Text layers: words or letters in or out one after another: `unit` (`word`, `letter`, `sentence`), `style` (`fade`, `slide_up`, `slide_down`, `slide_left`, `slide_right`, `pop`, `typewriter`, `scramble`), `stagger`, `duration`, `distance`, `easing`.
`stagger`	`object`	—	Apply the motion to the layer's children one after another: `each` (required, seconds), `from` (`first`, `last`, `center`, `point`), `point`.
`shapes`	`string[][]`	—	Vector layers: outlines to morph between with a `shape` track.
`path`, `auto_orient`	`string`, `boolean`	—	Move along an SVG path over `duration`; turn to face along it.
`physics`	`object`	—	Drop or throw in under gravity: `from` (`[0, -600]`), `gravity` (3000), `bounce` (0.45), `throw`, `from_rotation`, `start`.
`follow`	`object`	—	Trail a moving parent on a spring: `stiffness` (180), `damping` (0.4), `sway`.
`stretch`	`object`	—	Squash and stretch with speed: `amount` (0.2), `max` (0.4).
`wiggle`	`object`	—	Smooth random jitter: `amount` (10), `frequency` (2), `rotation`, `scale`, `ramp`, `seed`.
`motion_blur`	`object`	—	Smear along the movement: `shutter` (1/60), `samples` (16).
`clock`	`object`	—	The layer's own clock for it and its children: `start`, `from`, `speed`, `repeat`, `hold_at`.
`counter_format`	`object`	—	Text with a counter track: `decimals`, `grouping`, `separator`, `decimal_point`, `step`.
`replace`	`boolean`	`false`	Clear the layer's existing motion first.

Track names and their values at rest:

Track	Unit (rest)
`translation_x`, `translation_y` (also `x`, `y`), `translation_z`	px from the layer's place (0)
`scale_x`, `scale_y`	factor about the centre (1)
`resize_x`, `resize_y`	factor that rebuilds the box, keeping radii and strokes (1)
`rotation`, `skew_x`, `rotation_x`, `rotation_y`	degrees (0)
`opacity`	0 to 1 (1)
`blur`	px (0)
`clip_left`, `clip_top`, `clip_right`, `clip_bottom`	0 to 1 of the layer's box (0, 0, 1, 1)
`path_trim_start`, `path_trim_end`	0 to 1 of the outline drawn (0, 1)
`corner_radius`, `stroke_width`	px (the layer's own)
`peel`, `peel_angle`	0 to 1 (0); degrees where the peel starts
`shadow`	factor on drop shadows (1)
`counter`	the number shown in a text layer
`text_path_offset`, `text_ring_turn`	laps along a text path; degrees a text ring turns
`motion_progress`	0 to 1 along `path`
`shape`	index into `shapes` (1.5 is halfway from the second to the third)
`fill_color`, `stroke_color`	hex, in `color`

`kinetic_type`

A phrase laid out word by word by the real text engine, with motion that gives every word its own path. Seeded, so it varies per phrase but repeats exactly.

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`text`	`string`	Yes	—	The phrase.
`x`, `y`, `width`	`number`	Yes	—	Where the block sits in its parent and how wide it may be.
`font_size`	`number`	Yes	—	px.
`font_family`, `font_style`	`string`	No	—	The font.
`color`	`string`	No	`"#111111"`	Text colour.
`align`	`string`	No	`"left"`	Line alignment.
`line_height`	`number`	No	`1.15`	A multiple of the size, or px when above 4.
`motion`	`string`	No	—	`fly`, `drop`, `scatter`, `pop`, `wave`, `glitch` or `zoom`.
`start`, `duration`, `stagger`	`number`	No	`0`, `0.7`, `0.08`	When it starts, seconds per word, seconds between words.
`exit_at`	`number`	No	—	Words fly back out in reverse at this second.
`emphasis`	`object[]`	No	—	Per word, by `index` or `word`: `color`, `font_family`, `font_style`, `scale`, `rotation`, `highlight` (a pill colour), `strike_at`.
`strike_at`, `strike_color`	`number`, `string`	No	—	Strike the whole phrase through at this second.
`seed`	`integer`	No	`0`	The variation.
`name`, `parent_id`	`string`	No	The text, the page	The group's name and parent.

Returns: The group id and the block's size.

`make_transition`

Shapes that cover or reveal the design, on top of everything.

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`style`	`string`	No	—	`circle` (rings grow from `origin`), `stripes`, `blades` or `burst` (rays, then a flood).
`part`	`string`	No	—	`out` ends fully covered at `at + duration`; `in` starts covered and reveals.
`at`	`number`	No	`0`	When it starts.
`duration`	`number`	No	`0.6`	Seconds.
`colors`	`string[]`	No	Built-in	The layers of colour, first to last.
`origin`	`[x, y]`	No	The centre	Where circles and bursts start.
`angle`	`number`	No	`-18`	Stripes: the tilt.
`count`	`integer`	No	5 stripes, 14 rays	How many stripes or rays.
`size`	`[w, h]`	No	`[1920, 1080]`	The scene's size.
`name`	`string`	No	—	The layer's name.

`camera`

Films the page's layers with a camera. The layers move into a page-sized Camera frame at the back; kinetic type and transitions stay on screen above the shot. Calling it again replaces the move.

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`stops`	`object[]`	Yes	—	Where the camera is over time: `t` (required), `zoom` (1 is the whole design), `focus` (`[x, y]` at the centre of the shot), `rotation`, `tilt_x`, `tilt_y`, `easing` (`ease_in_out`), `spring`.
`ids`	`string[]`	No	Every top-level layer except transitions	The layers the camera films.

`make_particles`

A region filled with small shapes spread by a seed, behind the other layers unless front is set.

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`region`	`[x, y, w, h]`	Yes	—	The area they live in, in the parent.
`count`	`integer`	Yes	—	1 to 400.
`shapes`	`string[]`	No	dot, ring, sparkle	`dot`, `ring`, `star`, `plus`, `cross`, `pill`, `square`, `triangle`, `blob`, `sparkle`.
`motion`	`string`	No	—	`float`, `twinkle`, `burst` (from `origin`), `rain`, `rise`, `pop` or `still`.
`palette`	`string[]`	No	Built-in	Colours as hex.
`size`	`[min, max]`	No	`[6, 28]`	Particle sizes, px.
`opacity`	`[min, max]`	No	`[0.5, 1]`	Opacity range.
`depth`	`number`	No	`0.2`	Share pushed out of focus, 0 to 1.
`avoid`	`[x, y, w, h]`	No	—	A box kept clear, such as behind a headline.
`start`, `duration`, `until`	`number`	No	`0`, `1.2`, start + duration + 4	When motion starts, how long the arrival takes, when floating stops.
`strength`	`number`	No	`14`	How far they drift, px.
`origin`	`[x, y]`	No	The region's centre	Burst: where they fly from.
`front`	`boolean`	No	`false`	Put the field on top.
`seed`	`integer`	No	`0`	The same seed gives the same field.
`name`, `parent_id`	`string`	No	`"Particles"`, the page	The group's name and parent.

`make_cursor`

A pointer that glides through stops with eased moves; each click presses and spreads a ripple. It sits on top.

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`stops`	`object[]`	Yes	—	At least one: `x`, `y` (where the tip is), `t` (when it arrives), `click` (`false`).
`style`	`string`	No	—	`arrow`, `pill` (with `label`) or `dot` (a touch).
`label`	`string`	No	—	Pill style: the name on it.
`color`, `ripple`	`string`	No	Near-black, the cursor colour	Colours.
`size`	`number`	No	`40`	Arrow size, px.
`name`	`string`	No	—	The layer's name.

`make_list`

Rows of UI with text and an optional value on the right. Rows spring in one after another and a highlight slides between rows at the select times; pair it with make_cursor clicks.

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`items`	`{text, value?}[]`	Yes	—	The rows; `value` is shown on the right ("312", "+4%").
`x`, `y`, `width`	`number`	Yes	—	Top-left of the list and its width.
`select`	`{index, t}[]`	No	—	The highlight's path: the row and when it arrives.
`numbered`	`boolean`	No	`false`	Number each row, for ranked lists.
`static`	`boolean`	No	`false`	A still list or table built as layout flows, with no motion or highlight.
`row_height`, `gap`	`number`	No	`64`, `10`	Row height and the gap between rows, px.
`start`, `stagger`	`number`	No	`0`, `0.07`	When rows start arriving, and the seconds between them.
`fill`, `color`	`string`	No	White, near-black	Row fill and text colour.
`accent`, `accent_text`	`string`	No	—	Highlight fill and the text colour on it.
`divider`	`string`	No	—	Static lists: a hairline under each row in this colour.
`font_family`, `font_size`	`string`, `number`	No	—	The font.
`name`, `parent_id`	`string`	No	—	The group's name and parent.

`make_carousel`

Cards on a track that step to the next card every step seconds, neighbours swung back in 3D. An animation inside one design; an Instagram carousel is one page per slide instead.

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`items`	`{image?, title?, subtitle?}[]`	Yes	—	The cards; `image` is an `https` URL.
`center_x`, `y`	`number`	Yes	—	Centre of the focused card, and the top of the cards.
`card_width`, `card_height`	`number`	No	`720`, `940`	Card size.
`radius`	`number`	No	6% of the width	Card corner radius.
`start`, `step`, `move_duration`	`number`	No	`0`, `0.5`, `0.35`	When the first card is centred, seconds per card, seconds per move.
`tilt`	`number`	No	`58`	Degrees the neighbours swing back.
`side_scale`, `side_shade`	`number`	No	`1`, `0.12`	Neighbours' size and how much they fade.
`gap`	`number`	No	−2% of the width	Space between a neighbour and the centre card.
`enter`	`boolean`	No	`true`	Slide the carousel up into place just before `start`.
`card_fill`, `art_fill`, `color`, `subtitle_color`	`string`	No	White, `#F4F4F4`, near-black, `#8A8A8A`	Colours.
`font_family`, `name`, `parent_id`	`string`	No	—	The font, the group's name and parent.

`stagger_times`

Start times for N items that cascade. Free.

Parameter	Type	Required	Default	Description
`count`	`integer`	Yes	—	How many items.
`start`	`number`	No	`0`	The first start.
`step`	`number`	One of these	—	Seconds between starts.
`total`	`number`	One of these	—	Seconds from the first start to the last.
`ease`	`string`	No	`"linear"`	`linear`, `in`, `out` or `in_out`: how the gaps shrink or grow.

`set_timeline`

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`duration`	`number`	No	—	The page's length in seconds.
`fps`	`number`	No	—	Frame rate.
`still_time`	`number`	No	The last frame	The second a still image of the page shows, where all its content is in place. Image batches use it unless the batch gives its own. A negative value clears it.

`set_choreography`

Camera moves and morphs between layers, in their stored format.

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`choreography`	`object`	Yes	—	The stored format (read the current value with `get_timeline`); `{}` clears it. A `flow` alone (slides in order joined by transitions, under `stage` and `steps`) is compiled into the camera and morphs it plays. Validated before saving; the timeline grows to fit.

`edit_keyframes`

Tune existing motion one keyframe at a time. Edits apply in order; if one cannot apply, none do.

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`edits`	`object[]`	Yes	—	The edits below.

`op`	Fields	Does
`add`	`node_id`, `track`, `t`, `value` (required), `easing`, `hold`	Add a keyframe, or replace the one at the same time.
`update`	`node_id`, `track`, `at` (required), `t`, `value`, `easing`, `hold`	Change the keyframe at `at`: move it, or change its value, easing or hold.
`delete`	`node_id`, `track`, `at` (required)	Remove the keyframe at `at`.
`shift`	`node_id`, `by` (required), `tracks`, `from`	Move a layer's whole motion, and that of the layers inside it, by `by` seconds.

`clear_animation`

Parameter	Type	Required	Default	Description
`page_id`, `intent`	`string`	Yes	—	The page, and what and why.
`node_ids`	`string[]`	No	Every layer	The layers to clear.
`tracks`	`string[]`	No	All motion	Only these properties; `shape` removes a shape morph with its outlines.

`get_timeline`

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`node_ids`	`string[]`	No	—	Layers (or groups, for the layers inside) whose keyframes to return.
`detail`	`boolean`	No	`false`	Each keyframe as `{t, value, easing, hold}` instead of `[t, value]`.

Returns: Without node_ids, an overview of what moves on each layer and when; with them, their keyframes, and the choreography's stored value.

`render_timeline`

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`node_ids`	`string[]`	No	Every animated layer	Only these layers (or groups).
`properties`	`boolean`	No	`true`	A row per property under each layer.

Returns: A diagram: a time ruler, a row per animated layer with a bar over its motion, keyframe diamonds per property, and where the motion ends.

`render_contact_sheet`

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`frames`	`integer`	No	`12`	Frames evenly spaced from `start` to `end`, at most 32.
`times`	`number[]`	No	—	1 to 32 exact seconds, in place of `frames`.
`start`, `end`	`number`	No	`0`, the end	The range.
`columns`	`integer`	No	`4`	Frames per row, at most 8.
`cell_width`	`integer`	No	`320`	Width of each frame, at most 320 px.

Returns: One PNG of the frames, left to right and top to bottom, and the times shown. For one moment at full preview size, use render_design with time.

Shared Types

Layer fields

The fields of a layer in create_layers and of a change in update_layers. Only type is required, and only on create.

Field	Type	Description
`type`	`string`	`frame` (a box with children and an optional flow), `group`, `text`, `rectangle`, `ellipse`, `line`, `image` or `vector`.
`id`	`string`	An id you choose, unused on the page; generated when omitted.
`name`	`string`	The layer's name, and the input's label in batches. Name layers by role ("Headline", "CTA").
`children`	layer`[]`	Create only: the layers inside a frame or group.
`x`, `y`	`number`	Position relative to the parent. Ignored inside a flow unless `absolute`.
`width`, `height`	`number`	Size.
`rotation`	`number`	Degrees clockwise about the centre.
`visible`, `opacity`	`boolean`, `number`	Visibility; opacity 0 to 1.
`blend_mode`	`string`	`normal`, `darken`, `multiply`, `color_burn`, `linear_burn`, `lighten`, `screen`, `color_dodge`, `linear_dodge`, `overlay`, `soft_light`, `hard_light`, `difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity`, `pass_through`, `print_light`.
`constraints`	`{horizontal, vertical}`	How the layer follows a resized parent: horizontal `left`, `right`, `center`, `left_right`, `scale`; vertical `top`, `bottom`, `center`, `top_bottom`, `scale`. Not for layers a flow places.
`absolute`	`boolean`	Inside a flow: take the layer out of it and place it by x/y.
`flow`	flow	Frames: arrange the children in a row or column.
`padding`	`number` \| `[v, h]` \| `[t, r, b, l]` \| `{top, right, bottom, left}`	Frames: inner spacing.
`clip`	`boolean`	Frames: hide children that overflow.
`sizing`	`{horizontal, vertical}`	Inside a flow: each `fixed`, `hug` (fit the content) or `fill` (the space left).
`min_width`, `max_width`, `min_height`, `max_height`	`number`	Limits for hug and fill sizing; 0 clears one.
`fill`	fill	One fill, replacing all fills; on text, the text colour. `"none"` removes fills.
`fills`	fill`[]`	Several fills, painted bottom to top.
`stroke`	stroke	Outline; `width: 0` removes it.
`radius`	`number` \| `[tl, tr, br, bl]`	Corner radius.
`shadows`	`{x, y, blur, spread, color, inner}[]`	Replaces the shadows; `[]` removes them. Colour defaults to `#00000040`.
`blur`, `background_blur`	`number`	Blur of the layer, or of what is behind it (frosted glass), px; 0 removes it.
`mask`	`string`	Mask the layers above in the same parent: `alpha`, `vector`, `luminance`, `alpha_inverted`, `luminance_inverted` or `none`.
`glass`, `noise`, `texture`, `progressive_blur`	effect	Liquid glass, film grain, torn edges, and a blur that grows across the layer.
`text`	`string`	Text content, as one run in the current style.
`runs`	text run`[]`	Differently styled runs (one highlighted word). Each run has `text` and any text style field below.
`font_family`, `font_style`, `font_weight`, `font_size`, `italic`	`string`, `string`, `integer`, `number`, `boolean`	The font. `font_family` must come from `list_fonts`; `font_style` such as "Bold Italic", or `font_weight` 100 to 900.
`font_axes`	`Record<string, number>`	Variable-font axes, e.g. `{"wght": 640}`; `{}` clears them.
`color`	`string`	Text colour as hex; wins over `fill` on text.
`gradient`	gradient	A gradient on the text instead of a solid colour.
`line_height`	`number` \| `string`	px (4 or more), a percentage like `"120%"`, or `"auto"`.
`letter_spacing`	`number` \| `string`	px, or a percentage of the size like `"-2%"`.
`align`, `vertical_align`	`string`	`left`, `center`, `right`, `justified`; `top`, `center`, `bottom`.
`text_sizing`	`string`	`fixed` (wraps and clips), `auto_height` (wraps, grows down) or `auto_width` (one line, grows to fit).
`shrink_to_fit`	`boolean` \| `{min_scale}`	Text in a fixed box: shrink until it fits, down to `min_scale` of the size (0.5).
`wrap`	`string`	`balance` evens line widths (headlines), `pretty` avoids a one-word last line, `normal` fills lines.
`min_last_line_words`	`integer`	Fewest words a paragraph may end on.
`max_lines`	`integer`	Most lines shown.
`text_case`	`string`	`original`, `upper`, `lower` or `title`.
`decoration`, `decoration_style`	`string`	`underline`, `strikethrough`, both, or `none`; `solid`, `dotted`, `dashed`, `wavy`, `double`.
`list`, `paragraph_spacing`, `paragraph_indent`	`string`, `number`, `number`	Paragraphs as `bullets`, `numbers` or `none`; space before each, and first-line indent, px.
`figures`, `features`	`string`, `object`	Digit style (`default`, `lining`, `oldstyle`, `tabular`, `tabular_lining`); OpenType `ligatures`, `contextual_alternates`, `fractions`, `superscript`, `subscript`.
`text_effect`	`{preset, color?, intensity?}`	One-click effect on text: `shadow`, `lift`, `hollow`, `splice`, `echo`, `glitch`, `neon`, `outline`, `sticker`, `gradient`, `background` (create only: a pill behind the text) or `none`. `intensity` 1 by default. The text stays one layer.
`text_path`	`boolean` \| `{path, start}`	Lay the text along an SVG path; `false` removes it.
`ring`	`boolean` \| `{radius, tilt, perspective, back_opacity, start}`	Lay the text on a ring in perspective; `false` removes it.
`image`	`string`	Image layers: a key from `find_images`, or an `https` URL (copied into the workspace).
`fit`	`string`	`fill` (cover, cropping), `fit` (inside, leaving space), `stretch` or `tile`.
`zoom`, `focus`, `tile_scale`	`number`, `[x, y]`, `number`	Zoom into the image (1 as fitted); the point to centre, 0 to 1; tile size as a multiple of the image.
`filters`	`object`	Photo adjustments, each −1 to 1: `exposure`, `contrast`, `saturation`, `temperature`, `tint`, `highlights`, `shadows`.
`paths`	`string[]`	Vector layers: SVG path data in the layer's own px, one per sub-shape. `width` and `height` are the box of the data.

Fill

A fill is one of:

A colour: "#FF5A1F", "#FF5A1F80", "white" or "none"; or {color, opacity}.
A gradient, flat or as {gradient: {...}}: type (linear, radial, angular, diamond), stops (required: colours spread evenly, or {color, at} with at 0 to 1), angle (linear: 0 left to right, 90 top to bottom), from and to (linear points), center, radius (0.5 touches the edges), repeat (none, repeat, mirror) and opacity. Points are fractions of the layer's box.
An image: {image, fit, zoom, focus, opacity, tile_scale, filters}, with image an https URL or a key.

Flow

A frame's layout flow arranges its children; fields left out keep their values.

Field	Values
`direction`	`row`, `column`, `wrap` (a row that wraps), or `none` to remove the flow.
`gap`, `row_gap`	Space between children, and between rows of a wrap, px.
`align`	Along the flow: `start`, `center`, `end`, `space_between`, `space_around`, `space_evenly`.
`cross_align`	Across the flow: `start`, `center`, `end`, `stretch`, `baseline`.
`row_align`	Wrap only: `start`, `center`, `end`, `space_between`, `space_around`.
`width`, `height`	`fixed` keeps the frame's size; `hug` grows and shrinks with the children.

Stroke

width (px; 0 removes it; a new stroke defaults to 1), color (a new stroke defaults to black) or gradient, align (inside, center, outside), dashes ([6, 4]; [] is solid), cap (none, round, square), join (miter, round, bevel), miter_limit, and sides ([top, right, bottom, left] widths, such as [0, 0, 2, 0] for a bottom rule).

Effects

Each effect takes its settings, true for the defaults, or false to remove it.

Effect	Settings (defaults)
`glass`	`depth` (24), `refraction` (0.5), `dispersion` (0.2), `radius` (8, frost), `light_angle` (0), `light_intensity` (0.72)
`noise`	`kind` (`mono`, `duo`, `multi`), `color` (`#00000040`), `second_color`, `density` (0.5), `size` (1), `opacity` (1)
`texture`	`size` (4), `depth` (4), `clip` (true), `self_only` (false: fray only a frame's own fill)
`progressive_blur`	`radius` (required), `start_radius` (0), `from` (`[0.5, 0]`), `to` (`[0.5, 1]`), `background` (false)

Designer Tools Reference

On this page