Artifacts Runtime

ArtifactsRuntimeCapability exposes ArtifactsApi under platform.artifacts. It manages durable deliverables generated by plugins and Agents, including HTML, Markdown, PDF, PowerPoint, images, files, Sites, and presentations. Artifact content bytes live in Workspace Files. The Artifact service adds stable business identity, immutable version history, governed access links, lifecycle state, and access counters.

Data model

An Artifact flow has three layers:

Artifact container — stable plugin-owned identity defined by pluginName, resourceType, and resourceId.
Artifact version — immutable content described by a WorkspacePortableFileReference, MIME type, checksums, and metadata.
Artifact link — an open/share/download entrypoint with a version policy, access mode, expiration, and presentation policy.

Supported Artifact kinds are html, markdown, pdf, pptx, image, file, site, and presentation.

Container and version methods

Method	Purpose
`createArtifact(input)`	Create or locate a container without uploading content bytes.
`findArtifactBySource(input)`	Find a container by the plugin-owned source triple.
`getArtifact(idOrSlug)`	Get a container by ID or slug.
`listArtifacts(input?)`	Page through visible containers.
`archiveArtifact(idOrSlug)`	Transition a container to `archived`.
`deleteArtifact(idOrSlug)`	Transition a container to `deleted`.
`createArtifactVersion(input)`	Create an immutable version.
`ensureArtifactVersion(input)`	Idempotently create or reuse a version.
`listArtifactVersions(input)`	List versions, optionally by idempotency key or status.

Container status is active, archived, or deleted. Version status is active or deleted.

Method	Purpose
`createArtifactLink(input)`	Create a new governed link.
`createSignedPreviewLink(input)`	Create a short-lived preview link; never use it as a durable share URL.
`updateArtifactLinkAccess(idOrSlug, patch)`	Change mutable access and presentation properties.
`revokeArtifactLink(idOrSlug)`	Revoke a specific link.
`getArtifactShare(input)`	Resolve the active durable share for an Artifact and `shareKey`.
`ensureArtifactShare(input)`	Create, reuse, or replace one stable share slot.
`revokeArtifactShare(input)`	Revoke a stable share slot.

Link status is active, revoked, or expired. versionMode: 'latest' follows the current Artifact version; versionMode: 'version' pins an immutable version. Access modes are:

owner_only
workspace_all
organization_all
custom_principals
public_link
signed_preview

Presentation can use inline or attachment, can allow or disallow download, and can apply the strict or interactive safe-HTML profile.

Publish a generated file

Write bytes to Workspace Files first, then create or reuse the Artifact version and share:

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

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

const stored = await files.writeRuntimeBuffer({
  buffer: reportBuffer,
  originalName: 'inspection-report.pdf',
  mimeType: 'application/pdf',
  folder: 'reports'
})

const artifact = await artifacts.createArtifact({
  source: {
    pluginName: '@acme/plugin-inspection',
    resourceType: 'inspection-report',
    resourceId: inspectionId
  },
  kind: 'pdf',
  title: `Inspection report ${inspectionCode}`,
  scope: {
    workspaceId,
    projectId,
    userId
  }
})

const { version } = await artifacts.ensureArtifactVersion({
  artifactId: artifact.id,
  idempotencyKey: `inspection:${inspectionId}:${reportRevision}`,
  workspaceFileRef: stored.reference,
  mimeType: 'application/pdf',
  fileName: stored.name,
  size: stored.size,
  sha256: reportSha256,
  sourceVersionId: reportRevision,
  setCurrent: true
})

const { link } = await artifacts.ensureArtifactShare({
  artifactId: artifact.id,
  artifactVersionId: version.id,
  versionMode: 'version',
  shareKey: 'reviewers',
  access: {
    mode: 'workspace_all'
  },
  presentation: {
    disposition: 'inline',
    allowDownload: true
  }
})

return link.publicUrl

Use a deterministic version idempotencyKey that represents the same immutable content. ensureArtifactVersion() reports created or reused; ensureArtifactShare() reports created, reused, or replaced.

Security and lifecycle rules

Do not store content bytes in Artifact metadata. Store them in Workspace Files and pass the portable reference.
Require explicit user confirmation before requesting public_link; set userConfirmedPublicLink in the access input.
Use createSignedPreviewLink() only for short-lived previews. Store a shareKey and use ensureArtifactShare() for a durable share policy.
Pin a version for review, approval, audit, and reproducible delivery. Use latest only when readers should always see the current version.
Choose strict HTML unless the deliverable needs the platform’s interactive HTML allowance.
Revoke links or share slots when access should end. Archiving the business object should also drive the plugin’s Artifact lifecycle policy.

Default

Plugin SDK Core

Trigger

Integration

Feishu Document Example

Triggers

Integrations

Artifacts Runtime

Data model

Container and version methods

Publish a generated file

Security and lifecycle rules

​Data model

​Container and version methods

​Link and share methods

​Publish a generated file

​Security and lifecycle rules

Data model

Container and version methods

Link and share methods

Publish a generated file

Security and lifecycle rules