Edit without the AI

POST /api/v1/diagrams/:id/edits makes exact changes directly, as the canvas editor makes them: retype a label, recolour a box, a line or its text, change a font or size, hide or show a part, move a part, put it beside another, swap two, line parts up or space them evenly. It does not use the AI, answers in a few seconds, costs no credits, saves the result as the next version, and does not count as a new AI diagram. For anything else (new content, a different layout) ask for a change instead. Wording is matched by the text itself. Everything else names parts by their ids, from the parts list:

curl "https://app.diagramkit.ai/api/v1/diagrams/DIAGRAM_ID/parts?page=1" -H "Authorization: Bearer $DIAGRAMKIT_KEY"

# {"diagram_id": "…", "version": 3, "page": 1, "layouts": {"wide": 900, "compact": 390}, "truncated": false, "inner": 48,
#  "parts": [
#   {"id": "node:api", "kind": "node", "summary": "node \"API\"; to \"Cache\", \"Database\"; 2 in; movable; 6 inner parts",
#    "text": "API", "movable": true, "inner": 6, "wide": [361, 148, 79, 105], "compact": [176, 163, 63, 84]},
#   {"id": "node:db", "kind": "node", "summary": "node \"Database\"; 2 in; movable; 4 inner parts", …},
#   {"id": "link:api->db", "kind": "link", "summary": "link \"API\" -> \"Database\"; 2 inner parts",
#    "link": {"from": "api", "to": "db"}, "wide": [431, 187, 104, 119], "compact": [53, 204, 131, 247]}, …]}

A part’s id comes from what it is, so it stays the same through edits, and through a change from the AI that keeps the part:

Id	What it names
`node:<id>`	A part diagramkit placed, by the id the diagram gives it (`node:api`).
`link:<from>-><to>`	A connection, with its line and arrowheads (`link:api->db`).
`note:<words>`, `text:<words>`, `box:<words>`	A note, free-standing words (a title, a label, a caption) or a box, by its words (`text:monthly-revenue`).
`cell:<id>`, `cell:<row>/<col>`	A placed cell by the id of the part in it; a table cell by row and column (`cell:0/2` is the second header).
`mark:<series>/<category>`	A chart’s bar or point (`mark:revenue/2024`), a whole line by its series, a pie slice by its id.
`<owner>/<kind>`	Something inside one of those: a node’s words (`node:api/text`), an icon’s shapes (`node:api/shape#2`), a link’s `line` and `head`.

Two parts with the same name are told apart in the order the diagram draws them: text:total, text:total#2. A part’s position (0/2/1, its path) is accepted too. By default the list has what a person points at: nodes (with their words), links, notes, cells, chart marks, titles and labels. Each has its kind (node, cell or note for parts diagramkit placed; link; mark; text, line, shape or box), a one-line summary, its first 40 characters of text, inner (how many parts sit inside it), and its box [left, top, width, height] in pixels in the wide layout (desktop, 900 px wide, as image.png draws it) and, where it shows, the compact layout (phone, 390 px). movable marks the parts that move; hidden marks a hidden part; offset is a moved part’s current offset per layout. detail=true lists what sits inside them too, each with its tag, its path and moves_with, the placed part it moves with. A large diagram lists its first 400 parts and says truncated.

curl https://app.diagramkit.ai/api/v1/diagrams/DIAGRAM_ID/edits \
  -H "Authorization: Bearer $DIAGRAMKIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": [{"before": "Cache", "after": "Redis cache"}],
       "place": [{"part": "node:db", "relative_to": "node:cache", "side": "below"}],
       "restyle": [{"part": "link:api->db", "style": {"stroke": "#d92d20"}}]}'

# The job, as GET returns it, with what was applied, what was skipped and where each moved part is now:
# {..., "version": 4,
#  "applied": [{"before": "Cache", "after": "Redis cache", "places": 1}],
#  "skipped": [],
#  "moved": [{"part": "node:db", "wide": [505, 260, 86, 105]}]}
# places is how many times the text appeared and was changed.

Parameter	In	Values	Default	What it does
`text`	body	up to 30 objects: `{"before", "after"}`	`[]`	Each replaces one label or line of text. `before` is the text exactly as it appears in the diagram (up to 600 characters); `after` is what it should say. Also accepted as `edits`.
`restyle`	body	up to 100 objects: `{"part", "style"}`	`[]`	`style` sets any of `fill`, `stroke`, `color`, `background-color`, `font-family`, `font-size` (4 to 400 px), `font-weight` (`normal`, `bold`, 100 to 900) and `visibility`. `fill` colours a shape, or a box’s background; `color` its text. On a link, `stroke` (or `color`) colours its line and arrowheads; on a chart mark, `fill` its shape; on a node, `color` its words. Values are plain CSS: colours (`#0b5fff`, `rgb()`, `hsl()`, `var(--…)`), lengths and font names; anything else is refused. An empty value takes back an earlier change. A fill that leaves text on it hard to read re-colours that text from the diagram’s own colours, as the canvas does.
`hide`	body	up to 100 part ids	`[]`	Hide parts.
`show`	body	up to 100 part ids	`[]`	Show parts hidden earlier with `hide`.
`nudge`	body	up to 100 objects: `{"part", "dx", "dy", "layout"}`	`[]`	Shift a movable part (or the one a part sits in) `dx`, `dy` pixels from where it is now; right and down are positive.
`place`	body	up to 100 objects: `{"part", "relative_to", "side", "gap", "layout"}`	`[]`	Put a movable part `left`, `right`, `above` or `below` another part, `gap` pixels away (default 40), centred on it across that side. The other part need not move.
`swap`	body	up to 50 objects: `{"a", "b", "layout"}`	`[]`	Exchange two movable parts’ positions, centre for centre.
`move`	body	up to 100 objects: `{"part", "layout", "dx", "dy"}`	`[]`	Set a movable part’s offset from where diagramkit placed it, -4000 to 4000 pixels. `0, 0` puts it back.
`align`	body	`{"parts", "to", "layout"}`	none	Line up two or more placed parts with each other: `to` is `left`, `center` or `right` (across) or `top`, `middle` or `bottom` (down).
`distribute`	body	`{"parts", "axis", "layout"}`	none	Space three or more placed parts evenly between the first and the last: `axis` is `horizontal` or `vertical`.
`page`	body	1 to 100	`1`	Which page of a multi-page diagram; part ids are per page.
`styles`, `moves`	body	the canvas editor’s own form	`[]`	What the web app’s canvas sends: styles by element position, moves by part key. Prefer the fields above.

layout is wide (desktop, the default), compact (phone) or both (each layout the part has). Lines follow a part that moves. Send at least one edit. Moves apply in this order: move, nudge, place, swap, align, distribute, each measuring the parts where the earlier ones left them, and the result’s moved gives each moved part’s new box per layout, so there is no need to list the parts again. A layout a diagram does not have (one drawn the same on desktop and phone has only wide) is refused with a message saying which to use. Edits apply to the latest version, and wording is matched exactly, case included. Text the diagram works out from data, such as a chart’s axis values or a computed total, cannot be retyped: change the data with a revision. An unknown part id (the message lists ids of that kind), a part that cannot move, a part placed beside itself, or a change that would break the diagram answers 422 not_applied naming the part and the reason, and the diagram is left as it was. A diagram being made or changed answers 409 conflict.

Get started

Diagrams

Guides

More