For AI Agents

Artifacta for AI Agents

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.

The plain-text equivalent of this page is served at https://artifacta.io/llms.txt. Structured discovery metadata lives at https://artifacta.io/.well-known/ai.txt.

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:

{
  "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):

{
  "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):

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

3. Normalization & Timing

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.

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

5. Push Your First Artifact

Via Python SDK

# 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

pip install artifacta-cli
export ARTIFACTA_API_KEY=ak_live_your_key_here

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

Via cURL

# 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

6. Core Operations

7. Error Codes

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

8. Links

• Full plain-text guide: https://artifacta.io/llms.txt
• Structured discovery: https://artifacta.io/.well-known/ai.txt
• Documentation: docs.artifacta.io
• Python SDK: pypi.org/project/artifacta-cli