Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt

Use this file to discover all available pages before exploring further.

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.png', 'rb') as f:
    response = requests.post(
        'https://api.u1.archetypeai.app/v0.5/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://api.u1.archetypeai.app/v0.5/files/metadata",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)

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

API Endpoints Summary

Lens API

MethodEndpointDescription
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
POST/lens/registerRegister lens
POST/lens/cloneClone lens
POST/lens/modifyModify lens
POST/lens/deleteDelete lens
GET/lens/infoGet lens summary info
GET/lens/metadataGet detailed lens metadata

Files API

MethodEndpointDescription
POST/filesUpload file
POST/files/base64Upload base64 file
DELETE/files/delete/{file_id}Delete file
GET/files/download/{file_id}Download file
GET/files/infoGet files info
GET/files/metadataList all files and their metadata
GET/files/metadata/{file_id}Get a file’s metadata
POST/files/uploads/initiateInitiate a direct-to-cloud upload
POST/files/uploads/{upload_id}/parts/urlsGenerate presigned URLs for upload parts
POST/files/uploads/{upload_id}/parts/checkpointCheckpoint completed upload parts
POST/files/uploads/{upload_id}/completeComplete a direct-to-cloud upload
POST/files/uploads/{upload_id}/abortAbort a direct-to-cloud upload

Batch Processing API

MethodEndpointDescription
Jobs
POST/batch/jobsCreate job
GET/batch/jobsList jobs
GET/batch/jobs/{id}Get job info
POST/batch/jobs/{id}/retryRetry job
DELETE/batch/jobs/{id}Delete job
POST/batch/jobs/{id}/cancelCancel job
GET/batch/jobs/queueGet global queue depths grouped by pipeline type
Events
GET/batch/jobs/{id}/eventsList job events
I/O
GET/batch/jobs/{id}/inputsList job inputs
GET/batch/jobs/{id}/outputsList job outputs
Progress
GET/batch/jobs/{id}/progressList job progress
Registry: Pipelines
GET/batch/registry/pipelinesList pipelines
GET/batch/registry/pipelines/{id}Get pipeline info
GET/batch/registry/pipelines/{id}/schemaGet pipeline schema

Fine-Tuning Node

MethodEndpointDescription
POST/fine-tune/jobsCreate fine-tuning job
GET/fine-tune/jobsList fine-tuning jobs
GET/fine-tune/jobs/{job_id}Get fine-tuning job info
GET/fine-tune/jobs/{job_id}/metricsGet fine-tuning job metrics
PUT/fine-tune/jobs/{job_id}/stopStop running fine-tuning job
DELETE/fine-tune/jobs/{job_id}Delete fine-tuning job
PUT/fine-tune/jobs/{job_id}/cancelCancel fine-tuning job
GET/fine-tune/statusGet node status

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

Live Monitor

View real-time API usage and active sessions

Newton Console

Manage API keys and organization settings

System Status

Check API health and service status

Support

Get help from our technical team