create_items
Create many items and the connectors between them in one call. Preferred way to build a diagram or a board section. For a single item the single tools remain. Each entry has a kind - label, sticky, shape, connector or image - and the fields of the matching single tool (create_item, create_shape, connect_items, upload_image; a connector's line type is lineType). Name entries with ref and attach connectors with source/target {"ref": "a"}, or to an item already on the board with {"itemId": "..."} - no round trip for ids. Items are created in entry order, connectors after all of them. The whole batch is checked first and created as one change: if any entry is invalid nothing is created and the error names its index. At most 200 entries. Returns [{ref, itemId, kind}] in entry order, each with its own warnings. At most 20 image entries (50 MB together). Labels have no background by default - pass backgroundColor for a filled text box. To put text on a shape, create the shape, then a label without background on top of it. Without textColor a label's text is dark (#1F2937) or white (#FFFFFF), whichever contrasts better with its backgroundColor, or with the canvas when it has none - pass textColor when the label sits on a shape. Colors are hex strings only - "#RRGGBB" (e.g. "#3B82F6"), or "#AARRGGBB" for alpha (alpha first). rgb()/rgba(), hsl() and named colors are rejected. The result may carry warnings: [{itemId, code, message}] for text cut off by its box (TEXT_HEIGHT_TOO_SMALL), text running into other text (TEXT_OVERLAP), text that cannot be read on what is behind it (LOW_CONTRAST), text running past the shape it starts on (OUTSIDE_PARENT_SHAPE) and text a new shape hides (TEXT_COVERED). The write happened; fix what they name before reporting the work as done.
Building a 10-node flowchart with 12 edges one tool call at a time takes 22 round trips, and every connector has to wait for the ids of both of its ends. With create_items it is one call: entries name each other with a ref, and the server resolves the refs to item ids.
Tool name: create_items
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
projectId | string | Yes | — | Target project (map) id. |
items | object[] | Yes | — | The entries, at most 200, of which at most 20 images (50 MB together). See Entries. |
parentId | string | No | Project canvas | Container for every entry. |
Entries
Every entry has a kind and the fields of the single tool for that kind:
kind | Fields | Same rules as |
|---|---|---|
label, sticky | text (required), position, size, fontSize, fontFamily, textColor, backgroundColor, horizontalTextAlignment, verticalTextAlignment, autoSize (label only) | create_item — including the transparent label background, the contrasting default text color and the sizing modes |
shape | shape (required), position (required), size (width and height), angle, fillColor, strokeColor, strokeThickness, cornerRadius | create_shape |
connector | source and target (required), lineType, strokeColor, strokeThickness, startDecorator, endDecorator | connect_items — its type is called lineType here, next to kind |
image | imageBase64 or imageUrl, fileName, mimeType, position, size (width and height) | upload_image |
Any entry can have a ref: a name of your choice, unique in the batch. A field that does not belong to the entry's kind is rejected rather than dropped — e.g. text on a shape. To put text on a shape, add a label entry on top of it.
Connector ends
source and target each take exactly one of:
{ "ref": "a" }— an entry of this batch (not another connector). It may appear anywhere in the array.{ "itemId": "11aa22bb-..." }— an item already on the board.
Validation
The whole batch is checked before anything is created, and it is created as one change. If any entry is invalid — an unknown shape, a color that is not hex, a ref that names nothing, a shape without a height — nothing is created, and the error names the entry by index and ref:
items[12] (ref "p7-end"): target.ref "nowhere" names no entry in this batch.
Items are created in entry order, connectors after all of them, so a connector can attach to an entry that appears later in the array.
If sending the batch fails after it passed validation — for example a timeout — the error says so and that the batch may still have been applied; check the board with get_project before sending it again. The board is checked when the batch is validated: if another user deletes an item a connector attaches to in the moment before the batch is applied, that connector is skipped.
Returns
The created items in entry order, whatever order they were created in:
{
"created": 3,
"items": [
{ "ref": "start", "itemId": "11aa22bb-...", "kind": "shape" },
{ "ref": "next", "itemId": "33cc44dd-...", "kind": "shape" },
{ "ref": "start-next", "itemId": "55ee66ff-...", "kind": "connector" }
]
}
An entry the batch left a layout problem for carries its own warnings. A warning about two entries of the batch sits on the later one and names the other by its index and ref, e.g. items[0] (ref "title").
Image files are uploaded once the batch exists. If an upload fails, the image item stays without its picture and the failure is listed in imageUploadErrors.
Example
"Draw the order process: received, check stock, ship — with arrows between the steps."
{
"projectId": "a1b2c3d4-...",
"items": [
{ "ref": "received", "kind": "shape", "shape": "RoundedRectangle", "position": { "x": 0, "y": 0 }, "size": { "width": 160, "height": 80 } },
{ "ref": "check", "kind": "shape", "shape": "Diamond", "position": { "x": 260, "y": -20 }, "size": { "width": 120, "height": 120 } },
{ "ref": "ship", "kind": "shape", "shape": "RoundedRectangle", "position": { "x": 480, "y": 0 }, "size": { "width": 160, "height": 80 } },
{ "kind": "label", "text": "Order received", "position": { "x": 20, "y": 28 }, "size": { "width": 120 }, "textColor": "#FFFFFF" },
{ "kind": "label", "text": "In stock?", "position": { "x": 285, "y": 28 }, "size": { "width": 70 }, "textColor": "#FFFFFF" },
{ "kind": "label", "text": "Ship", "position": { "x": 500, "y": 28 }, "size": { "width": 120 }, "textColor": "#FFFFFF" },
{ "kind": "connector", "source": { "ref": "received" }, "target": { "ref": "check" } },
{ "kind": "connector", "source": { "ref": "check" }, "target": { "ref": "ship" } }
]
}
Labels come after the shapes, so they are drawn on top of them.