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
get_artifactopens the link:share_linkfor/artifacts/s/<handle>,artifact_idfor/artifacts/<id>(the Agents MCP takes that page URL in either field). The answer'sroleandnextsay what the caller may do.- Owner or editor:
read_artifact_filesreads the live version, thenpublish_artifact_versionpublishes only the changed files withbase_versionset to the live version andpublish: false. The receipt'spage_urlshows the new version. Only when the person asked to update the current version does it publish withpublish: true, or make the version live withupdate_artifact(live_version). - Anyone else:
clone_artifactmakes the person's own private copy of the live version, andpublish_artifact_versionchanges the copy (base_version: 1). The answer is the copy'sowner_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.
type | What it is | The file to change |
|---|---|---|
presentation | A slide deck written in Markdown - layouts, charts and speaker notes; prints to PDF | slides.md |
game | A 3D game in three.js - drive a combine harvester through a golden wheat field | game.config.js |
landing | A product landing page from one JSON file - hero, features, pricing and FAQ | site.json |
report | A report in Markdown with KPI tiles, charts from data files and tables; prints to A4 | report.md |
dashboard | A metrics dashboard - KPI tiles, charts and a sortable table, light and dark | dashboard.json |
gallery | A gallery for images and videos - filters, a lightbox, prompts and models | gallery.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_typeslists the types;create_artifactwithtypemakes the artifact.nameis optional (the type'sdefault_name), and anyfilesyou send are laid over the template. - From Python (
flymyai1.2.0rc12 or later):client.artifacts.types()andclient.artifacts.create(type="game", idempotency_key=...). - REST:
GET /api/v1/artifacts/types/answers each type'skey,name,summary,edit(the file to change),default_name,example_change,entry,files_countandtotal_bytes;POST /api/v1/artifacts/takestype. - 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: falsesaves it next to the live version, which stays what people see. Make it live later withupdate_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 currentlatest_versionandlive_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'spage_url.get_artifacttakes an optionalversionfor the same. - Nothing changed: a publish with the same files answers
no_changeand 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 by link
Share sets who can open the artifact:
| Visibility | Who opens it |
|---|---|
private | You and the people you shared it with by name |
link | Anyone with the link |
public | Anyone 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.
Continue from a share link
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_largeorrequest_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 withsecret_file. A text file that holds a private key or another service's token (GitHub, GitLab, Slack, Stripe, OpenAI- or Anthropic-stylesk-keys, AWS access keys) is refused withsecret_in_file, and one with a FlyMyAI key withplatform_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:
| What | Agents MCP tool | Python SDK (client.artifacts) | REST (/api/v1/artifacts/) |
|---|---|---|---|
| List yours or shared with you | list_artifacts | list(scope=...) | GET / (?scope=shared) |
| Standard types | list_artifact_types | types() | GET /types/ |
| Open one | get_artifact (artifact_id, share_link, optional version) | get(id) / get(share_link=...) | GET /<id>/, GET /shared/<handle>/ |
| Create | create_artifact (optional type) | create(...), create(type=...) | POST / |
| New version | publish_artifact_version | publish(...) | POST /<id>/versions/ |
| Read the files | read_artifact_files | files(...), read_file(...) | GET /<id>/versions/<n>/files/ |
| Rename or set the live version | update_artifact | update(...) | PATCH /<id>/ |
| Share by link | share_artifact | share(...) | PATCH /<id>/share/ |
| Clone | clone_artifact | clone(...) | POST /<id>/clone/, POST /shared/<handle>/clone/ |
| Lineage | get_artifact_lineage | lineage(...) | GET /<id>/lineage/ |
| People | list_artifact_members, add_artifact_member, remove_artifact_member | members, add_member, remove_member | GET/POST /<id>/members/, DELETE /<id>/members/<member id>/ |
| Invitations to you | list_artifact_invitations, accept_artifact_invitation, decline_artifact_invitation | invitations(), accept_invitation(id), decline_invitation(id) | GET /invitations/, POST /invitations/<id>/accept/, POST /invitations/<id>/decline/ |
| Delete | delete_artifact | delete(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.