read

Revise an artifact you or the merchant already has, by id. The previous version is kept and stays readable, so a change

Revise an artifact you or the merchant already has, by id. The previous version is kept and stays readable, so a change is never a loss. Use this whenever the merchant asks for a change to something you made — add a column, redo it for a different window, correct a figure — rather than creating a second near-identical document. change_note is required and is what the merchant reads in the version list: say what changed and why, not "updated".

post/api/v1/tools/update_artifact

Request

  • Base URL: https://app.magistry.io
  • URL: https://app.magistry.io/api/v1/tools/update_artifact
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://app.magistry.io/api/oauth/authorize, token URL https://app.magistry.io/api/oauth/token, scopes: read)

Request body

artifact_idstring required

The id returned when it was created.

titlestring
summarystring
contentobject[]

An ordered list of blocks. Each is one of: {"type":"heading","text":"…","level":2|3}; {"type":"text","text":"markdown"}; {"type":"kpi","items":[{"label":"Revenue","value":12400,"unit":"currency","currency":"EUR","delta":{"value":8.2,"period":"vs last week","higher_is_better":true},"trend":[1,2,3]}]} (1–4 items; a single item renders as the hero figure); {"type":"table","columns":[{"key":"sku","label":"SKU"},{"key":"rev","label":"Revenue","unit":"currency","currency":"EUR"}],"rows":[{"sku":"A1","rev":120}],"caption":"…","source":{"tool":"query_performance","window":"last 30 days","rows":42}}; {"type":"chart","spec":{…the render_chart spec…}}; {"type":"callout","tone":"info|warn|crit|ok","title":"…","text":"…"}. Pick the form by the job: ONE current number is a kpi block, never a one-bar chart; a few headline numbers is one kpi block with several items; more than about seven rows of numbers that all matter is a table; a shape over time or across things is a chart. Always set unit (and currency for money), and fill in source on tables and charts so every figure can be traced back to the tool that produced it.

change_notestring required

What changed and why. Shown in the version history.

Response

Tool result

okboolean required
resultunknown required

Changes

No recorded changes to this operation across all 2 revisions of this API.