# Artifacta — LLM Agent Guide

Artifacta is an artifact store purpose-built for AI agents. Store, retrieve, and share files (PDF, CSV, JSON, images, binaries) with metadata, session tracking, and content-hash deduplication. Interfaces: REST API, Python SDK (`pip install artifacta-cli`), and CLI.

---

## 1. Create an Account (no browser needed)

Complete three HTTP requests to get an API key. The signup uses Hatcha — a reverse-CAPTCHA that proves you are an AI agent.

### Step 1: Get a challenge

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

Response:
```json
{
  "challenge": {
    "id": "abc123...",
    "type": "math",
    "title": "Speed Arithmetic",
    "description": "Compute the exact product of these two numbers.",
    "prompt": "54,321 x 12,345",
    "timeLimit": 30
  },
  "token": "<challenge_token>"
}
```

### Step 2: Solve the challenge and verify

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

{
  "answer": "670562745",
  "token": "<challenge_token from step 1>"
}
```

Response (success):
```json
{
  "success": true,
  "challengeId": "abc123...",
  "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>"
}
```

Response (success):
```json
{
  "success": true,
  "email": "agent@example.com",
  "verified": true,
  "api_key": "ak_live_...",
  "api_key_id": "key_...",
  "api_key_name": "my-agent-default-key"
}
```

Save the `api_key` value — it is shown only once.

---

## 2. Challenge Types

You will receive one of five challenge types. Solve it and return the answer as a string.

| 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 rules
- `math`, `count`, `sort`: whitespace and commas are stripped before comparison
- `binary`: answer is uppercased before comparison
- `string`: answer is trimmed of leading/trailing whitespace

### Timing
- Challenge token expires in **120 seconds** — solve and verify within this window
- Verification token expires in **5 minutes** — use it to sign up within this window

---

## 3. Authenticate

All API requests require a Bearer token:

```
Authorization: Bearer ak_live_your_key_here
```

API base URL: `https://api.artifacta.io`
All endpoints are prefixed with `/v1/`.

---

## 4. Push Your First Artifact

### Via 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)
```

### Via CLI

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

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

### Via cURL

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

---

## 5. Core Operations

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

---

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

---

## 7. Links

- Full API reference: https://artifacta.io/agents
- Documentation: https://docs.artifacta.io/introduction
- Python SDK: https://pypi.org/project/artifacta-cli/