---
audience: developer
summary: "Canvas \u2014 collaborative documents inside a chat room."
title: Artifacts API
path: reference/api/artifacts
status: published
---

# Artifacts API

7 endpoints. Artifacts are documents the AI can produce or edit
during a chat — code, markdown, JSON — that live as first-class
documents alongside the conversation. They have version history;
think of them as "the AI's draft pad that you can co-edit".

All paths scoped to a room. Auth: `power_level ≥ 0` to read,
default `power_level ≥ 10` to write (configurable per room).

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/rooms/{room_id}/artifacts` | List artifacts in this room. |
| `GET` | `/v1/rooms/{room_id}/artifacts/{artifact_id}` | Read latest version. |
| `PUT` | `/v1/rooms/{room_id}/artifacts/{artifact_id}` | Update (creates new version). |
| `DELETE` | `/v1/rooms/{room_id}/artifacts/{artifact_id}` | Soft-delete. |
| `POST` | `/v1/rooms/{room_id}/artifacts/{artifact_id}/revert` | Revert to a specific version. |
| `GET` | `/v1/rooms/{room_id}/artifacts/{artifact_id}/versions` | List versions with `change_description`. |
| `GET` | `/v1/rooms/{room_id}/artifacts/{artifact_id}/versions/{version}` | Read a specific version. |

## PUT body

```json
{
  "title": "Migration plan v3",
  "content": "# Migration plan\n\n…",
  "change_description": "Added the rollback section per Alice's feedback"
}
```

Each PUT creates a new version. `change_description` is what you see
in the version history panel.

## Creation

There's no `POST /artifacts` — artifacts are created by the AI
calling the `create_artifact` plugin tool, or by the client's
canvas panel which uses an internal mechanism. From outside,
artifacts come into existence when the AI decides they should.

## Versions

```bash
curl "$BASE/v1/rooms/$ROOM_ID/artifacts/$ARTIFACT_ID/versions" \
  -H "Authorization: Bearer $TOKEN"
```

```json
{
  "data": [
    {
      "version": 3,
      "title": "Migration plan v3",
      "change_description": "...",
      "editor_id": "ai-…",
      "created_at": "..."
    },
    {
      "version": 2,
      "title": "Migration plan v2",
      …
    },
    …
  ]
}
```

## Revert

```bash
curl -X POST "$BASE/v1/rooms/$ROOM_ID/artifacts/$ARTIFACT_ID/revert" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"version": 2}'
```

Creates a new version with content from version 2; doesn't delete
versions 3+ from history.