Artifacts

An artifact is something an assistant made for you to keep: a report, a dashboard, a prototype, a diagram. It is one HTML page, or a small package of HTML, CSS, JavaScript, images, fonts and data. n8v keeps every version, opens it safely, and hands it to your agents when their work needs it.

Why it lives in n8v

A page an assistant makes in its own app stays in that app. Your agents cannot read it, the next assistant cannot change it, and nobody can say which version is the current one. In n8v an artifact:

• has one address that never expires, such as https://n8v.online/artifacts/5f0c…;
• keeps every version, with who published it, from where and what changed;
• is private until you share it;
• can be read, mounted and updated by your chats and your organizations' agents;
• records who read it and who changed it.

Publish from an assistant

Ask an assistant that is connected to n8v to publish what it made. Try: "Publish this report to n8v as an artifact." It calls artifact_publish with a title and the files:

{
  "title": "Q3 churn report",
  "note": "First version, from the October export.",
  "files": [
    { "path": "index.html", "text": "<!doctype html>…" },
    { "path": "assets/chart.js", "text": "…" },
    { "path": "assets/logo.png", "base64": "iVBORw0KGgo…" }
  ]
}

A text file goes in text. A binary file, such as an image or a font, goes in base64. The assistant answers with the artifact's address:

Published "Q3 churn report" version 1 (3 files, 41.2 KB). Open it in n8v: https://n8v.online/artifacts/5f0c…

A script or a CI job does the same with an API key that has artifacts:write:

curl -sS -X POST "https://n8v.online/api/v1/artifacts" \
  -H "Authorization: Bearer $N8V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: churn-report-1" \
  -d '{"title":"Q3 churn report","files":[{"path":"index.html","text":"<!doctype html><title>Churn</title><h1>Churn, Q3</h1>"}]}'

To change an artifact, publish again with its id (over the API, POST /api/v1/artifacts/{id}/versions). Send the whole package each time. See Artifacts in the API for every call and its answer.

A page can only load its own files and a few script, style and font hosts, so an assistant should put the data a page needs into the package. See What a page can and cannot do.

What a version may hold

The file type comes from the extension, never from what the file claims to be. A file with any other extension is refused, and so is a version over the cap. Nothing is stored from a refused publish, and the answer names the file and the rule.

View it

Open an artifact on the Artifacts page of n8v, at /artifacts. The list filters by organization, repository and where the latest version came from (an assistant, the API, a chat or an organization agent). It searches titles and shows the archived ones on request.

An artifact's page shows the version you picked, live, with:

• a version picker, and the files of that version;
• compare, between any two versions;
• a zip download of the version;
• full screen, and a phone width to check a narrow layout;
• share, archive and the artifact's activity.

The address /artifacts/<id>?v=<n> opens one version directly. An assistant should give you this address: it never expires.

The isolated viewer

A page an assistant wrote is code from outside. n8v never serves it from its own site. It is served by a separate viewer on usercontent.n8v.nl, a different site from n8v.online, inside an isolated frame.

The app decides who may open a version and signs a view link for it. A view link names one version and is good for six hours. The viewer checks the signature and serves that version's files, and nothing else. A forged, changed or expired link gets one answer: it has expired.

What a page can and cannot do

A page can:

• run its own scripts and styles, inline or from its files;
• load its own files by relative path, and fetch them from script;
• load scripts, styles and fonts from cdn.jsdelivr.net, cdnjs.cloudflare.com, unpkg.com, esm.sh and cdn.tailwindcss.com;
• show images, sound and video from its own files or from data it builds itself;
• open dialogs, open a link in a new tab and offer a download.

A page cannot:

• read any cookie or stored data: the frame has no origin of its own, so the browser gives it none;
• reach n8v: no session, no API, no page of the app;
• fetch from or post to any other address in the background, or load an image from another site;
• embed another site in a frame, or submit a form to a server;
• take its frame in n8v to another site: on the Artifacts page the frame shows the viewer and nothing else;
• use the camera, microphone, location or other device features;
• be framed by any site other than n8v.

These rules are sent with every answer of the viewer, so they hold when a page is opened directly too. A link in a page can still open another site in a new tab, as a link on any page can. The page holds nothing of your account to take along.

Versions and comparing

Every publish is a new version. A published version never changes, and nothing is deleted.

• Publishing with an id adds a version. The assistant sends the whole package again, and a file that did not change is stored once.
• Publishing exactly what the latest version holds publishes nothing. The answer says unchanged.
• A title sent with an id renames the artifact.
• Each version records who published it, from where (an assistant, an API key, a chat or an organization agent), when, and its note.

Compare shows what changed between two versions: each file added, removed or changed, with the changed lines for text files. A binary file is listed without lines, and so is a text file of more than 4,000 lines. An assistant reads the same with artifact_diff, which compares the latest version with the one before unless it names two.

Share it

An artifact is private until you say otherwise. Only its person changes who sees it.

A share link opens on the viewer, behind a Cloudflare Access sign-in that proves the reader's email address (a one-time code, GitHub or Google):

• It names up to 20 email addresses. With none, anyone who passes the sign-in opens it.
• It follows the latest version, unless you fix it to one.
• It can have an end date. Without one it works until you revoke it.
• Sharing by link again keeps the same link, so a link you sent stays good.

After the sign-in the reader is sent to a view that lasts 30 minutes. The viewer checks it against the share on every request. A reader who stays longer signs in again.

Revoke by setting the artifact to private or to its organization. The link stops at the reader's next request, also for files their browser already holds. Archiving ends the link too.

Archive takes an artifact out of the list. It takes no new versions while archived, and its share link stops. Nothing is deleted: restore it at any time. A share link has to be made again after a restore.

Use it in chats and organizations

An artifact is not only for reading. Your chats and your organizations' agents can work from one and publish the next version.

Start a chat with artifacts. Pass up to 5 artifacts when a chat starts, over the API (POST /api/v1/chats) or with the MCP tool start_chat:

{
  "repo": "fieldnote/app",
  "message": "Build the churn dashboard from this prototype.",
  "artifacts": [{ "id": "5f0c…" }, { "id": "a91e…", "version": 2 }]
}

Without a version the chat gets the latest. n8v unpacks each one, read-only, in the agent environment at /tmp/artifacts/<id>/v<n>/, and the agent's first message says where they are.

Tools in the agent environment. The agent of a chat, and every organization agent, has four tools:

Links. A chat that used an artifact or changed one is linked on the artifact's page, with the version and whether it used or changed it. You see the names of your own chats only.

Organization agents read and update the artifacts of their organization. A new artifact an organization agent publishes belongs to its organization and is visible to it. An organization agent never shares an artifact and never archives one: who sees an artifact stays a person's decision. For the same reason it cannot publish to an artifact shared by a link that follows the latest version; fix the link to a version, or publish that version yourself.

Security at a glance

• A site of its own. Pages are served from usercontent.n8v.nl, never from n8v.online. No cookie of the app reaches a page, and the viewer sets none.
• Isolation. Every page runs isolated, without an origin of its own, in the frame and when opened directly: no cookie, no stored data, no way to the app.
• A content security policy on every answer. Nothing loads by default. A page gets its own files and the script, style and font hosts listed above. No other network, no frames, no form posts.
• Nothing runs on n8v's servers. n8v stores files and serves them. It never executes or renders a page. Thumbnails are rendered by Cloudflare Browser Rendering, from the same viewer under the same rules.
• Signed links. A view link opens one version for six hours. A share link sits behind a sign-in, and its 30 minute view is checked against the share on every request.
• A stated cap. 100 files, 10 MB a file, 25 MB a version (3 MB of it sent inline), file types by extension. Checked before anything is stored.
• Rate limits. A key's 120 calls a minute, and 30 published versions an hour per account.
• A scan for secrets. Every text file is scanned whole before it is stored: private keys, and keys and tokens of AWS, GitHub, Slack, Stripe, Google, Anthropic, OpenAI and n8v. A file named like a credentials file is refused by its name. A hit refuses the publish and names the file and the kind, never the value.
• An audit trail. Every API and MCP call is in your activity log as artifact.*, by its shape and never with a file's content. Each artifact keeps its own trail: every publish, share, archive and restore, and every read or mount by an assistant or an agent.
• Two permissions of their own. artifacts:read and artifacts:write. An app or a key that reads your repository files does not read your artifacts, and the other way round.

Limits

Over the hourly limit a publish answers 429 rate_limited with Retry-After.

Turn it on

Artifacts are behind the flag artifacts, which is off by default.

1. The account. An admin switches the flag on for an account, or for everyone, under /internal/admin/feature-flags. The Artifacts page appears, and chats can be started with artifacts.
2. Connected assistants. The two permissions, Read your artifacts and Publish artifacts, are switches of their own on the consent screen. An assistant that was connected before reconnects once: connect n8v again in Claude or ChatGPT and switch them on. Every connection of that app then has them, on every device.
3. API keys. Give a key artifacts:read (Read artifacts), artifacts:write (Publish artifacts) or both in Settings, API.

To check a connection, the assistant calls whoami, or a key GET /api/v1/me: each artifact tool is listed with whether it may be used and, if not, why. See What an assistant can read.

For assistants and scripts

# List what the key can see
curl -sS "https://n8v.online/api/v1/artifacts?q=churn" \
  -H "Authorization: Bearer $N8V_API_KEY"

# One artifact, with its versions and files
curl -sS "https://n8v.online/api/v1/artifacts/$ARTIFACT_ID" \
  -H "Authorization: Bearer $N8V_API_KEY"

# What the latest version changed
curl -sS "https://n8v.online/api/v1/artifacts/$ARTIFACT_ID/diff" \
  -H "Authorization: Bearer $N8V_API_KEY"