Artifacts

Produced and consumed

An artifact is a first-class value: a run can both produce one and consume one. A workflow is, in effect, a function over artifacts — it takes zero or more artifacts (plus intake) and produces one.

Workflow : Artifact* -> Artifact

This is why composition works two ways. A workflow can obtain an input artifact by generating it inline (a sub-workflow) or by accepting one you already have (an artifact input).

Artifact classes

Provenance

Every artifact references the runId and templateId that produced it, so you can trace prompt, provider, model, timing, cost, and review state from any persisted output through GET /v1/runs/{runId}.

{
  "id": "artifact-0dc32dbb",
  "runId": "run-a1b2c3d4",
  "templateId": "generate-clip-art-asset",
  "artifactClass": "visual",
  "status": "review",
  "content": {
    "type": "image",
    "url": "https://images.esy.com/artifacts/clip-art/artifact-0dc32dbb/processed.webp",
    "storageKey": "artifacts/clip-art/artifact-0dc32dbb/processed.webp",
    "mimeType": "image/webp",
    "width": 1024,
    "height": 1024
  },
  "createdAt": "2026-05-16T22:14:43.711Z"
}

Status values

Visual artifacts

A visual artifact has two files: raw (model output) and processed (post background removal and any QA passes). Both are stored as WebP. The artifact response includes the public url for the processed file; the storageKey is stable and safe to persist on your side.

artifacts/{artifactType}/{artifactId}/raw.webp
artifacts/{artifactType}/{artifactId}/processed.webp

Research artifacts

A research artifact is structured text rather than a file. Its content carries a title, a summary, an ordered list of sections (heading + body), and a list of sources. Sourcing is model-derived today; web-search-backed citations land in a later phase.

{
  "id": "artifact-7c4e91aa",
  "runId": "run-9f8e7d6c",
  "templateId": "generate-research-report",
  "artifactClass": "research",
  "status": "review",
  "content": {
    "type": "research-report",
    "title": "The economics of desalination",
    "summary": "A structured synthesis of cost drivers, energy intensity, and...",
    "sections": [
      { "heading": "Cost drivers", "body": "..." },
      { "heading": "Energy intensity", "body": "..." }
    ],
    "sources": ["IEA 2025 desalination outlook", "..."]
  },
  "createdAt": "2026-05-29T15:02:11.004Z"
}

Research artifacts are reusable on their own and as inputs to other workflows. When a workflow composes a research report through a sub-workflow, the produced artifact (for example, an infographic) carries a sourceReportArtifactId back-reference to the report it was built from.

Artifacts as inputs

A workflow template can declare that it accepts an existing artifact as input. The author adds an intake field of type artifactReference, constrained to the artifact class and type the workflow knows how to read — so the field has a defined consumer and the supplied value can be validated.

{
  "name": "sourceReport",
  "type": "artifactReference",
  "required": false,
  "description": "An existing research report to visualize",
  "artifactClass": "research",
  "artifactType": "research-report"
}

At run time you pass the chosen artifact’s id in intake. The engine loads that artifact and exposes its content at inputs.{field}, which steps reference like any other context — for example {inputs.sourceReport.summary}.

{
  "templateId": "generate-research-infographic",
  "intake": {
    "topic": "The history of dinosaurs",
    "aspectRatio": "3:4",
    "sourceReport": "artifact-7c4e91aa"
  }
}

Generate or supply

A step can declare that a supplied artifact satisfies it. When the input is present, the step is skipped and the supplied artifact fills its output slot; when it is absent, the step runs normally — for example, generating the artifact through a sub-workflow. Downstream steps read the same reference either way, so “generate a fresh one” and “use this existing one” are interchangeable to the rest of the workflow.

See the compose with artifact inputs guide for a worked example.

Video and knowledge artifacts have their own content shapes; those will be documented here as each class ships its public contract.