Kalpana Docs

`design_guide`

The guide to designing with this server. Without topics it returns a short core: how templates, pages and flows fit together, the working loop, what calls cost, the rules for every design, and the list of topics. Agents read the core before their first design, then ask for the topics the job needs in one call.

Parameter	Type	Required	Default	Description
`topics`	`string[]`	No	—	Topics to return instead of the core, in this order.

Topic	Covers
`brief`	Gathering a brief for products, services, apps, local businesses, events and brands
`ad`	The step-by-step procedure for an ad
`formats`	Angles and ad formats
`copy`	Copy budgets, formulas, CTAs, platform limits
`structure`	Units, stacks, layout flows, page patterns, naming
`sizes`	Ratio families, size plans, safe zones, shared input limits
`colour`	Palettes, value structures, contrast
`type`	Font pairings, scale, prices, Indic scripts
`imagery`	Cutouts, scenes, people, screenshots, designs without images
`effects`	Gradients, shaders, grain, scrims, shadows, badges, text effects
`lettering`	Extrude, outlines, contours, warps and cuts for display type
`numbers`	Charts, shapes, curved text, items on a path, measurements
`critique`	Glance, value and layout checks, generic tells, batch stress test
`reference`	Rebuilding or matching a reference design
`carousel`	Carousels and series
`motion`	Animating a page
`flows`	Videos made from pages
`batch`	Handing a template over to batches
`limits`	Known engine limits and workarounds

Returns: The core, or the topics asked for, as text. Free.

`get_workspace`

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 workspace_id, name, slug, subscribed (whether its organization's plan is active) and allowed_image_domains, the hosts an image URL may come from, subdomains included. An image URL on another host is refused until an admin adds the domain in Workspace Settings > Domain Whitelisting.

`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. list_pages gives its page ids.

`list_pages`

List 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
`template_id`	`string`	Yes	—	The template, from `search_templates` or `create_design`.

Returns: The template's id, name and description, and each page's page_id, name, size and whether it is animated. To add an empty page, use create_design with template_id; to copy pages, use duplicate.

`rename_page`

Rename one page of a template.

Parameter	Type	Required	Default	Description
`page_id`	`string`	Yes	—	The page.
`name`	`string`	Yes	—	The page's new name.

Returns: The page's page_id and new name. To name the template itself, use set_template_info.

`delete_pages`

Delete one or more pages of a template, with their layers and motion. Every page is checked first: an unknown id, or deleting every page of a template (a template keeps at least one), refuses the whole call and nothing is deleted. Deleted pages cannot be brought back, not even with undo.

Parameter	Type	Required	Default	Description
`page_ids`	`string[]`	Yes	—	1 to 20 pages.

Returns: The deleted page_ids and their template_ids.

A deleted page also leaves every flow that visits it. A flow left with no pages stays, empty, under its name.

`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 `list_pages`.
`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.
`fixed`	`Record<string, boolean>`	No	—	Layer id or name to `true` to keep it as designed, not a batch input (slide numbers, arrows, labels that never change), or `false` to make it an input again.

`undo`

Reverts the latest change of a design. Free.

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

Returns: The revision the design is now at.

`send_feedback`

Feedback from the agent to the people who build these tools: a tool, its arguments or the design guide that was confusing, missing something or wrong, or that worked well. Agents call it when a tool blocks them and once after set_template_info with anything they have to report or suggest. It holds no user content and changes nothing in the design.

Parameter	Type	Required	Default	Description
`kind`	`"confusing"` \| `"missing"` \| `"bug"` \| `"guide"` \| `"worked_well"`	Yes	—	What sort of feedback it is.
`tools`	`string[]`	No	`[]`	The tools it is about; empty for the guide or the connection as a whole.
`what_happened`	`string`	Yes	—	What the agent tried and what happened. Up to 1000 characters.
`what_would_help`	`string`	No	—	What would have helped. Up to 1000 characters.
`page_id`	`string`	No	—	The page the agent was working on.

Returns: { "received": true }.

Templates and pages