artifacts_create
Host a self-contained HTML page at a stable, default-private, shareable URL — the Artifact experience, in-app.
Pass exactly one of:
html— the full page: your<body>plus any<style>/<script>. Unlike documents.create, the page is served live (JavaScript runs), so charts, interactivity, and small tools work.file_id— a workspace file whose contents are already the HTML page.analytics_card_ids— ids of saved analytics dashboard cards; the platform re-runs their queries and composes one designed report page (static charts, snapshot at build time). Best way to give someone a shareable analytics report.
The page runs in a locked-down sandbox: a dedicated origin + a strict CSP. That means it is fully self-contained — it CANNOT call out to the network (fetch/XHR/WebSocket are blocked; the one exception is the press counter below, which the platform adds itself). Scripts, styles and fonts may load from cdnjs.cloudflare.com, cdn.jsdelivr.net/npm/, unpkg.com, cdn.tailwindcss.com and code.jquery.com (always pin an exact version, e.g. Chart.js from cdnjs), fonts also from Google Fonts; nothing else. Images must be inline data: URIs. A PDF export renders offline with JavaScript off: anything loaded from a CDN (scripts, CSS, fonts, Tailwind) is missing there, so a page meant for PDF keeps its CSS inline and draws charts as inline SVG.
Counting presses. To know what visitors press on a shared page, put data-track="<name>" on the element (a link, a button, or anything around them): <a href="https://wa.me/..." data-track="whatsapp">. Each press is recorded with its name and time and read back with artifacts.get (events). From a script, DialogBrain.count("<name>") does the same. A name is one word: letters, digits and _ . : -, up to 64 characters, no spaces; a page may use up to 100 different names. Write each name as a literal in the page (data-track="whatsapp", DialogBrain.count("whatsapp")): only names written that way are counted, one a script builds at run time is not. Nothing about the visitor is recorded, so give each person their own page when you need to know WHO pressed. Presses made inside the app's own viewer are not counted.
access_level defaults to 'private' (viewable only in-app). Set 'shared' to make the unguessable link itself the capability (anyone-with-link). You can flip this later with artifacts.set_access.
Returns {artifact_id, slug, url, app_url, version, access_level}. app_url always opens for workspace members, in the app. url is the public link and is set ONLY for a shared artifact (a private one has no public page: handed out bare, the public link answers "not available"). Republish with artifacts.update — both links stay the same.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"title": "<title>"
},
"name": "artifacts_create"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| html | No | Full self-contained HTML page. Mutually exclusive with file_id. | |
| title | Yes | Short human-readable title (page <title> + gallery label). | |
| favicon | No | Optional emoji used as the browser-tab icon (e.g. '📊'). | |
| file_id | No | Workspace file whose contents are the HTML page. Mutually exclusive with html. | |
| template | No | Optional data-driven template: HTML with {{placeholder}} tokens. When set, later artifacts.refresh(data={...}) re-renders the page server-side from tiny data payloads (no HTML round-trip) — ideal for a scheduled agent that refreshes live numbers. The initial html you pass should be this template already rendered with today's values. | |
| description | No | Optional one-line summary for the gallery card. | |
| access_level | No | 'private' (default, in-app only) or 'shared' (anyone-with-link). | private |
| in_workspace | No | Run this one call in this workspace id instead of the session's. Nothing is stored; other sessions are not affected. | |
| analytics_card_ids | No | Compose saved analytics dashboard cards into one report page: each card's SQL re-runs through the guarded analytics engine and renders as a static chart. Data is a snapshot at build time. Mutually exclusive with html/file_id. |