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.

kindNameFor
markdownMarkdownReadable prose with headings, lists, tables, and links.
htmlHTMLA web page with its own styles and scripts. It runs in a sandbox.
codeCodeSource code in monospace. Set the language to label it.
textTextPlain text, shown as written.
jsonJSONData, pretty-printed. The content must be valid JSON.
csvCSVA table. The first row names the columns.
svgSVGA vector image. Scripts inside it never run.
mermaidMermaidA diagram drawn from Mermaid source.
uiInterfaceAn earlier format: a dashboard or report built from our components. For a new page, choose HTML.
canvasCanvasAn earlier format: a board of screens built from our components. For a new mockup, choose HTML.
fileFilesImages, 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

LimitValueApplies to
Content1,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.
Metadata65,536 bytes (64 KB)The metadata object, as JSON text.
ui spec200,000 bytes (195 KB)ui content and each frame of a canvas, plus element and depth limits.
Canvas800,000 bytes (781 KB)canvas content: up to 24 frames and 3,000 elements across them.
Mermaid source50,000 charactersmermaid content.
File26,214,400 bytes (25 MB)Each upload. Up to 100 files in a document's text, and 20 attached files, per artifact.
Page files16,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.
The full list, with rate limits and storage quotas, is on Limits and quotas. The ui limits are on Validation.

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 ![alt](/api/files/<file id>) on its own line; artifacts_formats_guide with kind "markdown" explains how.

kindmarkdown
Saves whenAny non-empty text.
Shows asGitHub-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 ![alt](/api/files/<file id>) 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".
Example contentmarkdown
# 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.

kindhtml
Saves whenMust 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 asThe 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.
Example contenthtml
<!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>
Refused content, and the real messagetext
<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 .html file is another page of the site (see below); .htm is 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 own url(). 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.href in 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 to docs/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.
ExtensionsServed asName
.htmltext/plain, written into the frameHTML page
.csstext/cssStylesheet
.js .mjstext/javascriptScript
.svgimage/svg+xmlSVG image
.jsonapplication/jsonJSON
.mapapplication/jsonSource map
.txt .mdtext/plainText
.csvtext/csvCSV
.woff2font/woff2Font
.wofffont/woffFont
.ttffont/ttfFont
.otffont/otfFont
.wasmapplication/wasmWebAssembly module
.pngimage/pngPNG image
.jpg .jpegimage/jpegJPEG image
.gifimage/gifGIF image
.webpimage/webpWebP image
.avifimage/avifAVIF image
.mp4video/mp4MP4 video
.webmvideo/webmWebM video
.mp3audio/mpegMP3 audio
.wavaudio/wavWAV audio
LimitValue
Page files per artifact100
All page files of one artifact16,777,216 bytes (16 MB)
One page file26,214,400 bytes (25 MB)
Path200 characters, 8 parts (folders and the file's name)
Uploads started by one page_files_request_uploads call50
Uploads, and removals, named in one page_files_publish call100
Uploads waiting to finish, per person, when a call asks for a set200
Page file uploads started with page_files_request_uploads1,000 per hour, per person, counted per file
Upload URL lifetime10 minutes
A page's files addressWorks 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.
Example: the documenthtml
<!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>
Example: its page filestext
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 holds css/site.css and img/logo.png adds those two paths. Hidden and system files, such as .DS_Store, are left out.
  • A zip is unpacked. A .zip you 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.html at the top of a dropped folder can become the page's HTML, after you confirm. The HTML it had stays in History. Every other .html file in the drop is another page of the site, added at its path like any page file.
How an agent uploads them is on the MCP reference.

CodeLink to this section

Source code shown in monospace. Set language, for example typescript.

kindcode
Saves whenAny non-empty text. language (up to 60 characters) labels it.
Shows asMonospace, as written, with the language as a caption. There is no syntax highlighting.
Example contenttypescript
export function retryAfter(seconds: number): string {
  return `Try again in ${seconds} s.`;
}

TextLink to this section

Plain text, shown as written.

kindtext
Saves whenAny non-empty text.
Shows asAs written, with line breaks kept, in the page's column.
Example contenttext
Standup notes, 6 Nov
Shipped: docs shell
Next: MCP reference

JSONLink to this section

A JSON document, pretty-printed. It must parse.

kindjson
Saves whenMust parse as JSON.
Shows asPretty-printed with two-space indent. Content that does not parse shows as written, under a warning.
Example contentjson
{ "service": "billing", "p95Ms": 182, "regions": ["eu-west-1", "us-east-1"] }
Refused content, and the real messagetext
{ "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.

kindcsv
Saves whenRFC 4180 CSV with a header row. Quotes must close.
Shows asA 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.
Example contentcsv
service,p95_ms,errors
billing,182,3
search,95,0
Refused content, and the real messagetext
service,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.

kindsvg
Saves whenMust 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 asAn <img> with a data: URI on a checkerboard. Scripts, event handlers, and external loads never run. A missing xmlns is added.
Example contentsvg
<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>
Refused content, and the real messagetext
<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.

kindmermaid
Saves whenUp 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 asMermaid 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.
Example contentmermaid
flowchart LR
  agent[Coding agent] -->|artifacts_create| server[MCP server]
  server --> page[Artifact page]
Refused content, and the real messagetext
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.

kindui
Saves whenA JSON Render spec that passes validateUiSpec: known components, valid props, a tree from the root, and the size limits.
Shows asThe stout component set, the same for every reader. Links follow the link policy and images come only from the artifact's own files.
Example contentjson
{ "version": 1, "root": "page", "elements": { "page": { "type": "Heading", "props": { "text": "Hello" } } } }
Refused content, and the real messagetext
{ "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.

kindcanvas
Saves whenA 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 asA 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.
Example contentjson
{ "version": 1, "frames": [{ "id": "home-phone", "name": "Home, phone", "width": 390, "spec": { "version": 1, "root": "page", "elements": { "page": { "type": "Heading", "props": { "text": "Hello" } } } } }] }
Refused content, and the real messagetext
{ "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).

kindfile
Saves whenContent is optional Markdown notes. Files are uploaded first, then attached.
Shows asThe 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.
Example contenttext
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 typeExtensionsNameShown as
image/png.pngPNG imageimage
image/jpeg.jpg .jpegJPEG imageimage
image/gif.gifGIF imageimage
image/webp.webpWebP imageimage
image/avif.avifAVIF imageimage
application/pdf.pdfPDFpdf
text/plain.txt .md .logTexttext
text/csv.csvCSVdocument
application/json.jsonJSONdocument
application/zip.zipZIP archivedocument
application/vnd.openxmlformats-officedocument.wordprocessingml.document.docxWord documentdocument
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.xlsxExcel workbookdocument
application/vnd.openxmlformats-officedocument.presentationml.presentation.pptxPowerPoint deckdocument
video/mp4.mp4MP4 videovideo
video/webm.webmWebM videovideo
audio/mpeg.mp3MP3 audioaudio
audio/wav.wavWAV audioaudio

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.