Install
This installs both the CLI and the Python client library.
Initialize the client
from artifacta import Client
# Option 1: Auto-detect from environment or config file
client = Client()
# Reads ARTIFACTA_API_KEY from env, then ~/.config/artifacta/config.toml
# Also reads ARTIFACTA_SESSION_ID and ARTIFACTA_AGENT_ID as defaults
# Option 2: Explicit API key
client = Client(api_key="ak_live_abc123")
# Option 3: Custom base URL
client = Client(base_url="https://api.artifacta.dev")
Zero-config for agents: If ARTIFACTA_API_KEY and ARTIFACTA_SESSION_ID are set in the environment, Client() with no arguments is all you need. Every push() call inherits the session automatically.
Methods at a glance
Write
| Method | Description |
|---|
push() | Upload a file from disk or bytes |
push_dict() | Serialize a dict to JSON and upload |
delete() | Soft-delete an artifact |
create_link() | Create a temporary download URL |
extend_ttl() | Extend artifact expiration |
seal_session() | Seal a session |
Read
| Method | Description |
|---|
pull() | Download to a file path |
pull_bytes() | Download as bytes (in memory) |
pull_dict() | Download and parse as JSON dict |
list() | List artifacts with filters |
get() | Get artifact metadata |
Utilities
| Method | Description |
|---|
Client.session_new() | Generate a session ID locally (static, no API call) |
whoami() | Verify auth and get tenant info |
Quick example
from artifacta import Client
client = Client()
# Push a file
artifact = client.push(
"report.pdf",
session_id="run_q4",
agent_id="earnings_bot",
metadata={"model": "claude-sonnet-4-6"}
)
print(artifact.id) # art_2xk9f7v3m1p0
print(artifact.size_bytes) # 250880
# Push structured data
artifact = client.push_dict(
{"results": [1, 2, 3], "score": 0.95},
filename="results.json",
session_id="run_q4"
)
# Pull to disk
client.pull(artifact.id, output="./downloads/")
# Pull as bytes (no disk I/O)
content = client.pull_bytes(artifact.id)
# Pull as dict
data = client.pull_dict(artifact.id)
# List with filters
for a in client.list(session_id="run_q4", metadata={"model": "claude-sonnet-4-6"}):
print(f"{a.id}: {a.filename}")
# Create a shareable link
link = client.create_link(artifact.id, expires_in=86400)
print(link.url) # https://dl.artifacta.dev/lnk_xxx
# Seal a session
client.seal_session("run_q4")
Error handling
All methods raise typed exceptions matching the API error taxonomy:
from artifacta import (
Client,
ArtifactNotFoundError,
ArtifactExpiredError,
SessionSealedError,
QuotaExceededError,
RateLimitedError,
)
client = Client()
try:
artifact = client.push("output.json", session_id="run_42")
except SessionSealedError:
print("Session is finalized — use a new session")
except QuotaExceededError:
print("Storage or request limit reached — delete artifacts or upgrade")
except RateLimitedError as e:
print(f"Throttled — retry in {e.retry_after_seconds}s")
Environment variable defaults
The SDK respects the same environment variables as the CLI:
| Variable | SDK behavior |
|---|
ARTIFACTA_API_KEY | Used by Client() if no explicit api_key param |
ARTIFACTA_API_URL | Used as base_url default |
ARTIFACTA_SESSION_ID | Default session_id for push() and list() |
ARTIFACTA_AGENT_ID | Default agent_id for push() |
