Skip to main content

Authentication

# Set your API key
export ATAI_API_KEY="your-api-key-here"

# Basic API call
curl https://api.u1.archetypeai.app/v0.5/lens/info \
  -H "Authorization: Bearer $ATAI_API_KEY"

Common Patterns

Create and Use a Session

import requests

# 1. Create session
response = requests.post(
    "https://api.u1.archetypeai.app/v0.5/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://api.u1.archetypeai.app/v0.5/lens/sessions/destroy",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"session_id": session['session_id']}
)

Upload and Process Files

import requests

# Upload file
with open('image.jpg', 'rb') as f:
    response = requests.post(
        'https://api.u1.archetypeai.app/v0.5/files/upload',
        headers={'Authorization': 'Bearer YOUR_API_KEY'},
        files={'file': f},
        data={'description': 'Test image'}
    )

file_data = response.json()
print(f"Uploaded: {file_data['file_id']}")

# List files
response = requests.get(
    "https://api.u1.archetypeai.app/v0.5/files/list",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

files = response.json()['files']
for file in files:
    print(f"- {file['filename']} ({file['size_bytes']} bytes)")

API Endpoints Summary

Lens API

MethodEndpointDescription
GET/lens/infoGet lens summary info
GET/lens/metadataGet detailed lens metadata
POST/lens/sessions/createCreate new lens session
POST/lens/sessions/destroyDestroy lens session
GET/lens/sessions/infoGet sessions summary
GET/lens/sessions/metadataGet active sessions metadata

Files API

MethodEndpointDescription
POST/files/uploadUpload file
GET/files/listList all files
GET/files/{file_id}/metadataGet file metadata

Error Handling

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

CodeHTTP StatusDescriptionSolution
UNAUTHORIZED401Invalid API keyCheck API key format: Bearer YOUR_KEY
INVALID_LENS_ID400Lens doesn’t existGet valid IDs from /lens/metadata
SESSION_NOT_FOUND404Session destroyed/expiredCreate new session
RATE_LIMIT_EXCEEDED429Too many requestsImplement exponential backoff
FILE_TOO_LARGE413File > 1GBCompress 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://api.u1.archetypeai.app/v0.5/lens/info \
  -H "Authorization: Bearer $ATAI_API_KEY"
2

List Available Lenses

curl https://api.u1.archetypeai.app/v0.5/lens/metadata \
  -H "Authorization: Bearer $ATAI_API_KEY" | jq '.[].lens_id'
3

Check Active Sessions

curl https://api.u1.archetypeai.app/v0.5/lens/sessions/info \
  -H "Authorization: Bearer $ATAI_API_KEY"
4

Clean Up Sessions

# Get all sessions and destroy them
curl https://api.u1.archetypeai.app/v0.5/lens/sessions/metadata \
  -H "Authorization: Bearer $ATAI_API_KEY" \
  | jq -r '.[].session_id' \
  | xargs -I {} curl -X POST https://api.u1.archetypeai.app/v0.5/lens/sessions/destroy \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"session_id\": \"{}\"}"

Resources