Artifacts

Persistent key-value storage for AI-generated content

Artifacts in Open WebUI provide a built-in key-value storage API for persistent data. This enables AI models to create and maintain long-lived content such as journals, trackers, leaderboards, collaborative tools, and interactive applications that persist across chat sessions.

Overview

Artifacts enable:

• Persistent key-value data storage
• Personal and shared data scopes
• JSON-based structured data
• Cross-session persistence
• Collaborative features
• Interactive AI-powered applications

Artifacts are built directly into Open WebUI, providing a simple storage API that AI models can use to create stateful applications without external databases.

What Are Artifacts?

Artifacts are persistent data objects that survive beyond individual chat conversations. Unlike memories which store context and preferences, artifacts store structured application data.

Common use cases:

• Journals: Daily logs and note-taking
• Trackers: Habit tracking, goal monitoring
• Leaderboards: Competitive rankings and scores
• Dashboards: Data visualization and metrics
• Collaborative Docs: Shared documents and wikis
• Games: Persistent game state

Data Scopes

Artifacts support two data scopes:

Personal Scope

Data accessible only to the individual user:

// Store personal data
const personalData = {
  key: "my-journal",
  scope: "personal",
  value: {
    entries: [
      {
        date: "2024-03-02",
        content: "Today I learned about artifacts..."
      }
    ]
  }
};

Shared Scope

Data accessible to all users (workspace-wide):

// Store shared data
const sharedData = {
  key: "team-leaderboard",
  scope: "shared",
  value: {
    scores: [
      { user: "Alice", points: 150 },
      { user: "Bob", points: 120 }
    ]
  }
};

Storage Operations

Store Data

Save or update an artifact:

import requests
import json

url = "http://localhost:8080/api/artifacts/store"
payload = {
    "key": "habit-tracker",
    "scope": "personal",
    "value": {
        "habits": [
            {"name": "Exercise", "completed": ["2024-03-01", "2024-03-02"]},
            {"name": "Reading", "completed": ["2024-03-01"]}
        ]
    }
}

response = requests.post(url, json=payload)
result = response.json()

if result["success"]:
    print("Artifact stored successfully")

Retrieve Data

Get an artifact by key:

import requests

url = "http://localhost:8080/api/artifacts/get"
params = {
    "key": "habit-tracker",
    "scope": "personal"
}

response = requests.get(url, params=params)
artifact = response.json()

if artifact:
    print(f"Habits: {artifact['value']['habits']}")
else:
    print("Artifact not found")

List Artifacts

Get all artifacts for a scope:

import requests

# List personal artifacts
response = requests.get(
    "http://localhost:8080/api/artifacts/list",
    params={"scope": "personal"}
)
personal_artifacts = response.json()

for artifact in personal_artifacts:
    print(f"Key: {artifact['key']}")
    print(f"Updated: {artifact['updated_at']}")

Delete Artifact

Remove an artifact:

import requests

url = "http://localhost:8080/api/artifacts/delete"
params = {
    "key": "old-tracker",
    "scope": "personal"
}

response = requests.delete(url, params=params)

if response.json()["success"]:
    print("Artifact deleted")

Example Applications

Daily Journal

Journal Application

import requests
from datetime import datetime

class JournalApp:
    def __init__(self):
        self.base_url = "http://localhost:8080/api/artifacts"
        self.key = "daily-journal"
    
    def add_entry(self, content):
        """Add a new journal entry."""
        # Get existing journal
        response = requests.get(
            f"{self.base_url}/get",
            params={"key": self.key, "scope": "personal"}
        )
        
        journal = response.json() or {"entries": []}
        
        # Add new entry
        entry = {
            "date": datetime.now().isoformat(),
            "content": content
        }
        journal["entries"].append(entry)
        
        # Save updated journal
        requests.post(
            f"{self.base_url}/store",
            json={
                "key": self.key,
                "scope": "personal",
                "value": journal
            }
        )
    
    def get_recent_entries(self, count=5):
        """Get recent journal entries."""
        response = requests.get(
            f"{self.base_url}/get",
            params={"key": self.key, "scope": "personal"}
        )
        
        journal = response.json()
        if journal:
            entries = journal["entries"][-count:]
            return entries
        return []

# Usage
journal = JournalApp()
journal.add_entry("Today I learned about Open WebUI artifacts!")
recent = journal.get_recent_entries(3)

Habit Tracker

Habit Tracker Application

import requests
from datetime import datetime, date

class HabitTracker:
    def __init__(self):
        self.base_url = "http://localhost:8080/api/artifacts"
        self.key = "habit-tracker"
    
    def add_habit(self, habit_name):
        """Create a new habit to track."""
        tracker = self._load_tracker()
        
        if habit_name not in tracker["habits"]:
            tracker["habits"][habit_name] = {
                "created": datetime.now().isoformat(),
                "completed_dates": []
            }
            self._save_tracker(tracker)
    
    def mark_complete(self, habit_name, date_str=None):
        """Mark a habit as completed for today or specific date."""
        if date_str is None:
            date_str = date.today().isoformat()
        
        tracker = self._load_tracker()
        
        if habit_name in tracker["habits"]:
            completed = tracker["habits"][habit_name]["completed_dates"]
            if date_str not in completed:
                completed.append(date_str)
                self._save_tracker(tracker)
    
    def get_streak(self, habit_name):
        """Calculate current streak for a habit."""
        tracker = self._load_tracker()
        
        if habit_name not in tracker["habits"]:
            return 0
        
        completed = sorted(
            tracker["habits"][habit_name]["completed_dates"],
            reverse=True
        )
        
        streak = 0
        current_date = date.today()
        
        for completed_date in completed:
            if completed_date == current_date.isoformat():
                streak += 1
                current_date = current_date - timedelta(days=1)
            else:
                break
        
        return streak
    
    def _load_tracker(self):
        response = requests.get(
            f"{self.base_url}/get",
            params={"key": self.key, "scope": "personal"}
        )
        return response.json() or {"habits": {}}
    
    def _save_tracker(self, tracker):
        requests.post(
            f"{self.base_url}/store",
            json={
                "key": self.key,
                "scope": "personal",
                "value": tracker
            }
        )

# Usage
tracker = HabitTracker()
tracker.add_habit("Exercise")
tracker.mark_complete("Exercise")
print(f"Current streak: {tracker.get_streak('Exercise')} days")

Team Leaderboard

Leaderboard Application

import requests
from typing import List, Dict

class Leaderboard:
    def __init__(self, board_name="default"):
        self.base_url = "http://localhost:8080/api/artifacts"
        self.key = f"leaderboard-{board_name}"
    
    def add_score(self, user_name: str, points: int):
        """Add or update a user's score."""
        board = self._load_board()
        
        # Find existing user
        user_entry = next(
            (u for u in board["scores"] if u["name"] == user_name),
            None
        )
        
        if user_entry:
            user_entry["points"] += points
        else:
            board["scores"].append({
                "name": user_name,
                "points": points
            })
        
        # Sort by points (descending)
        board["scores"].sort(key=lambda x: x["points"], reverse=True)
        
        self._save_board(board)
    
    def get_top(self, count: int = 10) -> List[Dict]:
        """Get top N players."""
        board = self._load_board()
        return board["scores"][:count]
    
    def get_rank(self, user_name: str) -> int:
        """Get a user's rank (1-based)."""
        board = self._load_board()
        
        for i, entry in enumerate(board["scores"], start=1):
            if entry["name"] == user_name:
                return i
        
        return -1  # Not found
    
    def _load_board(self):
        response = requests.get(
            f"{self.base_url}/get",
            params={"key": self.key, "scope": "shared"}
        )
        return response.json() or {"scores": []}
    
    def _save_board(self, board):
        requests.post(
            f"{self.base_url}/store",
            json={
                "key": self.key,
                "scope": "shared",
                "value": board
            }
        )

# Usage
board = Leaderboard("weekly-challenge")
board.add_score("Alice", 50)
board.add_score("Bob", 30)
board.add_score("Alice", 20)  # Alice now has 70 total

top_players = board.get_top(5)
for i, player in enumerate(top_players, start=1):
    print(f"{i}. {player['name']}: {player['points']} points")

Interactive Dashboard

Dashboard Application

import requests
from datetime import datetime, timedelta

class MetricsDashboard:
    def __init__(self):
        self.base_url = "http://localhost:8080/api/artifacts"
        self.key = "metrics-dashboard"
    
    def log_metric(self, metric_name: str, value: float):
        """Log a metric value with timestamp."""
        dashboard = self._load_dashboard()
        
        if metric_name not in dashboard["metrics"]:
            dashboard["metrics"][metric_name] = []
        
        dashboard["metrics"][metric_name].append({
            "timestamp": datetime.now().isoformat(),
            "value": value
        })
        
        # Keep only last 100 entries per metric
        dashboard["metrics"][metric_name] = \
            dashboard["metrics"][metric_name][-100:]
        
        self._save_dashboard(dashboard)
    
    def get_latest(self, metric_name: str):
        """Get the most recent value for a metric."""
        dashboard = self._load_dashboard()
        
        if metric_name in dashboard["metrics"]:
            entries = dashboard["metrics"][metric_name]
            if entries:
                return entries[-1]["value"]
        
        return None
    
    def get_average(self, metric_name: str, hours: int = 24):
        """Calculate average over the last N hours."""
        dashboard = self._load_dashboard()
        
        if metric_name not in dashboard["metrics"]:
            return None
        
        cutoff = datetime.now() - timedelta(hours=hours)
        entries = dashboard["metrics"][metric_name]
        
        recent = [
            e["value"] for e in entries
            if datetime.fromisoformat(e["timestamp"]) > cutoff
        ]
        
        return sum(recent) / len(recent) if recent else None
    
    def _load_dashboard(self):
        response = requests.get(
            f"{self.base_url}/get",
            params={"key": self.key, "scope": "shared"}
        )
        return response.json() or {"metrics": {}}
    
    def _save_dashboard(self, dashboard):
        requests.post(
            f"{self.base_url}/store",
            json={
                "key": self.key,
                "scope": "shared",
                "value": dashboard
            }
        )

# Usage
dashboard = MetricsDashboard()
dashboard.log_metric("cpu_usage", 45.2)
dashboard.log_metric("memory_usage", 62.8)

print(f"Current CPU: {dashboard.get_latest('cpu_usage')}%")
print(f"Avg CPU (24h): {dashboard.get_average('cpu_usage', 24):.1f}%")

Best Practices

Data Structure

1. Use JSON: Store well-structured JSON data
2. Version Your Schema: Include version fields for migrations
3. Keep It Small: Store only necessary data
4. Index When Needed: Use keys that facilitate lookups

# Good: Structured, versioned data
artifact = {
    "key": "user-settings",
    "value": {
        "version": "1.0",
        "preferences": {
            "theme": "dark",
            "language": "en"
        },
        "updated_at": "2024-03-02T10:00:00Z"
    }
}

Performance

1. Cache Locally: Don’t fetch on every operation
2. Batch Updates: Combine multiple changes
3. Limit Size: Keep artifacts under 1MB
4. Clean Old Data: Implement data retention policies

Security

1. Validate Input: Always validate before storing
2. Sanitize Output: Clean data before display
3. Scope Appropriately: Use personal scope for sensitive data
4. Don’t Store Secrets: Never store passwords or API keys

Error Handling

import requests

def safe_artifact_operation():
    try:
        response = requests.post(
            "http://localhost:8080/api/artifacts/store",
            json={
                "key": "my-data",
                "scope": "personal",
                "value": {"data": "value"}
            },
            timeout=5
        )
        response.raise_for_status()
        return response.json()
    
    except requests.exceptions.Timeout:
        print("Request timed out")
    except requests.exceptions.HTTPError as e:
        print(f"HTTP error: {e}")
    except Exception as e:
        print(f"Error: {e}")
    
    return None

Troubleshooting

Artifact Not Found

• Verify the key is correct
• Check you’re using the right scope (personal vs shared)
• Ensure the artifact was successfully saved
• Confirm you have permission to access the scope

Data Not Persisting

• Check the API response for errors
• Verify JSON data is valid
• Ensure sufficient storage space
• Review application logs

Performance Issues

• Reduce artifact size
• Implement caching
• Limit update frequency
• Archive old data

Next Steps

• Learn about Memories for context storage
• Explore Functions to create artifact-powered tools
• Build Skills that leverage artifacts