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

PUT body#

1
2
3
4
5

{
  "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#

1
2

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

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

Revert#

1
2
3

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.