Artifacts
An Artifact is a document, file, dataset, or link associated with a workflow or task. Artifacts are versioned — each time the content changes, a new version is appended to the history. Artifacts can be marked required, blocking a task from completing until the artifact is present and approved.
When to use client.artifacts
- Attaching a generated report or contract to a workflow instance for downstream review
- Tracking document versions as a task progresses through revision cycles
- Gating task completion on artifact approval (pair with Approvals)
- Linking external resources (Notion pages, Google Docs, Figma files) to tasks
Methods
| Method | Description |
|---|---|
create(input) | Create a new artifact |
get(artifactId) | Fetch with full version history |
list(opts?) | List artifacts for a workflow, task, or project |
version(artifactId, input) | Append a new version |
attachToTask(artifactId, taskId) | Associate an existing artifact with a task |
update(artifactId, input) | Toggle required flag |
artifacts.create(input)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Human-readable artifact name |
type | string | yes | e.g., 'document', 'file', 'dataset', 'link' |
workflowInstanceId | string | no | Associate with an instance |
taskId | string | no | Associate with a specific task |
contentReference | string | no | URL or storage key for the content |
required | boolean | no | If true, task cannot complete until artifact is present |
typescript
const { data: artifact } = await client.artifacts.create({
name: 'Signed NDA',
type: 'document',
workflowInstanceId: 'wi_abc123',
taskId: 'tsk_xyz',
contentReference: 'https://storage.example.com/ndas/nda-2026-07.pdf',
required: true,
})artifacts.version(artifactId, input)
Appends a new version without replacing the old one.
typescript
await client.artifacts.version('art_abc123', {
contentReference: 'https://storage.example.com/ndas/nda-2026-07-v2.pdf',
metadata: { reviewedBy: 'alice@example.com', approvedAt: '2026-07-01T14:00:00Z' },
})artifacts.get(artifactId)
Returns the artifact with all versions attached (newest first).
typescript
const { data: artifact } = await client.artifacts.get('art_abc123')
console.log(artifact.currentVersion) // 3
console.log(artifact.versions) // [{version: 3, ...}, {version: 2, ...}, {version: 1, ...}]Type reference
typescript
interface Artifact {
id: string
projectId: string | null
workflowInstanceId: string | null
taskId: string | null
name: string
type: string
currentVersion: number
required: boolean
metadata: Record<string, unknown> | null
createdAt: string
updatedAt: string
versions?: ArtifactVersion[]
}
interface ArtifactVersion {
id: string
artifactId: string
version: number
createdByActorId: string | null
contentReference: string | null
metadata: Record<string, unknown> | null
createdAt: string
}