Artifacts

Artifacts are knowledge-base-scoped Markdown documents or HTML pages that an agent or application can create and revise. Active artifacts can also be attached to chat turns.

Endpoints

Method	Path	Description	Auth
`GET`	`/knowledge-bases/:id/artifacts`	List artifacts in a knowledge base	[User+Key]
`POST`	`/knowledge-bases/:id/artifacts`	Create an artifact	[User+Key]
`GET`	`/artifacts/:id`	Get an active artifact	[User+Key]
`PATCH`	`/artifacts/:id`	Update metadata or apply text edits	[User+Key]
`POST`	`/artifacts/:id/archive`	Archive an artifact	[User+Key]
`POST`	`/artifacts/:id/restore`	Restore an archived artifact	[User+Key]
`GET`	`/artifacts/:id/revisions`	List revision history	[User+Key]
`POST`	`/artifacts/:id/publish`	Publish a hosted artifact	[User]
`DELETE`	`/artifacts/:id/publish`	Unpublish an artifact	[User]

API-key management uses artifacts:read and artifacts:write. Publishing and unpublishing are signed-in dashboard-user actions.

List artifacts

GET /knowledge-bases/:id/artifacts

string

Filter to markdown or html.

string

Search string, up to 200 characters.

string

active, archived, or all.

curl "$AUTOSAGE_URL/knowledge-bases/KB_ID/artifacts?include_status=active" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"

Create an artifact

POST /knowledge-bases/:id/artifacts

string

required

markdown or html.

string

required

Display title, up to 500 characters.

string

required

Short description, up to 2,000 characters.

string

required

Complete artifact content.

curl -X POST "$AUTOSAGE_URL/knowledge-bases/KB_ID/artifacts" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "markdown",
    "title": "Quarterly support brief",
    "summary": "Key themes from the quarter.",
    "content": "## Summary\n\nSupport volume declined..."
  }'

Get an artifact

GET /artifacts/:id Returns an active artifact by ID or slug, subject to access to its knowledge base.

Update an artifact

PATCH /artifacts/:id Use this endpoint either to update metadata or to apply exact text replacements.

string

New title.

string

New summary.

object[]

One to 50 edits with oldText, newText, and optional replaceAll.

curl -X PATCH "$AUTOSAGE_URL/artifacts/ARTIFACT_ID" \
  -H "Authorization: Bearer $AUTOSAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "edits": [{
      "oldText": "Support volume declined",
      "newText": "Support volume declined by 12%"
    }],
    "summary": "Adds the measured change."
  }'

Update a title separately from a request that applies edits. Each edit operation creates revision history.

Archive and restore

POST /artifacts/:id/archive removes an artifact from the active set without deleting its history. POST /artifacts/:id/restore makes an archived artifact active again.

List revisions

GET /artifacts/:id/revisions Returns revision history for an active artifact so clients can present its evolution.

Publish and unpublish

POST /artifacts/:id/publish publishes the artifact as a hosted page.

string

required

private or public.

DELETE /artifacts/:id/publish removes the hosted publication while preserving the artifact and its revisions.

Publishing is intentionally a dashboard-user action. API keys can create and edit artifacts but cannot publish or unpublish them.

Use /swagger for full artifact and publication response schemas.

Next steps

Chats API

Attach artifacts to a chat turn with attached_artifact_ids.

Agents API

Run agents that can produce artifacts.

Get started

Core concepts

Lifecycles

Guides

API reference

Endpoints

List artifacts

Create an artifact

Get an artifact

Update an artifact

Archive and restore

List revisions

Publish and unpublish

Next steps

Chats API

Agents API

​Endpoints

​List artifacts

​Create an artifact

​Get an artifact

​Update an artifact

​Archive and restore

​List revisions

​Publish and unpublish

​Next steps

Chats API

Agents API

Endpoints

List artifacts

Create an artifact

Get an artifact

Update an artifact

Archive and restore

List revisions

Publish and unpublish

Next steps