Archboard

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

add_image

Creates a diagram in a workspace (requires editor access and at least the write permission there; permission is in list_workspaces). workspaceId may be left out when the connection can write to only one workspace. Optionally adds initial content in the same call, one of: ops (same rules as apply_ops; temporary "$" ids are returned in idMap), a Mermaid flowchart (same as compose_diagram: types / layout / direction; returns nodeIds, groupIds and edgeIds), or an infographic spec (same as compose_diagram infographic: returns posterId, nodeIds, blocks, quota and layout; the diagram font is set to the theme’s font). There is no dryRun: every call creates a diagram (compose_diagram dryRun with preview checks a drawing on an existing diagram without writing). The plan’s diagram limit applies (Free: 3 diagrams).

create_diagram

Adds a new drawing to an existing diagram as one agent change (revert_change can revert it). It only adds shapes: it never changes, moves, reconnects or removes what is already on the canvas; changes to existing shapes, such as inserting a node between two existing ones or renaming one, are made with apply_ops. The drawing is either a Mermaid flowchart (subgraphs become frames, or containers such as network.vpc when you map their ids; map ids, classes or "@shape" to node types with types; unmapped nodes become core.box; options layout, direction ("auto" picks the readable one), frame), or an infographic spec (infographic: theme + blocks; each block is { block, …the node type’s props }, e.g. header, kpi-row, chart, progress, funnel, timeline, process, icon-grid, versus, source) that the server measures and lays out on a 12-column poster — the spec gives data and order, not coordinates. Pie, xychart, timeline, quadrantChart and venn Mermaid diagrams become infographic blocks. It takes exactly one of mermaid and infographic. dryRun checks without writing; with dryRun, preview "light" or "dark" also returns a PNG (a poster exactly as export_diagram draws it). read_me topic "infographics" describes the blocks. Returns applied, seq, batchId, effects, bounds and warnings; Mermaid adds nodeIds, groupIds, edgeIds ("A->B" → edge id) and frameId plus the direction used, an infographic adds idMap, posterId, nodeIds, blocks (node ids and bounds), quota and layout, and each infographic warning’s fix says which span, field or poster size to change. status (≤ 80 characters) is shown to people next to your cursor.

compose_diagram

Applies ops to a diagram as one atomic change (revert_change can revert it). Ids starting with "$" are temporary: the server assigns real ids and returns idMap. New records with caller-chosen ids make a retry after a lost response safe: a repeated batch then fails with id_taken and writes nothing (get_canvas shows what was written). References to temporary ids (parentId, source/target, props.assetId and "asset:$id" strings) are resolved at the end of the list, but ops that change or remove a record need it to exist at that point (added earlier in the list). A *.set or *.remove whose target is not there is dropped (effects.dropped, warning missing_target). If nothing changes (every op dropped, or the values were already there) nothing is written: applied false, noop true, reason (unchanged, dropped or skipped), seq unchanged. dryRun checks the batch, including embedded images, custom shapes and infographic data, against the current state without writing (isError true when it would be rejected; wouldCreate counts the new records); with dryRun, preview "light" or "dark" also returns a PNG of the custom shapes, drawings and infographic blocks (or the whole poster, as export_diagram draws it) the batch touches. People may edit at the same time; each field keeps the last write. baseSeq (the seq read with get_canvas or returned by the last write) reports which fields others changed since then (effects.conflicts, also for records a node.remove deletes with it; warning concurrent_edit); onConflict "skip" keeps their values. Warning node_being_edited means a person is typing in that node right now. A core.vector node takes one source in props: svg, elements, fromIcon, libraryRef or fromImage (read_me topic "shapes"). A palette key from search_node_types (such as infographic.chart::donut) works as the node type; chart data can be sent as data.rows, data.csv or Chart.js labels and datasets (read_me topic "infographics"). Returns applied, seq, batchId, idMap, effects (dropped / cascaded / pruned…, lists cut to the first 20 with a <name>Count), bounds of the touched nodes, images (embedded images the server re-encoded, if any), vectors (converted shapes), infographics (converted variants and data, applied themes) and warnings: layout lint plus props that have no effect (unknown_prop with a suggestion, invalid_prop_value with the allowed values, unknown_type, icon_not_found with close icon names); the change is applied anyway. Edge style and animation keys are in read_me topic "style". status (≤ 80 characters) is shown to people next to your cursor.

apply_ops

Exports the diagram, or one frame (frameId: the frame and everything inside it), as a PNG or SVG file and returns a download link for the person. Returns { downloadUrl, expiresAt, maxDownloads, downloadsLeft, reused, filename, mimeType, bytes, width, height, scale, requestedScale, seq, watermark, watermarkSource, watermarkStyle, watermarkPosition, externalImageCount, externalImageNodeIds, warnings }. The link downloads the file (it is not an inline image) until expiresAt (15 minutes), for up to 5 downloads, and anyone with the link can use it until then. Calling again with the same arguments while the diagram is unchanged returns the same open link (reused: true, with downloadsLeft) instead of a new file. PNG: scale 1–4 pixels per diagram unit (default 2), long edge up to 3072 px; scale in the result is the pixels per unit actually used, and warnings lists png_scale_capped (size limit) or png_size_reduced (file size limit) when it is lower than requested (for a large diagram, a frameId or format svg gives a sharper file). SVG: a still image unless animate is true. Files always have the theme’s opaque background and a fixed margin; PDF and JPEG files, a transparent background and custom margins are made in the editor (Share → Export). watermark adds the Archboard watermark; it is always added when the organization’s plan requires it (watermarkSource "plan"). watermarkStyle and watermarkPosition choose its look and corner; warnings lists watermark_style_adjusted when the requested style was replaced by badge. PNG is drawn by the same renderer as render_snapshot, with the same limits: external and AVIF images render as placeholders, colour emoji render in one colour, text inside nested SVG images is not drawn. In SVG, external and AVIF images are placeholders. When images point to a web address, warnings lists external_images_placeholder with externalImageCount and externalImageNodeIds (add_image imports them).

export_diagram

Returns one node type: label, pack, defaultSize, quotaClass, defaultProps, editableProps, styleProps, ports, whether it is a container (can be a parentId target), nameKey (the prop that names the node), uiFamily, its palette variants (paletteVariants: id, key, label, props) and, when declared, a JSON Schema of its props. editableProps[].ui.control is how the Archboard panel edits a field (date: YYYY-MM-DD text; multi-select: comma-separated option values); without it the input type applies. styleProps lists the style keys this type draws (e.g. accent, background, textColor, icon); other style keys are saved but not shown. A variant key (type::variant, from search_node_types) returns that variant’s defaults. Infographic types also return example (placeholders that show the data format, not real data), limits (soft: readable range; hard: rejected above) and sizing. detail: "compact" returns only the fields needed to write the props (for infographic blocks: propsSchema, composeExample, limits, sizing, styleProps). Every node type also accepts `props.fontFamily` (read_me topic "style", Fonts).

get_node_type

Returns what the person you act for has selected in their open editor tabs for this diagram: selection (node / edge ids), items (the first 20 selected records: kind, the node type or the edge ends, and the label) and tabs (each tab's selection and visible viewport). Empty when the diagram is not open.

get_selection

Lists diagrams this connection can access, most recently updated first, each with its permission (read, write or delete: what this connection may do with it, as in list_workspaces). Filters by workspaceId or a title query; pages with cursor (nextCursor) and limit (≤ 50). Node and edge counts are not included (get_canvas outline has them).

list_diagrams

Lists the organizations this connection can use, with your role, the plan, and their workspaces. The person may limit a connection to some organizations or workspaces (access.mode "restricted"); the others are not listed. Each organization and workspace has a permission (read: view only; write: also create and edit; delete: also move diagrams to the trash) that combines the person’s setting for this app, your role and the plan; it is null on an organization when only some of its workspaces are allowed. brandPalette is true when an organization has a saved brand palette, which infographic brand: true uses (without one, colours go in palette).

list_workspaces

Moves a diagram to the trash at the person’s request; the person can restore it in Archboard. It cannot delete permanently, and it is meant only for a diagram the person asked to delete. It needs the delete permission (permission in list_workspaces / list_diagrams) and editor access. Returns trashed, diagramId, title, deletedAt and userMessage (a confirmation for the person, in their language).

delete_diagram