> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artifacta.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK Overview

> Install, initialize, and use the Artifacta Python client.

## Install

```bash theme={null}
pip install artifacta-cli
```

This installs both the CLI and the Python client library.

## Initialize the client

```python theme={null}
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")
```

<Tip>
  **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.
</Tip>

## Methods at a glance

### Write

| Method | Description |
| - | - |
| [`push()`](/sdk/push) | Upload a file from disk or bytes |
| [`push_dict()`](/sdk/push-dict) | Serialize a dict to JSON and upload |
| [`delete()`](/sdk/delete) | Soft-delete an artifact |
| [`create_link()`](/sdk/create-link) | Create a temporary download URL |
| [`seal_session()`](/sdk/seal-session) | Seal a session |
| [`publish_artifact()`](#publish_artifact) | Publish an artifact as a shareable public page |
| [`unpublish()`](#unpublish) | Take down an artifact's public page |

### Read

| Method | Description |
| - | - |
| [`pull()`](/sdk/pull) | Download to a file path |
| [`pull_bytes()`](/sdk/pull-bytes) | Download as bytes (in memory) |
| [`pull_dict()`](/sdk/pull-dict) | Download and parse as JSON dict |
| [`list()`](/sdk/list) | List artifacts with filters |
| [`get()`](/sdk/get) | Get artifact metadata |

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

### Utilities

| Method | Description |
| - | - |
| [`Client.session_new()`](/sdk/session-new) | Generate a session ID locally (static, no API call) |
| [`whoami()`](/sdk/whoami) | Verify auth and get tenant info |

## Quick example

```python theme={null}
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()`

```python theme={null}
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`.

```python theme={null}
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()`

```python theme={null}
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`.

```python theme={null}
# 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](/errors):

```python theme={null}
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](/sdk/errors) 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()` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.