read

Create a document the merchant keeps — a report, an analysis, a comparison table, a checklist — that opens beside the co

Create a document the merchant keeps — a report, an analysis, a comparison table, a checklist — that opens beside the conversation and survives it. Use this instead of a long chat answer whenever the result is something they will come back to, share, or act on over days: a weekly performance review, a margin analysis, a launch plan, a list of products to fix. Do NOT use it for a direct answer to a direct question; that is a message. Write a specific title (a merchant will see it in a list beside twenty others), a one-line summary, and build the body out of blocks rather than one wall of prose. After creating it, say in one line what it contains and what you would do first.

post/api/v1/tools/create_artifact

Request

  • Base URL: https://app.magistry.io
  • URL: https://app.magistry.io/api/v1/tools/create_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

kind'report' | 'table' | 'chart' | 'document' | 'checklist' required

What it is, for the list icon and filter.

titlestring required

Specific enough to pick out of a list.

summarystring

One line: what it shows and over what window.

contentobject[] required

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.

Response

Tool result

okboolean required
resultunknown required

Changes

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