> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosage.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Artifacts

> Create, edit, version, archive, and publish generated documents and pages.

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

<Note>
  API-key management uses `artifacts:read` and `artifacts:write`. Publishing and unpublishing are signed-in dashboard-user actions.
</Note>

## List artifacts

`GET /knowledge-bases/:id/artifacts`

<ParamField query="type" type="string">
  Filter to `markdown` or `html`.
</ParamField>

<ParamField query="query" type="string">
  Search string, up to 200 characters.
</ParamField>

<ParamField query="include_status" type="string">
  `active`, `archived`, or `all`.
</ParamField>

```bash theme={null}
curl "$AUTOSAGE_URL/knowledge-bases/KB_ID/artifacts?include_status=active" \
  -H "Authorization: Bearer $AUTOSAGE_KEY"
```

## Create an artifact

`POST /knowledge-bases/:id/artifacts`

<ParamField body="type" type="string" required>
  `markdown` or `html`.
</ParamField>

<ParamField body="title" type="string" required>
  Display title, up to 500 characters.
</ParamField>

<ParamField body="summary" type="string" required>
  Short description, up to 2,000 characters.
</ParamField>

<ParamField body="content" type="string" required>
  Complete artifact content.
</ParamField>

```bash theme={null}
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.

<ParamField body="title" type="string">
  New title.
</ParamField>

<ParamField body="summary" type="string">
  New summary.
</ParamField>

<ParamField body="edits" type="object[]">
  One to 50 edits with `oldText`, `newText`, and optional `replaceAll`.
</ParamField>

```bash theme={null}
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."
  }'
```

<Note>
  Update a title separately from a request that applies `edits`. Each edit operation creates revision history.
</Note>

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

<ParamField body="visibility" type="string" required>
  `private` or `public`.
</ParamField>

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

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

<Tip>
  Use `/swagger` for full artifact and publication response schemas.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Chats API" icon="comments" href="/developers/api/chats">
    Attach artifacts to a chat turn with `attached_artifact_ids`.
  </Card>

  <Card title="Agents API" icon="robot" href="/developers/api/agents">
    Run agents that can produce artifacts.
  </Card>
</CardGroup>