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.
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. 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. |