Python SDK Overview

Install

pip install artifacta-cli

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.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

The existing push(..., transcript=True) and list(..., transcript=True) calls store and filter transcripts. See the session transcript guide for their exact signatures and precedence.

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-fable-5"}  # stored as metadata.model — a declared producer claim
)
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-fable-5"}):
    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

Publishes an artifact as a shareable page at 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"`.

Returns a 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

Soft-unpublishes an artifact page. The artifact itself is not deleted. Accepts an artifact ID (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")

See the full exception reference for the complete mapping.

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()`

​Install

​Initialize the client

​Methods at a glance

​Write

​Read

​Utilities

​Quick example

​publish_artifact()

​unpublish()

​Error handling

​Environment variable defaults

Install

Initialize the client

Methods at a glance

Write

Read

Utilities

Quick example

`publish_artifact()`

`unpublish()`

Error handling

Environment variable defaults