Skip to main content

Frontend Artifacts

An artifact is a small web frontend - a page, a presentation, a mini game - made of HTML, JavaScript, CSS and assets. Every save is a new immutable version, and one version is live. Artifacts are private until you share them: by link, publicly, or by inviting people by name to view or edit. Anyone you share the sources with can clone the artifact into their own copy.

A page runs sandboxed on its own origin: it has no cookies, no browser storage and no FlyMyAI key, and files that look like secrets are refused at publish (see Limits and refused files).

Artifacts are on for every account. GET /api/v1/artifacts/status/ (or client.artifacts.status() in the Python SDK) lists your limits. Each artifact is also a project, artifact:<id>, and its files live in that project's storage.

Change it with Claude in one line​

Every artifact page has one line to copy: Change with Claude on an artifact you may edit, Make your own version on anyone else's. Paste it into Claude, or any assistant with the FlyMy.AI MCP, and type what to change right after it:

https://app.flymy.ai/artifacts/s/<handle> add these things to the artifact: make v2 where the enemies are different

What happens depends on who you are:

  • You may edit it (its owner or an editor): Claude adds your change as a new version next to the live one. The live version stays what people see, and both versions are kept. Claude answers with the new version's page (https://app.flymy.ai/artifacts/<id>?v=<n>).
  • To change the live page right away, end the line with and update current version: the new version becomes the live one. The earlier versions stay.
  • Anyone else gets their own copy (a clone) with the change, when the author shared the sources. The original stays as it is.

The link can be the share link (/artifacts/s/<handle>) or the artifact's own page (/artifacts/<id>), which opens for its owner and the people it is shared with. Paste the line into the assistant's prompt; do not run it as a shell command: claude <link> some words hands Claude only the first word.

First time? Connect FlyMy.AI to Claude Code once, then type /mcp, pick flymyai and sign in (the sign-in creates a FlyMy.AI account if you have none). Other assistants: Connect your agent.

claude mcp add --scope user --transport http flymyai https://mcp-agents.flymy.ai/mcp

What the assistant does​

  1. get_artifact opens the link: share_link for /artifacts/s/<handle>, artifact_id for /artifacts/<id> (the Agents MCP takes that page URL in either field). The answer's role and next say what the caller may do.
  2. Owner or editor: read_artifact_files reads the live version, then publish_artifact_version publishes only the changed files with base_version set to the live version and publish: false. The receipt's page_url shows the new version. Only when the person asked to update the current version does it publish with publish: true, or make the version live with update_artifact (live_version).
  3. Anyone else: clone_artifact makes the person's own private copy of the live version, and publish_artifact_version changes the copy (base_version: 1). The answer is the copy's owner_url.

next is one plain sentence in the artifact's answer - get_artifact, GET /api/v1/artifacts/<id>/ and GET /api/v1/artifacts/shared/<handle>/ - written for the caller's access, so an assistant that never saw the page follows the same rule. A page shared without its sources can only be viewed: there is nothing to clone.

Create an artifact​

From your AI assistant (the Agents MCP):

Make a one-page landing for my bakery and publish it as a FlyMyAI artifact.

The assistant calls create_artifact with the files, or with a standard type. Version 1 goes live at once and stays private until you share it.

From Python (flymyai 1.2.0rc8 or later):

from flymyai import AgentClient
from flymyai.agents import artifact_files_from_directory

client = AgentClient(api_key="fly-...")
made = client.artifacts.create(
name="Pod racer",
files=artifact_files_from_directory("./pod-racer"), # index.html and its assets
idempotency_key="pod-racer-create-1",
)
print(made.artifact.owner_url)

In the app: open Artifacts > New artifact, then start from a type, write the HTML, or upload files or a whole folder. The entry page is index.html, or the only .html file.

Standard types​

A standard type is a template: a folder of files that becomes version 1 of a new artifact. Each one works as it is and keeps its content in one file, so most changes touch that file and leave the engine alone.

typeWhat it isThe file to change
presentationA slide deck written in Markdown - layouts, charts and speaker notes; prints to PDFslides.md
gameA 3D game in three.js - drive a combine harvester through a golden wheat fieldgame.config.js
landingA product landing page from one JSON file - hero, features, pricing and FAQsite.json
reportA report in Markdown with KPI tiles, charts from data files and tables; prints to A4report.md
dashboardA metrics dashboard - KPI tiles, charts and a sortable table, light and darkdashboard.json
galleryA gallery for images and videos - filters, a lightbox, prompts and modelsgallery.json

Every template has a README.md for people and assistants: which file to change for what, its format with an example, and what not to touch. An assistant reads it with read_artifact_files before the first change.

  • From your assistant: list_artifact_types lists the types; create_artifact with type makes the artifact. name is optional (the type's default_name), and any files you send are laid over the template.
  • From Python (flymyai 1.2.0rc12 or later): client.artifacts.types() and client.artifacts.create(type="game", idempotency_key=...).
  • REST: GET /api/v1/artifacts/types/ answers each type's key, name, summary, edit (the file to change), default_name, example_change, entry, files_count and total_bytes; POST /api/v1/artifacts/ takes type.
  • In the app: New artifact > Start from a type.

Make me a FlyMyAI presentation about our Q3 results, then add a slide about pricing.

An artifact keeps the type it started from, and so do its clones.

Versions: the live one and the ones next to it​

A new version starts from base_version: the latest version, or the live one. Files you send add or replace paths, delete removes paths, and every other file is kept.

  • Live or not: publish: true (the default) makes the new version live at once. publish: false saves it next to the live version, which stays what people see. Make it live later with update_artifact (live_version) - Make live in the app; rolling back works the same way. Earlier versions always stay.
  • Start from the live version to leave a saved version above it untouched: the new version takes the next number, and the saved one stays as it was. Any other base means someone published since you read it: the call is refused with stale_base_version (HTTP 412) and the current latest_version and live_version. Read the version your change starts from and apply it there.
  • Show a version that is not live with its page, https://app.flymy.ai/artifacts/<id>?v=<n> - the publish receipt's page_url. get_artifact takes an optional version for the same.
  • Nothing changed: a publish with the same files answers no_change and names the version that already holds them.
  • Saved versions are not private: the people the artifact is shared with see every version, and so do link viewers when the sources are shared.

In the app, New version edits the entry page in place or takes uploaded files.

Share sets who can open the artifact:

VisibilityWho opens it
privateYou and the people you shared it with by name
linkAnyone with the link
publicAnyone with the link, like link today; public artifacts may be listed in a gallery later

With sources also gives link viewers every version, the files and Make your own version (a clone). Reset link draws a new link: the old one and every frame opened through it stop working.

Share with people to view or edit​

Under People, enter someone's email or FlyMyAI username and pick a role:

  • Can view - every version, its files, and a clone.
  • Can edit - also publish versions, choose the live version and rename. An editor's versions are stored as yours.

This sends an invitation, and the person must accept it. They get an email and accept or decline on their Artifacts page, or from their assistant. Until they accept, nothing is shared with them: the artifact is not in their lists, and its files and pages stay closed to them. An invitation to an email waits for whoever verifies that email on FlyMyAI.

Nobody learns who an email or a username belongs to. Inviting an email answers the same whether an account has it or not; you see each person exactly as you typed them, with their status (pending or accepted); a member sees only which entry is theirs. The artifact's history names people the same way.

Sharing settings, the list of people and deleting the artifact stay yours. Someone who accepted finds the artifact under Artifacts > Shared with me and can Leave it. Removing a person, invited or accepted, stops their access and any page they have open at once. You can share an artifact with up to 20 people.

From your assistant: add_artifact_member invites, list_artifact_members shows who is in and who has not accepted yet, and remove_artifact_member takes the member's id. The invited person answers with list_artifact_invitations, accept_artifact_invitation and decline_artifact_invitation, and list_artifacts with scope: "shared" lists what they accepted; it and get_artifact give them the artifact's page in the app as app_url.

Clone​

Clone (or clone_artifact) makes a new private artifact that you own, starting from any version you may open. The copy is independent: changes to it never touch the original. It records where it came from (forked from: name and version), and the original counts its clones (get_artifact_lineage). A clone's name, author and link show in the original's lineage only when its owner made the clone public.

A share link opens the page under one thin bar: name, author, version, Page and Sources, and the description behind the info button. Make your own version (Change it with Claude for its owner and editors) gives the one line to paste into Claude. When the author shared the sources, people without an assistant can sign in and clone it right on the page.

Connect FlyMy.AI once. Claude Code:

claude mcp add --scope user --transport http flymyai https://mcp-agents.flymy.ai/mcp
claude mcp login flymyai

Codex (adding the server opens the sign-in; codex mcp login flymyai signs in again):

codex mcp add flymyai --url https://mcp-agents.flymy.ai/mcp

claude.ai, Claude Desktop and ChatGPT add the same URL as a custom connector, see Connect your agent. The sign-in creates a FlyMy.AI account if the person has none. Then paste the line with the change:

https://app.flymy.ai/artifacts/s/<handle> add these things to the artifact: make the title shorter

An agent that only fetches the link, without JavaScript, finds the same steps in the page, for /artifacts/s/<handle> and for /artifacts/<id>. GET /api/v1/artifacts/shared/<handle>/ answers the artifact's name, description, author and versions without sign-in. Share pages are never indexed by search engines.

Bring a page from elsewhere​

To bring in a Claude artifact, a CodePen or a folder on your disk, your assistant reads the page's files and calls create_artifact with them. Text files go in content and binary files in content_base64. A single-file page is just index.html.

Copy my Claude artifact "Q3 launch deck" into FlyMyAI and share it by link.

Claude reads the HTML of Claude artifacts you own. For a page someone else published, give your assistant the files, or let it fetch the page it serves. From Python, artifact_files_from_directory() turns a folder into the files to send and leaves out hidden files such as .env and .git.

Limits and refused files​

  • Size: a file is at most 16 MB, one create or publish call carries at most 24 MB of files, and its request body at most 40 MB (base64 grows binary files by a third); more is refused with file_too_large or request_too_large (HTTP 413). Build a bigger artifact over several versions: each keeps the files it does not change. GET /api/v1/artifacts/status/ lists the limits that apply to you.
  • Secrets: everyone who opens a page can read its files, so a version never carries secrets. A file whose path is an env file (.env, .env.local), version control (.git/), SSH or cloud credentials (.ssh/, .aws/, id_rsa) or a key or certificate (.pem, .key, .p12, .pfx) is refused with secret_file. A text file that holds a private key or another service's token (GitHub, GitLab, Slack, Stripe, OpenAI- or Anthropic-style sk- keys, AWS access keys) is refused with secret_in_file, and one with a FlyMyAI key with platform_key_in_file. The answer names the file (details.path): leave it out, revoke the key if it was real, and publish again.

Games​

A game is an artifact like any page. Canvas, WebGL, the gamepad, fullscreen and sound work in the frame. Start from the game type for a ready 3D game whose enemies, field, colors and difficulty live in game.config.js. Share it to edit with a friend to build it together, or share it with sources and let people clone it and make their own version. A page has no browser storage, so saving progress to a server is not part of this version.

In Projects​

Each artifact you own, or that is shared with you and you accepted, also appears in Projects as a project of kind artifact. Its card shows the live version, its sharing and the people, and opens the artifact page.

Tools, SDK and REST​

The same operations are available on every surface:

WhatAgents MCP toolPython SDK (client.artifacts)REST (/api/v1/artifacts/)
List yours or shared with youlist_artifactslist(scope=...)GET / (?scope=shared)
Standard typeslist_artifact_typestypes()GET /types/
Open oneget_artifact (artifact_id, share_link, optional version)get(id) / get(share_link=...)GET /<id>/, GET /shared/<handle>/
Createcreate_artifact (optional type)create(...), create(type=...)POST /
New versionpublish_artifact_versionpublish(...)POST /<id>/versions/
Read the filesread_artifact_filesfiles(...), read_file(...)GET /<id>/versions/<n>/files/
Rename or set the live versionupdate_artifactupdate(...)PATCH /<id>/
Share by linkshare_artifactshare(...)PATCH /<id>/share/
Cloneclone_artifactclone(...)POST /<id>/clone/, POST /shared/<handle>/clone/
Lineageget_artifact_lineagelineage(...)GET /<id>/lineage/
Peoplelist_artifact_members, add_artifact_member, remove_artifact_membermembers, add_member, remove_memberGET/POST /<id>/members/, DELETE /<id>/members/<member id>/
Invitations to youlist_artifact_invitations, accept_artifact_invitation, decline_artifact_invitationinvitations(), accept_invitation(id), decline_invitation(id)GET /invitations/, POST /invitations/<id>/accept/, POST /invitations/<id>/decline/
Deletedelete_artifactdelete(id)DELETE /<id>/

REST also has GET /<id>/versions/ (versions), GET /<id>/history/ (what happened, and who did it) and GET /<id>/versions/<n>/view/ (a sandboxed frame URL that is valid for 8 hours). Calls use your API key (X-API-KEY) or an OAuth token. A write that creates something (create, publish, clone, and a share that resets the link) takes a caller-owned Idempotency-Key of 1-255 printable ASCII characters (spaces inside are fine, not at either end): reuse it only to retry the identical request.

API versions​

This is version 1 of the artifacts API: the routes under /api/v1/artifacts/, the payload schema flymy.artifact.v1, the tool names above and the SDK methods. Version 1 stays for as long as anything uses it, so an agent frozen with these calls keeps working. New fields, routes and tools may be added to it. A breaking change would arrive as version 2 next to version 1, never in its place.