06Working with artefacts

Update an artefact without breaking its link

You send a client the pricing page on Monday. On Tuesday your agent fixes a figure. The client should see the fix at the link they already have, not wait for a new one. In myartefacts that is how publishing works: send the file again under the same slug and it becomes the next version, at the same URL.

The slug is the artefact's name

Every artefact has a slug, a short id such as pricing-page. On first publish it is made from the title or the file name, lowercased and hyphenated, with -2, -3 added if that one is taken. Every publish answers with it, so the agent always knows what to reuse.

Both of an artefact's links belong to the artefact, not to a version:

• In your libraryhttps://myartefacts.com/artefacts?open=pricing-page opens it on your sheet.
• The share linkhttps://myartefacts.com/s/… is fixed for the artefact. Once you share it, it keeps working through every version.

Four ways to publish a new version

All of them take the slug. Which one an agent uses depends on where the file is.

1. update_artifact with the slug, a filename and the new content. The safest choice for revisions: it fails with a clear message if no artefact has that slug, instead of quietly starting a new one.
2. publish_artifact with the slug. If the slug exists, this is a new version; if not, it creates the artefact under that slug.
3. create_upload_url with the slug, for a file on disk. The upload becomes the next version. See Publish a file that is already on disk.
4. The HTTP API, POST /api/artifacts with a slug field. It answers 201 for a new artefact and 200 for a new version.

Over the API, a revision looks like this:

curl -s https://myartefacts.com/api/artifacts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -F file=@./pricing-page.html \
  -F slug=pricing-page

The answer's version goes up by one, and slug, library_url and share_url are the same as before.

What a new version changes

The fresh preview matters more than it sounds. When a shared link is pasted into a chat, the picture people see is the top of the artefact. A new version renders a new one, and its address changes with the version number, so apps that cache previews pick up the new picture rather than last week's.

Change the details without a new version

Sometimes the file is right and only what is said about it is wrong. Call update_artifact with the slug and no content, and it changes only what you pass (title, project, summary, prompt or share) while the version stays where it is. This is also how an agent moves an artefact into another project:

{
  "slug": "pricing-page",
  "project": "Website/Pricing"
}

Earlier versions

Each version's file is stored on its own, so publishing again never overwrites the one before. Your library, the share link and the API's /content endpoint all serve the latest. Deleting an artefact removes it with every version.

When a slug does not match

A slug only finds artefacts the agent is allowed to see. An agent still waiting for your approval sees only what it published itself, so if it reuses the slug of something in your library, it starts a new artefact in its own tray rather than touching yours. Once you approve it, it can revise anything in your library.

A waiting agent also cannot turn a share link on. It still publishes, privately, and the answer's share_note says why. Once you have approved it, it publishes again with the same slug and share set: same slug, next version, and now a link.

If update_artifact answers that no artefact has the slug, the agent has misremembered it. search_artifacts or list_artifacts will find the right one.

What to tell your agents

One rule covers it: to revise something, reuse its slug; for new work, leave the slug out. The instructions every connected agent receives already say this, along with searching for earlier work before redoing it. If an agent keeps making near-duplicates such as pricing-page-2, remind it to look up the slug first.