Write a canvas
well_upsert_canvasWrite one canvas: create a board, or replace the arrangement of a board that already exists.
Writes an ARRANGEMENT — the blocks a canvas holds and where they sit. It never computes a figure and never stores one: a figure block names a data feed and stores the question rather than the answer, and a note carries its own words.
CREATE — omit canvas_view_id. name, layout_mode and tiles are required, and layout_mode is "free": every board is drawn on the infinite board.
WHO EDITS — anyone in the workspace can create a board and becomes its author. Only a board's author, a workspace admin or the owner can change it afterwards; every other member reads it. well_show_canvas returns can_edit for this caller. When can_edit is false, do not call this: tell the user the board is read-only for them, name who can change it, and offer to ask its author. A write by someone else is refused with can_edit false and author_name, and changes nothing.
UPDATE — pass canvas_view_id AND the version well_show_canvas returned for it. The write is compare-and-set on that version: if the canvas moved since you read it, the call is refused and comes back carrying the canvas as stored now, so you re-apply your one change instead of overwriting somebody else's. Never guess a version and never resend a rejected one — re-read with well_show_canvas first.
STORE CARD ANSWERS — pass canvas_view_id, the version you hold, and store_card_answers, and nothing else. Each entry names a block by tile_id and a card: "exemptions" or "cash_scope". The server reads the reader's answer to that card in this conversation, and every option that card offered. It writes both into the block's binding.scope and changes no other key of any block. The write is compare-and-set on the version and returns the new version. It is refused when the reader has not answered that card in this conversation, or when a newer card is on screen than the one the reader answered.
TILES — place them yourself. h is whole cells, and x, y and w may carry a fraction of a cell, to a hundredth; send back the position and width well_show_canvas returned. A figure block may send a size instead of w and h: "S" (4 × 3), "M" (7 × 6), "L" (11 × 8), the smallest rectangle that draws that size on the board a conversation draws. S draws the figure, M and L its chart. When the user asks for a size, send it rather than guessing a rectangle. A canvas takes any non-overlapping layout at or above each block's minimum size, negative coordinates included. A layout that is not already legal is REPORTED, never repaired — nothing here moves a block whose position you stated. Use the geometry helpers in @wellapp/shared/canvas-tiles to compute the rectangles. Every block that names a feed is type "figure" with mark null: the feed decides which chart it draws. A figure block stores no params. Params sent on one are dropped, not stored, because a stored figure would stop being true the day after it is written, and the board is measured again each time it is opened. A note (type "text") carries its words as params { content }.
Do NOT use this to answer a question about a figure (ask well_render_cash_position, well_render_burn, well_render_runway), to read a board (well_show_canvas), or to change a canvas's origin template — create a new canvas for that.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | The canvas's label. Required on create. | |
| tiles | No | The blocks the canvas holds, in full. Required on create; on update it REPLACES the stored set. | |
| version | No | The version well_show_canvas returned. Required when canvas_view_id is set; refused without it. | |
| parameters | No | Canvas-wide values stored beside the blocks. No block reads them: what a block asks its feed is its own `binding`, and a window named here reaches nothing. | |
| layout_mode | No | Create only: "free", which places blocks anywhere on the infinite board. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which. | |
| canvas_view_id | No | The canvas to write. Omit to create one; pass it with `version` to change one that exists. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| idempotency_key | No | Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. | |
| origin_template_id | No | Create only: which template this canvas came from. Provenance, not identity. | |
| store_card_answers | No | Update only, with no tiles, name or parameters: the blocks that took a card answer the reader gave in this conversation, and the card each one took. The server writes the answer and the options that card offered into each block's binding.scope. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| card | No | ||
| name | No | ||
| error | No | ||
| tiles | No | ||
| created | No | ||
| refusal | No | ||
| success | Yes | ||
| version | No | ||
| can_edit | No | ||
| conflict | No | ||
| parameters | No | ||
| author_name | No | ||
| layout_mode | No | ||
| grid_columns | No | ||
| canvas_view_id | No | ||
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| origin_template_id | No | ||
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. |