Artifacts

Artifacts are the outputs produced by action runs. When an action executes, it may generate data files, reports, or structured results — these are stored as artifacts for later retrieval.

Concept

Every artifact:

Is linked to the action run that created it
Has a kind (JSON, text, or file)
Is stored either inline (in the database) or in S3 (for large files)
Is immutable once created

Artifact Types

Kind	Storage	Use Case
`JSON`	Inline (JSONB)	Structured data, API responses, metadata
`TEXT`	Inline	Logs, summaries, generated content
`FILE`	S3	Parquet files, exports, large datasets

Storage Patterns

Artifacts use two storage strategies:

For JSON and text artifacts, content is stored directly in the database:

{
  "kind": "json",
  "storage": "inline",
  "data": {
    "records_processed": 1250,
    "tables": ["orders", "products"]
  }
}

Advantages:

Fast retrieval (no S3 roundtrip)
Atomic with the action run
Queryable via JSON operators

For file artifacts, only a reference is stored in the database:

{
  "kind": "file",
  "storage": "s3",
  "bucket": "vai-flux-artifacts",
  "key": "tenant_id=abc/run_id=xyz/orders.parquet",
  "size_bytes": 15000000,
  "etag": "abc123...",
  "original_filename": "orders.parquet"
}

Advantages:

Unlimited file size
Efficient for binary data
Cost-effective for large datasets

Artifact Lifecycle

Relationship to Action Runs

Every artifact is linked to an action run via action_run_id. This enables:

Traceability — Know exactly which execution produced each output
Audit trails — Review what was generated and when
Cleanup — Delete artifacts when their parent run is archived

In chat conversations, artifacts created by tools are linked through the turn's action runs, enabling the assistant to reference and display results.

API Endpoints

List Artifacts

GET /api/v1/artifacts?action_run_id={run_id}

Returns artifacts for a specific action run.

Get Artifact

GET /api/v1/artifacts/{artifact_id}

Returns artifact metadata and content (or signed URL for files).

Create Artifact

POST /api/v1/artifacts
Content-Type: application/json

{
  "action_run_id": "run_xyz789",
  "kind": "json",
  "title": "Extraction Summary",
  "content": {
    "storage": "inline",
    "data": { "records": 1250, "status": "success" }
  }
}

Delete Artifact

DELETE /api/v1/artifacts/{artifact_id}

Soft-deletes an artifact. The record remains for audit purposes but content is inaccessible.

Common Use Cases

Data Extraction Results

When a dlt_extract action completes, it creates artifacts for:

Summary — Record counts, duration, resource status
Files — Parquet files written to bronze layer

Transform Outputs

duckdb_transform actions create artifacts documenting:

Row counts — Records read and written
Schema — Output table structure
Location — Delta table path in silver/gold layer

Chat Tool Results

When chat tools execute actions, artifacts capture:

Search results — Web search responses
Query results — Database query outputs
Generated content — AI-produced summaries

Best Practices

Use descriptive titles — Make artifacts easy to identify in listings
Prefer JSON for structured data — Enables querying and programmatic access
Use files for large datasets — Keep database lean, leverage S3 for bulk data
Link to parent runs — Always provide action_run_id for traceability

OpenAPI Reference

For detailed endpoint schemas:

Artifact Endpoints

Full OpenAPI documentation for artifact management

Artifacts

Artifact Endpoints

On this page