Reference
Formats
Every artifact format: what each holds, how it is checked, how it renders, and its limits.
OverviewLink to this section
Every artifact has one kind. It decides how the content is checked when it is saved and how the page shows it. Pick the simplest kind that fits: Markdown for prose, html for anything visual or interactive (a mockup, a prototype, a dashboard, a report with charts), file for anything uploaded. The ui and canvas kinds are earlier formats, kept for the artifacts that use them.
| kind | Name | For |
|---|---|---|
| markdown | Markdown | Readable prose with headings, lists, tables, and links. |
| html | HTML | A web page with its own styles and scripts. It runs in a sandbox. |
| code | Code | Source code in monospace. Set the language to label it. |
| text | Text | Plain text, shown as written. |
| json | JSON | Data, pretty-printed. The content must be valid JSON. |
| csv | CSV | A table. The first row names the columns. |
| svg | SVG | A vector image. Scripts inside it never run. |
| mermaid | Mermaid | A diagram drawn from Mermaid source. |
| ui | Interface | An earlier format: a dashboard or report built from our components. For a new page, choose HTML. |
| canvas | Canvas | An earlier format: a board of screens built from our components. For a new mockup, choose HTML. |
| file | Files | Images, PDFs, documents, video, and audio, with optional notes. |
Content is checked on every save, from MCP and the web app alike. Agents can check it first, without saving, with artifacts_validate. Changing the kind of an existing artifact checks the stored content against the new kind.
Every format can also have a theme, which sets the colors and fonts of the artifact and its page. A web page (html) sets its own inside its frame. See Themes.
Size limitsLink to this section
| Limit | Value | Applies to |
|---|---|---|
| Content | 1,048,576 bytes (1.0 MB) | Every kind, in UTF-8 bytes. An HTML page's document counts whole, with the styles and scripts written in it; its page files do not. Split larger work into several artifacts. |
| Metadata | 65,536 bytes (64 KB) | The metadata object, as JSON text. |
| ui spec | 200,000 bytes (195 KB) | ui content and each frame of a canvas, plus element and depth limits. |
| Canvas | 800,000 bytes (781 KB) | canvas content: up to 24 frames and 3,000 elements across them. |
| Mermaid source | 50,000 characters | mermaid content. |
| File | 26,214,400 bytes (25 MB) | Each upload. Up to 100 files in a document's text, and 20 attached files, per artifact. |
| Page files | 16,777,216 bytes (16 MB) | The files an HTML page loads by relative path: up to 100 per artifact, on top of its other files. |
MarkdownLink to this section
GitHub-flavored Markdown, shown as formatted prose. Raw HTML is not rendered. A fenced code block with the language mermaid draws as a diagram, so keep diagrams in the document. Uploaded images, video, audio, and files embed as  on its own line; artifacts_formats_guide with kind "markdown" explains how.
| kind | markdown |
| Saves when | Any non-empty text. |
| Shows as | GitHub-flavored Markdown: tables, task lists, strikethrough, and autolinks. Raw HTML is skipped. A fenced code block with the language mermaid draws as a diagram with the Mermaid format's renderer; if it cannot be drawn, the source shows as code with a short note. Attributes in braces after the language set how it shows: mermaid {view=split} shows the source and the diagram side by side (stacked on phones), {view=code} only the source, and {view=preview}, the default, only the diagram. Any fenced code block takes a caption shown under it, {caption="How a change ships"}, and {wrap=true} to wrap long lines. Uploaded files embed as  on their own line: images, video and audio players, PDFs, and download cards, with a caption from the title and a width option (artifacts_formats_guide explains each form). A paragraph, heading, list item, or quoted line that ends in a color comment, such as <!-- color: red; background: yellow -->, shows in that text color and background (gray, brown, orange, yellow, green, blue, purple, pink, or red, in light and dark). Images from other sites do not load; they show as their alt text. Links must be http, https, or mailto, and open with rel="nofollow ugc". |
# Billing migration plan
- [x] Dual-write behind `billing.ledger_v2`
- [ ] Backfill 2025 invoices
| Step | Owner |
| --- | --- |
| Backfill | @dana |HTMLLink to this section
A full web page: one HTML document with its own CSS and JavaScript, shown running in a sandbox. Use it for anything visual or interactive: mockups, prototypes, dashboards, reports, explainers. It must start with <!doctype html>. Read artifacts_formats_guide with kind "html" before writing one.
| kind | html |
| Saves when | Must start with <!doctype html>. It is one full page: its styles and scripts are inside it, or in page files it loads by relative path. It is not sanitized, because it only ever runs in a sandbox. |
| Shows as | The page itself, running, in a sandboxed frame on a separate page host: one host per artifact, apart from this site, your session, and every other artifact. Inline scripts and styles run. Scripts, styles, fonts, and images may also load from cdnjs.cloudflare.com, cdn.jsdelivr.net, unpkg.com, esm.sh, cdn.tailwindcss.com, code.jquery.com, and Google Fonts, and from the page's own page files (stylesheets, scripts, images, fonts, and data that agents upload with a path such as css/site.css, many in two calls); every other request is refused, forms cannot be posted, and the page cannot open frames or navigate the tab. The page may keep data in the browser (localStorage). Links open in a new tab. Where no page host is set up, the source shows instead. |
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Launch countdown</title>
<style>
body { margin: 0; display: grid; place-items: center; min-height: 100vh; font: 16px system-ui; }
output { font-size: 3rem; font-weight: 700; }
</style>
</head>
<body>
<main>
<p>Days until launch</p>
<output id="days"></output>
</main>
<script>
const launch = new Date("2027-01-15");
document.getElementById("days").textContent = Math.max(0, Math.ceil((launch - Date.now()) / 86400000));
</script>
</body>
</html><h1>Launch countdown</h1>
→ - Error: An HTML artifact is a full page: it must start with <!doctype html>.Page filesLink to this section
An HTML artifact can be a whole small site, not one long document. Its page loads its own stylesheets, scripts, images, fonts, and data by relative path, as on any web host, so the document stays short and each file changes by itself. Agents put the files in with two calls, however many there are. People drop them on the page, or a whole folder, in the web app.
- Paths are relative to the page, which is
index.html:css/site.css,js/app.js,img/logo.png. Folders and a file name of letters, digits, dots, dashes, and underscores, joined by/. No leading slash and no... - A path is matched exactly, letter case included, so use lowercase. Two files whose paths differ only by case are refused.
- The type comes from the extension. An
.htmlfile is another page of the site (see below);.htmis refused, so name it.html. - Readers get the files of the version they are shown. On a link or public artifact, added and replaced files reach readers outside the team when the change is approved. Removed files stop loading for everyone at once.
- A page left open keeps working. Its files load under an address that works for 10 to 15 minutes; while its tab is visible, and for one hour after it was hidden, the page gets the next address before that, without loading again. A tab hidden for longer stops asking, and gets its next address when it is shown again. One limit remains: a module that already loaded keeps its first address for its own later
import(), and a stylesheet file for its ownurl(). Import what a module needs when it starts, or resolve a later import from the document:import(new URL("js/chart.js", document.baseURI)).
A site of several pages. The artifact's content is the first page, index.html. Every other page is a page file whose path ends in .html, such as about.html or docs/guide.html, linked with an ordinary relative link: <a href="about.html">.
- It opens in the same frame. A link, or
location.hrefin a script, moves the frame to that page, and the browser's Back and Forward move between the pages. The page host never serves the page as a document of its own: the frame loads its text and writes it in, as it writes the first page. - Every page follows the same rules as the first: the same hosts, the same refusals, and its own files by relative path from its own folder. Start each with
<!doctype html>; a page without it still shows, in the browser's quirks mode. - A page that has no file shows a line that says so, with a link to the first page. A folder's address, such as
docs/, is no page: link todocs/index.html. A link to a folder leaves the frame, which is then closed. - What is not there yet: a link from this site straight to a page inside the frame, a list of the pages beside the frame, and search over the text of pages other than the first.
| Extensions | Served as | Name |
|---|---|---|
| .html | text/plain, written into the frame | HTML page |
| .css | text/css | Stylesheet |
| .js .mjs | text/javascript | Script |
| .svg | image/svg+xml | SVG image |
| .json | application/json | JSON |
| .map | application/json | Source map |
| .txt .md | text/plain | Text |
| .csv | text/csv | CSV |
| .woff2 | font/woff2 | Font |
| .woff | font/woff | Font |
| .ttf | font/ttf | Font |
| .otf | font/otf | Font |
| .wasm | application/wasm | WebAssembly module |
| .png | image/png | PNG image |
| .jpg .jpeg | image/jpeg | JPEG image |
| .gif | image/gif | GIF image |
| .webp | image/webp | WebP image |
| .avif | image/avif | AVIF image |
| .mp4 | video/mp4 | MP4 video |
| .webm | video/webm | WebM video |
| .mp3 | audio/mpeg | MP3 audio |
| .wav | audio/wav | WAV audio |
| Limit | Value |
|---|---|
| Page files per artifact | 100 |
| All page files of one artifact | 16,777,216 bytes (16 MB) |
| One page file | 26,214,400 bytes (25 MB) |
| Path | 200 characters, 8 parts (folders and the file's name) |
| Uploads started by one page_files_request_uploads call | 50 |
| Uploads, and removals, named in one page_files_publish call | 100 |
| Uploads waiting to finish, per person, when a call asks for a set | 200 |
| Page file uploads started with page_files_request_uploads | 1,000 per hour, per person, counted per file |
| Upload URL lifetime | 10 minutes |
| A page's files address | Works for 10 to 15 minutes. Renewed 2 minutes before it ends while the page's tab is visible, and for one hour after the tab was hidden, without loading the page again. |
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Launch plan</title>
<link rel="stylesheet" href="css/site.css">
</head>
<body>
<h1>Launch plan</h1>
<ul id="milestones"></ul>
<script type="module" src="js/app.js"></script>
</body>
</html>css/site.css
body { font: 16px/1.5 system-ui; margin: 2rem; }
js/app.js
const milestones = await (await fetch("data/milestones.json")).json();
data/milestones.json
[{ "name": "Beta", "date": "2027-01-15" }]Adding page files in the web appLink to this section
Anyone who may edit an HTML artifact adds files from its page, in the workspace or on the artifact's own page: drop files or a folder anywhere on the page, or use Add files in the More menu or Add folder beside the list.
- Each file goes where its type belongs. A type in the table above becomes a page file. Any other file the site takes, such as a PDF, is attached beside the page as before.
- A folder keeps its shape. Dropping
site/that holdscss/site.cssandimg/logo.pngadds those two paths. Hidden and system files, such as.DS_Store, are left out. - A zip is unpacked. A
.zipyou drop or pick is unpacked in your browser and added exactly as the folder it holds would be. - A path that cannot be used says why. A name with a space or capital letters gets a cleaned path to take or change, and nothing is added under a name you did not see.
- One drop is one change. Up to 100 files land together as one version in History, or not at all. A file at a path the page has replaces it, and the row says so before it happens.
- The page itself. An
index.htmlat the top of a dropped folder can become the page's HTML, after you confirm. The HTML it had stays in History. Every other.htmlfile in the drop is another page of the site, added at its path like any page file.
CodeLink to this section
Source code shown in monospace. Set language, for example typescript.
| kind | code |
| Saves when | Any non-empty text. language (up to 60 characters) labels it. |
| Shows as | Monospace, as written, with the language as a caption. There is no syntax highlighting. |
export function retryAfter(seconds: number): string {
return `Try again in ${seconds} s.`;
}TextLink to this section
Plain text, shown as written.
| kind | text |
| Saves when | Any non-empty text. |
| Shows as | As written, with line breaks kept, in the page's column. |
Standup notes, 6 Nov
Shipped: docs shell
Next: MCP referenceJSONLink to this section
A JSON document, pretty-printed. It must parse.
| kind | json |
| Saves when | Must parse as JSON. |
| Shows as | Pretty-printed with two-space indent. Content that does not parse shows as written, under a warning. |
{ "service": "billing", "p95Ms": 182, "regions": ["eu-west-1", "us-east-1"] }{ "service": "billing", }
→ - Error: The content is not valid JSON: Expected double-quoted property name in JSON at position 24 (line 1 column 25).CSVLink to this section
CSV (RFC 4180) with a header row, shown as a table of up to 1,000 rows.
| kind | csv |
| Saves when | RFC 4180 CSV with a header row. Quotes must close. |
| Shows as | A table with row numbers and a sticky header. Readers sort by clicking a column header and filter from the search box or a column's menu; neither changes the file. Shows up to 1,000 rows and 50 columns and says how many it left out. Editors get a spreadsheet-style grid, with a Raw view for the text. |
service,p95_ms,errors
billing,182,3
search,95,0service,note
billing,"never closed
→ - Error: A quoted field never closes. Check for a missing closing quote.SVGLink to this section
An SVG document that starts with <svg>. Shown as an image: scripts and external loads never run.
| kind | svg |
| Saves when | Must start with an <svg> element (an XML declaration or comments may come first) and close with </svg>. It is not sanitized, because it is only ever shown as an image. |
| Shows as | An <img> with a data: URI on a checkerboard. Scripts, event handlers, and external loads never run. A missing xmlns is added. |
<svg viewBox="0 0 120 40" xmlns="http://www.w3.org/2000/svg">
<rect width="120" height="40" rx="8" fill="#1f6feb"/>
<text x="60" y="26" text-anchor="middle" fill="#fff">ready</text>
</svg><div>not an svg</div>
→ - Error: SVG content must start with an <svg> element (an XML declaration or comments before it are fine).MermaidLink to this section
Mermaid diagram source that starts with its type, such as flowchart TD or sequenceDiagram. Use it for a diagram that stands alone; for a diagram inside a document, put a fenced code block with the language mermaid in the Markdown instead.
| kind | mermaid |
| Saves when | Up to 50,000 characters, and the first line (after front matter and %% comments) must name a diagram type. Finer syntax errors show when it renders. |
| Shows as | Mermaid loads in the browser only when needed and draws in strict security mode with plain-text labels. The result shows as an image, so nothing in it can run. |
flowchart LR
agent[Coding agent] -->|artifacts_create| server[MCP server]
server --> page[Artifact page]agent --> server
→ - Error: Mermaid source must start with a diagram type such as flowchart TD, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram, gantt, pie, or mindmap.Interface (ui)Link to this section
An earlier format, kept for artifacts that already use it: a json-render spec on the artifacts.space component set. For a new mockup, dashboard, or report, prefer kind "html", a full web page. Read artifacts_formats_guide with kind "ui" before changing one.
| kind | ui |
| Saves when | A JSON Render spec that passes validateUiSpec: known components, valid props, a tree from the root, and the size limits. |
| Shows as | The stout component set, the same for every reader. Links follow the link policy and images come only from the artifact's own files. |
{ "version": 1, "root": "page", "elements": { "page": { "type": "Heading", "props": { "text": "Hello" } } } }{ "version": 1, "root": "page", "elements": { "page": { "type": "Gauge", "props": {} } } }
→ - Error: Element "page": unknown component "Gauge". Use one of: Section, Stack, Grid, Card, Tabs, Accordion, Separator, Box, Heading, Text, Markdown, Code, Callout, Badge, List, Steps, Link, Quote, Icon, Avatar, AvatarGroup, Kbd, Rating, Table, Metric, Chart, KeyValue, Progress, Timeline, Diagram, Board, Calendar, Checklist, Checkbox, Select, Switch, Slider, Button, Input, Textarea, Image, File, Placeholder.CanvasLink to this section
An earlier format, kept for artifacts that already use it: a board of frames, each one screen that holds a json-render spec on the artifacts.space component set. No HTML or CSS. For a new mockup, dashboard, or report, prefer kind "html", a full web page. Read artifacts_formats_guide with kind "canvas" before changing one.
| kind | canvas |
| Saves when | A JSON object with a list of frames that passes validateCanvas: up to 24 frames, each with a unique id, a name, a width from 240 to 2,560, and a ui spec that passes the ui checks. A frame may also set a least height, its padding, and its place on the board. |
| Shows as | A board of frames, each drawn at its real width with the stout component set. Readers drag to move the board and zoom with its buttons, with Ctrl or ⌘ and the wheel, or with two fingers on a touch screen; Fit shows every frame. A plain scroll or a one-finger swipe always moves the page. On a phone the frames stack in the page, each scaled to fit. A frame with a problem shows a notice in its place and the other frames still render. |
{ "version": 1, "frames": [{ "id": "home-phone", "name": "Home, phone", "width": 390, "spec": { "version": 1, "root": "page", "elements": { "page": { "type": "Heading", "props": { "text": "Hello" } } } } }] }{ "version": 1, "frames": [{ "id": "home-phone", "name": "Home, phone", "width": 20, "spec": { "version": 1, "root": "page", "elements": { "page": { "type": "Gauge", "props": {} } } } }] }
→ - Error: Frame "home-phone": "width" must be a whole number from 240 to 2560, in CSS pixels. Usual sizes: 1440 (desktop), 768 (tablet), 390 (phone).
- Error: Frame "home-phone": Element "page": unknown component "Gauge". Use one of: Section, Stack, Grid, Card, Tabs, Accordion, Separator, Box, Heading, Text, Markdown, Code, Callout, Badge, List, Steps, Link, Quote, Icon, Avatar, AvatarGroup, Kbd, Rating, Table, Metric, Chart, KeyValue, Progress, Timeline, Diagram, Board, Calendar, Checklist, Checkbox, Select, Switch, Slider, Button, Input, Textarea, Image, File, Placeholder.FilesLink to this section
Uploaded files with optional Markdown notes as content. Create one with files_create_artifact after uploading (files_request_upload, PUT, files_finalize).
| kind | file |
| Saves when | Content is optional Markdown notes. Files are uploaded first, then attached. |
| Shows as | The notes as Markdown, then each file: images inline, PDFs in the browser's viewer, video and audio in players, and a download card for every file. Every file URL is access-checked. |
Screenshots from the 6 Nov design review. The second one shows the empty state.Allowed file types. Anything else is refused. A vague type such as application/octet-stream is decided by the extension.
| Content type | Extensions | Name | Shown as |
|---|---|---|---|
| image/png | .png | PNG image | image |
| image/jpeg | .jpg .jpeg | JPEG image | image |
| image/gif | .gif | GIF image | image |
| image/webp | .webp | WebP image | image |
| image/avif | .avif | AVIF image | image |
| application/pdf | |||
| text/plain | .txt .md .log | Text | text |
| text/csv | .csv | CSV | document |
| application/json | .json | JSON | document |
| application/zip | .zip | ZIP archive | document |
| application/vnd.openxmlformats-officedocument.wordprocessingml.document | .docx | Word document | document |
| application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | .xlsx | Excel workbook | document |
| application/vnd.openxmlformats-officedocument.presentationml.presentation | .pptx | PowerPoint deck | document |
| video/mp4 | .mp4 | MP4 video | video |
| video/webm | .webm | WebM video | video |
| audio/mpeg | .mp3 | MP3 audio | audio |
| audio/wav | .wav | WAV audio | audio |
Uploading takes three calls: files_request_upload, a PUT to the presigned URL (valid 10 minutes), then files_finalize, which checks the size and type. Then files_create_artifact makes a file artifact, or files_attach adds the files to an existing one, such as a ui artifact that shows them with Image and File. files_replace puts a new upload in place of a file already there: it keeps its id, place, and name, so links open the new file, and the old copy stays in History for people who can edit. Unfinished uploads are deleted after 1 hour, and finished files never attached after 24 hours. See the Files tools.