Install
pip install artifacta-cli
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.io")
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 |
seal_session() | Seal a session |
publish_artifact() | Publish an artifact as a shareable public page |
unpublish() | Take down an artifact’s public page |
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.io/lnk_xxx
# Seal a session
client.seal_session("run_q4")
publish_artifact()
publish_artifact(
artifact_id: str,
*,
title: str | None = None,
visibility: str = "unlisted",
access: str = "none",
password: str | None = None,
) -> dict
https://artifacta.io/a/{slug}. Idempotent — re-publishing the same artifact updates the page and keeps the same URL.
| Parameter | Type | Default | Description |
|---|
artifact_id | str | — | Artifact ID to publish. |
title | str | None | None | Page title. |
visibility | str | "unlisted" | "unlisted" (URL-only) or "public" (discoverable). |
access | str | "none" | "none" (open) or "password" (Pro plan). |
password | str | None | None | Required when access="password". |
dict with page_id, public_url, visibility, and access.
from artifacta import Client
client = Client()
# Publish an artifact as an unlisted page
page = client.publish_artifact("art_abc123")
print(page["public_url"]) # https://artifacta.io/a/pg_...
# Publish publicly with a title
page = client.publish_artifact(
"art_abc123",
title="Q2 Report",
visibility="public",
)
# Publish with password protection (Pro plan)
page = client.publish_artifact(
"art_abc123",
access="password",
password="hunter2",
)
unpublish()
unpublish(id_or_slug: str) -> dict
art_...) or a page slug (pg_...).
Returns a dict with page_id and unpublished: True.
# Unpublish by artifact ID
result = client.unpublish("art_abc123")
print(result["page_id"]) # pg_...
# Unpublish by page slug
result = client.unpublish("pg_aB3xK9mP1qR5sT2u")
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() |
