Artifacts

​

Live dashboards

​

When to use an Artifact

• interactive HTML reports and dashboards;
• presentations generated by Presentation Studio;
• static site snapshots produced by Sites;
• PDF reports, PPTX decks, images, CSV files, and other downloadable outputs;
• visual comparisons, annotated reviews, timelines, and checklists;
• a result that a plugin will update by publishing additional versions.

​

What an Artifact is not

• It does not expose a plugin’s backend or credentials to viewers.
• It is not a replacement for a database-backed, multi-route application.
• It does not make the shared content collaboratively editable.
• Generic HTML content sharing supports client-side interactions allowed by its security profile. Live dashboards use a separate authorized presentation channel for declared data; page code cannot call external services or platform APIs directly.
• Version updates are durable, but an already open viewer currently needs to refresh to resolve a newer latest version.

​

Core model

​

Create an Artifact

1. Generate or export the content.
2. Write the content to Workspace Files.
3. Create or locate the stable Artifact container using the plugin’s business resource identity.
4. Add an immutable Artifact Version that references the Workspace Files object.
5. Optionally create a preview or sharing link.

​

Update an Artifact

​

Preview an Artifact

• use the signed_preview access mode;
• include an opaque token in the xpert_artifact_preview query parameter;
• expire after 15 minutes by default;
• can be given a shorter or longer TTL within the platform limit;
• must not be persisted as a durable public URL.

​

Share an Artifact

https://<xpert-public-base>/artifacts/share/<artifact-link-slug>

https://<xpert-public-base>/artifacts/share/<artifact-link-slug>/download

​

Access modes

​

Revoke, archive, and delete

• Revoke a link when the Artifact should remain available internally but a particular access path must stop working. Revocation takes effect immediately.
• Archive an Artifact when it should no longer be active but should remain in platform history and audit records.
• Delete an Artifact to mark the Artifact as deleted and revoke all of its links. Plugins that own the underlying Workspace Files object should separately apply their file-retention or deletion policy.

​

Supported content

​

HTML security profiles

​

Use Artifacts from a plugin

import {
  ArtifactsRuntimeCapability,
  WorkspaceFilesRuntimeCapability
} from '@xpert-ai/plugin-sdk'

const files = runtimeCapabilities.require(WorkspaceFilesRuntimeCapability)
const artifacts = runtimeCapabilities.require(ArtifactsRuntimeCapability)

const file = await files.writeRuntimeBuffer({
  tenantId,
  userId,
  catalog: 'xperts',
  scopeId: xpertId,
  xpertId,
  folder: 'reports',
  fileName: 'quarterly-report.html',
  originalName: 'quarterly-report.html',
  mimeType: 'text/html',
  buffer: Buffer.from(html, 'utf8')
})

const artifact = await artifacts.createArtifact({
  source: {
    pluginName: '@xpert-ai/plugin-example',
    resourceType: 'quarterly_report',
    resourceId: reportId
  },
  kind: 'html',
  title: 'Quarterly report'
})

const version = await artifacts.createArtifactVersion({
  artifactId: artifact.id,
  workspaceFileRef: file.reference,
  mimeType: 'text/html',
  fileName: 'quarterly-report.html'
})

const link = await artifacts.createArtifactLink({
  artifactId: artifact.id,
  artifactVersionId: version.id,
  versionMode: 'version',
  access: {
    mode: 'public_link',
    userConfirmedPublicLink: true
  },
  presentation: {
    disposition: 'inline',
    allowDownload: true,
    safeHtmlProfile: 'strict'
  }
})

console.log(link.publicUrl)

​

Plugin responsibilities

• Use a stable pluginName + resourceType + resourceId for the Artifact container.
• Store bytes through Workspace Files and persist only portable references.
• Create a new version instead of replacing published bytes.
• Ask for explicit confirmation before creating a public link.
• Return and copy the platform-provided publicUrl.
• Revoke links before deleting plugin-owned exported files.
• Keep large file bodies, HTML, tokens, and private identifiers out of tool results and logs.

​

Current release boundaries

​

Related resources

• Plugin development
• Workbench Remote Components and Agentic Apps
• Claude Code Artifacts, the product concept used as a reference for this Xpert capability