Refresh a shared link
well_refresh_share_linkTake a new snapshot of a shared link made by well_share_widget or well_share_canvas, on the SAME link: whoever already holds it now sees the new figures with the new date, and it still opens until it is stopped. Call it when the person asks to update, refresh or bring up to date a link they already sent ("update the link I sent my accountant").
Name the link with exactly one of share_link_id (from the share earlier in this conversation, or from well_list_share_links) or url (the link as the person pasted it).
A link to ONE widget: Well runs the widget's tool again, as the caller, with the arguments it was shared with. Pass no
arguments: the link keeps showing the same reading, measured again. To share another reading (another period, filter or scope), make a new link with well_share_widget instead. One exception: when the widget takes the figures themselves as its arguments (a cash position, burn, runway, cash forecast, cash flow bridge, cost structure, monthly pivot, MRR or category trend card), measure them again first with that card's own skill and pass the new call'sarguments, copied exactly: running the old ones again would only re-date old figures, so that case is refused.A link to a widget that acted on the workspace (a document, an invoice, an email draft, a company or person as written) shows the one result of that call and is refused with
refused_reason: "one_result": a new snapshot would act again. Offer to share the newer result with well_share_widget, which makes a new link; the old one keeps its result until it is stopped.A link to a BOARD: measure the board the same way as for well_share_canvas (well_show_canvas, then each block's render tool over its window), and pass
versionandblocks.
A link that was stopped, or that no longer opens, cannot take a snapshot: share again to make a new link. Tell the person the link they sent now shows the new figures and still opens until they stop it. The link itself does not change and is not returned again.
When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | The shared link the person pasted. | |
| blocks | No | For a board link: one reading per block that names a feed, as for well_share_canvas. | |
| version | No | For a board link: the canvas version well_show_canvas returned. | |
| arguments | No | Only for a one-widget link whose figures are computed before the card is drawn: the arguments of a new call of that card's tool, copied exactly. | |
| 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. | |
| share_link_id | No | The id the share or well_list_share_links returned. | |
| 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| error | No | ||
| message | No | ||
| success | Yes | ||
| expires_at | No | Null: the link opens until it is stopped. | |
| computed_by | No | ||
| resolved_at | No | When the new snapshot was taken. | |
| share_link_id | No | ||
| refused_reason | 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. | |
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| 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. |