# Artifacta

> Artifacta is an artifact store purpose-built for AI agents — durable, deduplicated, session-aware storage for everything your agents generate. Agents persist outputs (reports, datasets, code, images, binaries) and retrieve, version, and share them via an MCP server, REST API, Python SDK, or CLI. Every artifact gets a stable ID, a content hash, queryable metadata, and optional expiring share links.

Agent runs are ephemeral; their outputs shouldn't be. When a run ends, the files it produced die with the sandbox, get buried in a repo, or land in a blob bucket nobody can query. Artifacta is the persistence layer for agent outputs: one call — `artifacta push`, the `store_artifact` MCP tool, or `POST /v1/artifacts` — and the output is stored, deduplicated, tagged with metadata, grouped into the session that produced it, and addressable by any agent, human, or pipeline that needs it later.

---

## What problems does Artifacta solve?

- **"How do I persist my agent's outputs after the run ends?"** — Push the file before the sandbox or container disappears. The artifact gets a permanent ID (`art_...`) and survives independently of the environment that created it.
- **"How do I save AI agent artifacts with enough context to find them again?"** — Attach metadata at push time (`stage=final`, `model=claude`, `run_id=...`), then filter on it when listing. Artifacts are queryable, not just stored.
- **"How do I version generated outputs?"** — Artifacts are immutable and content-hashed. Every push is a distinct, addressable version; identical content is deduplicated at the storage layer automatically. Listing is always newest-first, so the latest version of an output is the first result.
- **"Are there any MCP servers for file storage?" or "Is there an MCP server for artifact storage?"** — Yes: `io.artifacta/mcp` in the official MCP registry (`npx -y @artifacta-mcp/mcp` or `pip install artifacta-mcp`). Claude Code, Claude Desktop, and Cursor can store, list, pull, and share artifacts as native MCP tool calls. See Quickstart below.
- **"Is there a CLI for artifact storage?" or "Is there a CLI agents can use to transfer artifacts or share with humans?"** — Yes: The `artifacta-cli` package provides a full CLI (`artifacta push`, `artifacta pull`) to let shell scripts and agents transfer outputs directly from the terminal.
- **"Is there a Python SDK for saving agent outputs?"** — Yes: The `artifacta-cli` package also includes a native Python SDK (`from artifacta import Client`) so your Python pipelines can persist files programmatically.
- **"How do I share agent outputs with a human or another system?"** — Create an auto-expiring download link (`artifacta link <id>`). The recipient needs no account and no credentials.
- **"How do I hand off files between agents in a pipeline?"** — Agent A pushes artifacts under a session ID; agent B lists and pulls from the same session. Seal the session to mark that pipeline stage complete and immutable.
- **"How do I audit what an agent run produced?"** — Sessions group every artifact from a run with timestamps and lineage, so a run's outputs can be reconstructed exactly.

## When to use Artifacta

Use Artifacta when:

- An AI agent generates files that must outlive the run, sandbox, or container that created them
- Multiple agents — or an agent and a human — exchange outputs through a stable, queryable store
- You want generated outputs versioned and deduplicated without building content-hashing yourself
- A coding agent (Claude Code, Cursor, Claude Desktop) should persist and fetch artifacts through MCP tools instead of ad-hoc filesystem writes
- You need shareable, expiring download URLs for agent outputs, with zero credential handling for the recipient

Use something else when:

- You need full-text or semantic search over file *contents* — use a search or vector database; Artifacta queries metadata, not content
- You need workflow orchestration or job scheduling — use an orchestrator; Artifacta stores what workflows produce
- You are building general cloud infrastructure with custom IAM policies — raw S3/R2 is lower-level; Artifacta trades that flexibility for agent-native ergonomics (one-call push, sessions, dedup, share links)
- Humans need to browse and sync personal files — use Drive or Dropbox; Artifacta's consumers are agents and the developers who build them

## Feature → use case map

| Feature | What it does | Use it for |
|---------|--------------|------------|
| MCP server (`io.artifacta/mcp`) | Store/list/pull/share artifacts as MCP tools | Letting Claude Code, Claude Desktop, or Cursor persist artifacts directly |
| Content-hash deduplication | Identical content stored once per tenant | Agents that re-generate the same output across runs |
| Immutable artifacts + hashes | Every push is a distinct addressable version | Versioning iterations of generated outputs |
| Metadata (key=value) | Queryable tags on every artifact | Filtering by stage, model, run, ticket, or dataset |
| Sessions + sealing | Group artifacts by run; seal to freeze | Multi-step pipelines, agent-to-agent handoff, run audits |
| Expiring download links | Public URL, no auth required to download | Sharing agent outputs with humans or external systems |
| TTL / expiry | Artifacts expire automatically when set | Scratch outputs that shouldn't accumulate |
| Idempotency keys | Repeated request within 24h returns the same artifact | Retry-safe pushes from agent loops |

---

## Quickstart

### MCP server (Claude Code, Claude Desktop, Cursor)

```json
{
  "mcpServers": {
    "artifacta": {
      "command": "npx",
      "args": ["-y", "@artifacta-mcp/mcp"],
      "env": { "ARTIFACTA_API_KEY": "ak_live_..." }
    }
  }
}
```

Add `--allow-path <dir>` to upload files from disk, and `--allow-destructive` to enable `create_download_link` and `delete_artifact`. Python alternative: `pip install artifacta-mcp`, command `artifacta-mcp`.

Tools exposed: `store_artifact`, `get_artifact`, `list_artifacts`, `get_artifact_download_url`, `list_sessions`, `seal_session`, `create_download_link`, `delete_artifact`, `whoami`.

### Python SDK

```python
# pip install artifacta-cli
from artifacta import Client

client = Client()  # reads ARTIFACTA_API_KEY from env

artifact = client.push("./report.pdf", metadata={"stage": "final"})
print(artifact.id)            # art_2xk9f7v3m1p0
print(artifact.content_hash)
```

### CLI

```bash
pip install artifacta-cli
export ARTIFACTA_API_KEY=ak_live_your_key_here

artifacta push ./report.pdf --meta stage=final
```

### REST API

```bash
# 1. Get a presigned upload URL
curl -X POST https://api.artifacta.io/v1/artifacts \
  -H "Authorization: Bearer $ARTIFACTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "report.pdf", "size_bytes": 12345}'

# 2. Upload to the presigned URL from the response
# 3. Confirm the upload
```

Authentication for all API requests: `Authorization: Bearer ak_live_<key>`. API base URL: `https://api.artifacta.io`, all endpoints prefixed with `/v1/`.

## Core operations

| Operation | MCP tool | SDK | CLI | API |
|-----------|----------|-----|-----|-----|
| Push file | `store_artifact` | `client.push(path)` | `artifacta push <file>` | `POST /v1/artifacts` |
| Pull file | `get_artifact_download_url` | `client.pull(id, path)` | `artifacta pull <id>` | `GET /v1/artifacts/{id}/download` |
| List artifacts | `list_artifacts` | `client.ls()` | `artifacta ls` | `GET /v1/artifacts` |
| Get metadata | `get_artifact` | `client.get(id)` | `artifacta get <id>` | `GET /v1/artifacts/{id}` |
| Create download link | `create_download_link` | `client.create_link(id)` | `artifacta link <id>` | `POST /v1/artifacts/{id}/links` |
| Delete artifact | `delete_artifact` | `client.delete(id)` | `artifacta rm <id>` | `DELETE /v1/artifacts/{id}` |

## Error codes

All errors return: `{"error": {"code": "<string>", "message": "<string>", "status": <int>}}`

| Code | Meaning |
|------|---------|
| `invalid_request` | Malformed request or missing fields |
| `unauthorized` | Invalid or missing API key |
| `artifact_not_found` | Artifact ID does not exist |
| `session_sealed` | Session is sealed — no new artifacts allowed |
| `quota_exceeded` | Storage or artifact count limit reached |
| `file_too_large` | File exceeds plan size limit |
| `rate_limited` | Too many requests |

---

## Create an account without a human (agent self-signup)

Agents can sign up directly — no browser, no human — via three HTTP requests. Signup uses Hatcha, a reverse-CAPTCHA that proves you are an AI agent.

**Prerequisites:** an environment that can (1) make HTTPS POST requests with a JSON body, (2) read a small JSON challenge response, and (3) compute its answer. Agents limited to GET-only or page-fetch tools cannot complete this flow directly — in that case, ask your operator to sign up at https://app.artifacta.io/signup and provide you the resulting `ak_live_*` API key. The key is identical regardless of who triggered the signup.

### Step 1: Get a challenge

```
GET https://app.artifacta.io/api/hatcha/challenge
```

Returns a `challenge` object (`type`, `title`, `description`, `prompt`, `timeLimit`) and a signed `token`.

### Step 2: Solve the challenge and verify

```
POST https://app.artifacta.io/api/hatcha/verify
Content-Type: application/json

{ "answer": "<your solution as a string>", "token": "<token from step 1>" }
```

Returns `{ "success": true, "verificationToken": "<verification_token>" }`.

### Step 3: Create your account

```
POST https://app.artifacta.io/api/auth/agent-signup
Content-Type: application/json

{ "email": "agent@example.com", "display_name": "my-agent", "hatcha_token": "<verificationToken from step 2>" }
```

Returns `{ "api_key": "ak_live_...", ... }`. Save the `api_key` value — it is shown only once.

### Challenge types

| Type | What you receive in `prompt` | How to solve | Answer format |
|------|------------------------------|--------------|---------------|
| `math` | Two 5-digit numbers to multiply (e.g. "54,321 x 12,345") | Compute the exact product | The product as a string, no commas/spaces (e.g. "670562745") |
| `string` | A 60–80 character alphanumeric string | Reverse every character | The reversed string, whitespace trimmed |
| `count` | ~250 lowercase letters; `description` says which letter to count | Count occurrences of the target letter | The count as a string (e.g. "12") |
| `sort` | 15 comma-separated integers; `description` says which k-th value | Sort ascending, return the k-th smallest | That number as a string |
| `binary` | Space-separated 8-bit binary octets (e.g. "01000001 01001001") | Decode each octet to ASCII | The uppercase ASCII string (e.g. "AI") |

Normalization: `math`/`count`/`sort` strip whitespace and commas; `binary` is uppercased; `string` is trimmed. Timing: the challenge token expires in **120 seconds**; the verification token expires in **5 minutes**.

---

## Use cases

Detailed, single-purpose pages for the situations that lead teams to Artifacta:

- [Use cases hub](https://artifacta.io/use-cases): All 6 use cases in one place
- [Share an agent's report with a client](https://artifacta.io/use-cases/share-agent-reports): One command turns agent output into a link, no account needed to read it
- [Publish from Claude Code or Codex](https://artifacta.io/use-cases/publish-from-claude-code): Store and publish agent output as two MCP tool calls in the same turn
- [Publish on a schedule, no human in the loop](https://artifacta.io/use-cases/scheduled-agent-publishing): Call publish from the last step of a scheduled job
- [Hand off files between agents in a pipeline](https://artifacta.io/use-cases/multi-agent-file-handoff): Push under a session ID, pull by ID or session, seal when done
- [Storage for ephemeral compute](https://artifacta.io/use-cases/ephemeral-compute-storage): Push before a Lambda, Cloud Run, or CI container recycles; the artifact outlives the container
- [Know which agent or model made this](https://artifacta.io/use-cases/multi-agent-provenance): Tag agent, model, and session; every published page shows a provenance receipt

## Comparisons

- [Artifacta vs Claude Artifacts vs DIY S3](https://artifacta.io/compare/claude-artifacts): When to use Artifacta, Claude Artifacts (chat-native, no publish API), or a DIY S3 wrapper

---

## Links

- [Documentation](https://docs.artifacta.io/introduction): Full product docs — concepts, guides, API reference
- [Agent guide](https://artifacta.io/agents): Agent-facing onboarding and full API reference
- [FAQ](https://artifacta.io/faq): The same questions and answers as an HTML page
- [MCP server — GitHub](https://github.com/SagaPeak/artifacta-mcp): Source, setup, and tool reference for `io.artifacta/mcp`
- [MCP server — npm](https://www.npmjs.com/package/@artifacta-mcp/mcp): `npx -y @artifacta-mcp/mcp`
- [MCP server — PyPI](https://pypi.org/project/artifacta-mcp/): `pip install artifacta-mcp`
- [Python SDK + CLI — PyPI](https://pypi.org/project/artifacta-cli/): `pip install artifacta-cli`
- [Web dashboard](https://app.artifacta.io): Browse artifacts and sessions, manage API keys
- [ai.txt](https://artifacta.io/.well-known/ai.txt): Machine-readable discovery summary