# Frontend Artifacts

> Pages, presentations and mini games with versions: start from a standard type or your own files, change them by pasting one line into Claude, share them by link or with people to view or edit, and clone anyone's shared artifact into your own copy.

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](#limits-and-refused-files)).

Artifacts are on for every account. `GET /api/v1/artifacts/status/` (or
`client.artifacts.status()` in the [Python SDK](https://docs.flymy.ai/agents/sdk/python.md)) lists your limits. Each
artifact is also a [project](https://docs.flymy.ai/agents/guides/projects.md), `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:

```text
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](https://docs.flymy.ai/agents/guides/connect-your-agent.md).

```bash
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](https://docs.flymy.ai/agents/guides/agent-gateway-reference.md)):

> 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](#standard-types). Version 1 goes live at once and stays private
until you share it.

**From Python** (`flymyai` 1.2.0rc8 or later):

```python
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_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 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](#change-it-with-claude-in-one-line). 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:

```bash
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):

```bash
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](https://docs.flymy.ai/agents/guides/connect-your-agent.md). The sign-in creates a
FlyMy.AI account if the person has none. Then paste the line with the change:

```text
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:

| 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.
