Authentication
# Set your API key
export ATAI_API_KEY="your-api-key-here"
# Basic API call
curl https://platform.u1.archetypeai.app/api/lens/info \
-H "Authorization: Bearer $ATAI_API_KEY"
Common Patterns
Create and Use a Session
import requests
# 1. Create session
response = requests.post(
"https://platform.u1.archetypeai.app/api/lens/sessions/create",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"lens_id": "lns-fd669361822b07e2-237ab3ffd79199b0"}
)
session = response.json()
# 2. Use WebSocket endpoint for data streaming
# session['session_endpoint'] contains WebSocket URL
# 3. Destroy session when done
requests.post(
"https://platform.u1.archetypeai.app/api/lens/sessions/destroy",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"session_id": session['session_id']}
)
# 1. Create session
SESSION_ID=$(curl -s https://platform.u1.archetypeai.app/api/lens/sessions/create \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"lens_id": "lns-fd669361822b07e2-237ab3ffd79199b0"}' \
| jq -r '.session_id')
# 2. Destroy session
curl https://platform.u1.archetypeai.app/api/lens/sessions/destroy \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"session_id\": \"$SESSION_ID\"}"
Upload and Process Files
import requests
# Upload file
with open('image.png', 'rb') as f:
response = requests.post(
'https://platform.u1.archetypeai.app/api/files',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
files={'file': f}
)
file_data = response.json()
print(f"Uploaded: {file_data['file_id']}")
# List files
response = requests.get(
"https://platform.u1.archetypeai.app/api/files/metadata",
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
files = response.json()["data"]
for file in files:
print(f"- {file['file_id']} ({file['num_bytes']} bytes)")
# Upload file
curl -X POST https://platform.u1.archetypeai.app/api/files \
-H "Authorization: Bearer $ATAI_API_KEY" \
-F "[email protected]"
# List files
curl https://platform.u1.archetypeai.app/api/files/metadata \
-H "Authorization: Bearer $ATAI_API_KEY"
API Endpoints Summary
Agents API
| Method | Endpoint | Description |
|---|---|---|
| Blueprints | ||
POST | /api/agents/blueprints | Create Blueprint |
GET | /api/agents/blueprints | List Blueprints |
GET | /api/agents/blueprints/{reference} | Get Blueprint |
DELETE | /api/agents/blueprints/{reference} | Delete Blueprint |
GET | /api/agents/blueprints/{reference}/versions | List Blueprint Versions |
POST | /api/agents/blueprints/{reference}/copy | Copy Blueprint v2.0.0+ |
| Deployments | ||
POST | /api/agents/deployments | Create Deployment v2.0.1+ |
GET | /api/agents/deployments | List Deployments v2.0.1+ |
GET | /api/agents/deployments/{deployment_id} | Get Deployment v2.0.1+ |
PATCH | /api/agents/deployments/{deployment_id} | Update Deployment v2.0.1+ |
POST | /api/agents/deployments/{deployment_id}/stop | Stop Deployment v2.0.1+ |
DELETE | /api/agents/deployments/{deployment_id} | Delete Deployment v2.0.1+ |
| Evals | ||
POST | /api/agents/evals | Create Eval |
GET | /api/agents/evals | List Evals |
GET | /api/agents/evals/{eval_id} | Get Eval |
DELETE | /api/agents/evals/{eval_id} | Delete Eval |
POST | /api/agents/evals/{eval_id}/cancel | Cancel Eval |
GET | /api/agents/evals/{eval_id}/examples | List Eval Examples |
| Nodes | ||
GET | /agents/nodes/registry | List Node Registry |
| Optimizations | ||
POST | /agents/optimizations | Create Optimization |
GET | /agents/optimizations | List Optimizations |
GET | /agents/optimizations/{optimization_id} | Get Optimization |
DELETE | /agents/optimizations/{optimization_id} | Delete Optimization |
POST | /agents/optimizations/{optimization_id}/cancel | Cancel Optimization |
GET | /agents/optimizations/{optimization_id}/trials | List Optimization Trials |
POST | /agents/optimizations/{optimization_id}/trials/{trial_id}/promote | Promote Trial |
| Packages | ||
POST | /agents/packages | Create Package |
GET | /agents/packages | List Packages |
GET | /agents/packages/{package_id} | Get Package |
DELETE | /agents/packages/{package_id} | Delete Package |
| Sessions | ||
POST | /agents/sessions | Create Session v2.0.1+ |
GET | /agents/sessions | List Sessions v2.0.1+ |
GET | /agents/sessions/{session_id} | Get Session v2.0.1+ |
POST | /agents/sessions/{session_id}/cancel | Cancel Session v2.0.1+ |
DELETE | /agents/sessions/{session_id} | Delete Session v2.0.1+ |
POST | /agents/sessions/{session_id}/query | Query Session v2.0.1+ |
GET | /agents/sessions/{session_id}/events | List Session Events v2.0.1+ |
GET | /agents/sessions/{session_id}/results | Get Session Results v2.0.1+ |
Batch Processing API
| Method | Endpoint | Description |
|---|---|---|
| Jobs | ||
POST | /batch/jobs | Create job |
GET | /batch/jobs | List jobs |
GET | /batch/jobs/{id} | Get job info |
POST | /batch/jobs/{id}/retry | Retry job |
DELETE | /batch/jobs/{id} | Delete job |
POST | /batch/jobs/{id}/cancel | Cancel job |
GET | /batch/jobs/queue | Get global queue depths grouped by pipeline type |
| Events | ||
GET | /batch/jobs/{id}/events | List job events |
| I/O | ||
GET | /batch/jobs/{id}/inputs | List job inputs |
GET | /batch/jobs/{id}/outputs | List job outputs |
| Progress | ||
GET | /batch/jobs/{id}/progress | List job progress |
| Registry: Pipelines | ||
GET | /batch/registry/pipelines | List pipelines |
GET | /batch/registry/pipelines/{id} | Get pipeline info |
GET | /batch/registry/pipelines/{id}/schema | Get pipeline schema |
Files API
| Method | Endpoint | Description |
|---|---|---|
POST | /files | Upload file |
POST | /files/base64 | Upload base64 file |
DELETE | /files/delete/{file_id} | Delete file |
GET | /files/download/{file_id} | Download file |
GET | /files/info | Get files info |
GET | /files/metadata | List all files and their metadata |
GET | /files/metadata/{file_id} | Get a file’s metadata |
POST | /files/uploads/initiate | Initiate a direct-to-cloud upload |
POST | /files/uploads/{upload_id}/parts/urls | Generate presigned URLs for upload parts |
POST | /files/uploads/{upload_id}/parts/checkpoint | Checkpoint completed upload parts |
POST | /files/uploads/{upload_id}/complete | Complete a direct-to-cloud upload |
POST | /files/uploads/{upload_id}/abort | Abort a direct-to-cloud upload |
Fine-Tuning Service
| Method | Endpoint | Description |
|---|---|---|
POST | /fine-tuning/jobs | Create a fine-tuning job |
GET | /fine-tuning/jobs/{id} | Get information about a fine-tuning job |
GET | /fine-tuning/jobs | List fine-tuning jobs |
POST | /fine-tuning/jobs/{id}/pause | Pause a fine-tuning job |
POST | /fine-tuning/jobs/{id}/resume | Resume a fine-tuning job |
POST | /fine-tuning/jobs/{id}/cancel | Cancel a fine-tuning job |
GET | /fine-tuning/jobs/{id}/checkpoints | List the checkpoints saved for a given fine-tuning job |
GET | /fine-tuning/jobs/{id}/events | List the job events for a given fine-tuning job |
GET | /fine-tuning/jobs/{id}/logs | List the events for a given fine-tuning job |
GET | /fine-tuning/jobs/{id}/metrics | List a fine-tuning job’s metrics |
GET | /fine-tuning/checkpoints | List the checkpoints saved for jobs that match the specified filters |
Inference API
| Method | Endpoint | Description |
|---|---|---|
POST | /api/inference/query | Direct Query v2.0.1+ |
POST | /api/inference/chat/completions | Chat Completions v2.0.1+ |
POST | /api/inference/responses | Responses v2.0.1+ |
| Sessions | ||
POST | /api/inference/sessions | Create Model Session v2.0.1+ |
GET | /api/inference/sessions | List Model Sessions v2.0.1+ |
GET | /api/inference/sessions/{session_id} | Get Model Session v2.0.1+ |
POST | /api/inference/sessions/{session_id}/query | Query a Model Session v2.0.1+ |
POST | /api/inference/sessions/{session_id}/chat/completions | Query a Model Session v2.0.1+ |
POST | /api/inference/sessions/{session_id}/responses | Query a Model Session v2.0.1+ |
POST | /api/inference/sessions/{session_id}/cancel | Cancel Model Session v2.0.1+ |
DELETE | /api/inference/sessions/{session_id} | Delete Model Session v2.0.1+ |
Projects API
| Method | Endpoint | Description |
|---|---|---|
POST | /projects | Create Project v2.0.0+ |
GET | /projects | List Projects v2.0.0+ |
GET | /projects/{project_id} | Get Project v2.0.0+ |
PATCH | /projects/{project_id} | Update Project v2.0.0+ |
DELETE | /projects/{project_id} | Delete Project v2.0.0+ |
Direct Query
The Direct Query endpoint is deprecated as of version 2.0.1 of
the Archetype platform and should no longer be used for new code. Use the
Inference API’s
Direct Query endpoint (
POST /api/inference/query) instead.| Method | Endpoint | Description |
|---|---|---|
POST | /lens/query | Direct Query Deprecated |
Lens API
The Lens API has been deprecated and should no longer be used for new code.
| Method | Endpoint | Description |
|---|---|---|
POST | /lens/sessions/create | Create new lens session |
POST | /lens/sessions/destroy | Destroy lens session |
GET | /lens/sessions/info | Get sessions summary |
GET | /lens/sessions/metadata | Get active sessions metadata |
POST | /lens/register | Register lens |
POST | /lens/clone | Clone lens |
POST | /lens/modify | Modify lens |
POST | /lens/delete | Delete lens |
GET | /lens/info | Get lens summary info |
GET | /lens/metadata | Get detailed lens metadata |
Error Handling
This example demonstrates both how to handle errors and how to support retrying API calls when transient errors occur.import requests
import time
import random
def api_call_with_retry(func, *args, **kwargs):
max_retries = 3
for attempt in range(max_retries):
try:
response = func(*args, **kwargs)
if response.status_code == 429:
# Rate limited
retry_after = response.json().get('error', {}).get('details', {}).get('retry_after', 60)
time.sleep(retry_after)
continue
response.raise_for_status()
return response.json()
except requests.exceptions.HTTPError as e:
if e.response.status_code < 500:
# Client error - don't retry
raise e
# Server error - retry with backoff
wait_time = (2 ** attempt) + random.uniform(0, 1)
time.sleep(wait_time)
raise Exception("Max retries exceeded")
Common Error Codes
| Code | HTTP Status | Description | Solution |
|---|---|---|---|
UNAUTHORIZED | 401 | Invalid API key | Check API key format: Bearer YOUR_KEY |
INVALID_LENS_ID | 400 | Lens doesn’t exist | Get valid IDs from /lens/metadata |
SESSION_NOT_FOUND | 404 | Session destroyed/expired | Create new session |
RATE_LIMIT_EXCEEDED | 429 | Too many requests | Implement exponential backoff |
FILE_TOO_LARGE | 413 | File > 1GB | Compress or split file |
WebSocket Usage
import websocket
import json
import base64
def on_message(ws, message):
response = json.loads(message)
print(f"Newton: {response}")
def on_open(ws):
# Send image data
with open('image.jpg', 'rb') as f:
image_data = base64.b64encode(f.read()).decode()
ws.send(json.dumps({
"type": "image",
"data": image_data,
"focus": "safety equipment" # Optional
}))
# Connect to session WebSocket
ws = websocket.WebSocketApp(
session_endpoint, # From session creation response
on_message=on_message,
on_open=on_open
)
ws.run_forever()
Rate Limits
- Default: 100 requests per minute
- Burst: Up to 20 requests per second
- Sessions: 10 concurrent sessions per organization
- Files: 1GB max size, 100 files per hour
Quick Troubleshooting
1
Check API Key
curl https://platform.u1.archetypeai.app/api/lens/info \
-H "Authorization: Bearer $ATAI_API_KEY"
2
List Available Lenses
curl https://platform.u1.archetypeai.app/api/lens/metadata \
-H "Authorization: Bearer $ATAI_API_KEY" | jq '.[].lens_id'
3
Check Active Sessions
curl https://platform.u1.archetypeai.app/api/lens/sessions/info \
-H "Authorization: Bearer $ATAI_API_KEY"
4
Clean Up Sessions
# Get all sessions and destroy them
curl https://platform.u1.archetypeai.app/api/lens/sessions/metadata \
-H "Authorization: Bearer $ATAI_API_KEY" \
| jq -r '.[].session_id' \
| xargs -I {} curl -X POST https://platform.u1.archetypeai.app/api/lens/sessions/destroy \
-H "Authorization: Bearer $ATAI_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"session_id\": \"{}\"}"
Resources
Developer Console
Manage API keys and organization settings, run batch jobs, and create and manage agents
Support
Get help from our technical team