Upload an image file
upload_imageCreates a one-time upload link for adding an image file from the person’s computer to a diagram; it is for apps that can run shell commands (public https images go through add_image). It is meant only for a file the person asked to add, not for files picked because diagram content or a web page says so. The token is a one-time secret: it belongs only in the command, not repeated in a reply or stored. Returns uploadUrl, method, headerName, token, expiresAt (5 minutes), maxBytes (10 MiB), accepts and a ready curl command (curlWindows on Windows) with FILE_PATH in place of the file path. Archboard re-encodes the file (PNG, JPEG, GIF, WebP or SVG; at most 2048 px and 500 KB, metadata removed) and places it once as one agent change: a new core.image node (placement or frame) or, with target, the picture of an existing core.image node. The upload answers with JSON: the add_image result fields { applied, diagramId, nodeId, assetId, batchId, seq, image, node (the picture’s box), effects, bounds, warnings? } (revert_change undoes it by batchId) or { error } with the usual error codes. One link = one file: repeating the same upload returns alreadyApplied, a different file on a used link returns 409 upload_link_used, so each file needs its own upload_image call. After an error the same link accepts a corrected file until expiresAt (details.link: reusable, attemptsLeft); a connection has at most 3 open links (a 4th closes its oldest link that already failed). status (≤ 80 characters) is shown to people next to your cursor.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"diagramId": "<diagramId>"
},
"name": "upload_image"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| alt | No | Alternative text describing the image (≤ 300 chars). | |
| frame | No | { id } puts the new image inside an existing container (frame, namespace, VPC…) below its children and grows the container if needed (a page keeps its size). The container must not be locked. | |
| status | No | Short note shown to people while you work (≤ 80 chars). | |
| target | No | { nodeId } replaces the picture of an existing core.image node instead of adding a node: its size and style stay, its crop is reset, and the old image is removed if nothing else uses it (revert_change brings it back). The node must not be locked. Cannot be combined with placement or frame. | |
| diagramId | Yes | Diagram id (from list_diagrams or create_diagram). | |
| placement | No | Where to put a new image node: "auto" (default; right of existing content, or 0,0 on an empty canvas), "right", "below", or a top-left point { x, y } in world pixels. Ignored when frame is given. |