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

# Artifacts

> The artifact lifecycle, supported content types, versions, and how content is stored.

An **artifact** is the durable object Artifacts hosts. It has a stable URL, belongs to exactly one project, has a single source type, and always points at its latest immutable version.

The key idea: you never overwrite an artifact. Every change appends a new version, so history is always intact and recoverable.

## Lifecycle

<Steps>
  <Step title="Create">
    A user, API key, agent, or MCP client submits source content with a workspace slug, project slug, artifact slug, title, and type.
  </Step>

  <Step title="Store">
    The API writes the source to object storage, records its byte count and SHA-256 hash, then creates the artifact and version rows in Postgres.
  </Step>

  <Step title="Render">
    The web app resolves the artifact path and renders the latest version according to its type.
  </Step>

  <Step title="Update">
    Each update appends a new immutable version. Existing versions are never modified.
  </Step>

  <Step title="Restore or delete">
    Restoring an older version creates a new head version from that content. Deleting an artifact is a soft delete that preserves audit history.
  </Step>
</Steps>

## Content types

Artifacts supports three source types, each with a safe render path:

| Type   | Input                             | Render behavior                                  |
| ------ | --------------------------------- | ------------------------------------------------ |
| `html` | HTML document or fragment         | Rendered as HTML with browser isolation controls |
| `md`   | Markdown                          | Sanitized, GitHub-flavored Markdown              |
| `jsx`  | JSX or TSX compatible with Preact | Rendered through the Preact-compatible runtime   |

The maximum source size depends on your plan:

| Plan | Max source size |
| ---- | --------------- |
| Free | 1 MB            |
| Pro  | 10 MB           |
| Team | 50 MB           |

## Fields

<AccordionGroup>
  <Accordion title="Artifact metadata" icon="box">
    * `artifactId` — stable identifier for API, CLI, and MCP operations.
    * `ownerUsername` — workspace slug used in public paths.
    * `projectSlug` — project slug under the workspace.
    * `normalizedSlug` — artifact slug normalized to lowercase hyphen format.
    * `type` — one of `html`, `md`, or `jsx`.
    * `title` and `description` — human-readable metadata.
    * `publicView` and `publicEdit` — coarse public access switches.
    * `latestVersionId` — pointer to the current version.
  </Accordion>

  <Accordion title="Version record" icon="git-branch">
    Every create, update, and restore writes a version with:

    * `versionNumber` — monotonically increasing positive integer.
    * `parentVersionId` — previous head version, when applicable.
    * `contentObjectKey` — object storage key for the source content.
    * `thumbnailObjectKey` — optional preview thumbnail key.
    * `contentSha256` — integrity hash of the stored source.
    * `contentBytes` — stored source size.
    * `changelog` — optional description of the write.
    * `createdByPrincipalType` and `createdByPrincipalId` — actor attribution.
  </Accordion>
</AccordionGroup>

## How content is stored

Source and thumbnail objects use owner- and artifact-scoped keys:

```text theme={"theme":"github-dark"}
users/{ownerUserId}/artifacts/{artifactId}/versions/{versionNumber}/source-{attemptId}
users/{ownerUserId}/artifacts/{artifactId}/versions/{versionNumber}/thumbnail-{attemptId}
```

This keeps stored content grouped by billing owner while preserving version-level immutability.

## Slugs and URLs

Artifact slugs normalize to lowercase letters, numbers, and single hyphens:

```text theme={"theme":"github-dark"}
my-launch-review
```

Public artifact URLs are shaped like this:

```text theme={"theme":"github-dark"}
https://agent-artifacts.com/{workspaceSlug}/{projectSlug}/{artifactSlug}
```

To go the other way — from a path back to metadata — resolve it:

```bash theme={"theme":"github-dark"}
artifacts path artifact --owner alice --project-slug default --slug launch-review
```

<Card title="Work with versions" icon="history" href="/guides/version-history" horizontal>
  List, read, diff, and restore versions from any surface.
</Card>