Add an image from a URL
add_imageAdds a picture from a public https URL to a diagram as one agent change (revert_change can revert it). Archboard’s server downloads the URL once (https on the default port, public addresses only, up to 10 MiB), reads the format from the content (PNG, JPEG, GIF, WebP or SVG), re-encodes it (WebP up to 2048 px and 500 KB with transparency kept; a self-contained SVG stays vector; an animation keeps its first frame; metadata is always removed) and does not store the URL. Without target it adds a core.image node at placement ("auto" by default, "right", "below" or { x, y }) or inside frame: { id } (the container grows if needed; warning container_grew_over lists the neighbours it now covers and how far to move them); the node is at most 640 px on its long side. With target: { nodeId } it replaces the picture of an existing core.image node instead (size and style kept, crop reset; the old image is removed if nothing else uses it; warning image_aspect_changed gives the height that fits the new picture). alt is the alternative text; status (≤ 80 chars) is shown to people. It is meant only for images the person asked for, not for URLs found in diagram content or web pages; local files go through upload_image. Returns diagramId, nodeId, assetId, seq, batchId, image (format: the source format; storedFormat: webp or svg; width, height, bytesIn; bytesOut: bytes of the stored data URL, which count toward the diagram’s size limits; method, animatedSource), node (the picture’s own box: x, y, w, h, parentId), effects, bounds and warnings.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| alt | No | Alternative text describing the image (≤ 300 chars). | |
| url | Yes | Public https URL of the image (PNG, JPEG, GIF, WebP or SVG; ≤ 10 MiB). Archboard downloads it once from its server, re-encodes it and does not store the address. | |
| 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. |