Roastify Add Design Element
roastify_add_design_elementAdd a new element (text or image) to a design and commit a new version of it.
The store is configuration management: the element is committed back to the SAME
design_id (git tracks the diff). The new element's id comes back, so you can
immediately edit a text element by id with update_design_text, or move/reorder
either kind with move_elements.
Placement is validated server-side and REFUSED, not warned: the element must fall
inside the named panel (with a default margin — the dieline carries no real safe
area) — or, when the product has no panels (Tubes / continuous wrap), inside the
design sheet — and must not overlap any existing element (the collider's id is
named). Typography is inherited for text, so a new text element matches the
template. Image creation reuses a src already present in the design (no new asset
upload) — pass kind="image" with src_from (an existing image id) or src that
already appears on an image.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| src | No | An image src already present in this design (kind="image"); alternative to src_from. New uploads are refused — only reuse an asset already on the design. | |
| face | No | The panel to place it on — one of the `panels` from get_design_text (e.g. "right"). On multi-panel boxes the element must fall inside that panel; face is required there. On single-face products (Tubes: `panels` is empty) any face is accepted and containment uses the design's sheet bounds instead. | |
| kind | No | "text" (default) or "image". | text |
| npub | No | Required. Your Nostr public key (npub1...) for credit billing. | |
| text | No | The element's text (\n for line breaks). Required when kind="text". | |
| label | No | Rename the design (optional). Defaults to keeping its current label. | |
| width | No | The text box (wrap) width, or the image frame width, in design units. Defaults to the panel width minus margins for text; required for images when not defaulting from the donor. | |
| height | No | Image frame height in design units (kind="image" only). Defaults to the donor image's height when src_from is set. | |
| position | No | Where to place it. Either absolute {"x": N, "y": M} (top-left in design units), or relative to an existing element: {"below"|"above"|"rightOf"|"leftOf": "layer_id", "gap": G}. Relative is best when there's a sibling to anchor to; an empty panel needs absolute. | |
| src_from | No | Existing IMAGE element id whose src to copy (kind="image"). | |
| design_id | Yes | The design to add to, from roastify_list_designs. | |
| dpop_token | No | ||
| style_from | No | An existing TEXT layer id (from get_design_text) whose font, size, weight, colour, alignment, and leading the new text element inherits. Required when kind="text". | |
| version_tag | No | The NEXT semver version (MAJOR.MINOR.PATCH, e.g. 1.3.0, no 'v') — call roastify_list_design_versions and increment. Required; reusing one is refused. | |
| client_req_id | No | Your idempotency key. | |
| commit_message | No | A specific description of WHAT changed and WHY — a real commit message, not a placeholder like 'save this' or 'update'. Required. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||