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

# Quick Reference

> Essential API commands and patterns for quick reference.

## Authentication

```bash theme={"system"}
# 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

<CodeGroup>
  ```python Python theme={"system"}
  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']}
  )
  ```

  ```bash cURL theme={"system"}
  # 1. Create session
  SESSION_ID=$(curl -s https://api.u1.archetypeai.app/v0.5/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://api.u1.archetypeai.app/v0.5/lens/sessions/destroy \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"session_id\": \"$SESSION_ID\"}"
  ```
</CodeGroup>

### Upload and Process Files

<CodeGroup>
  ```python Python theme={"system"}
  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)")
  ```

  ```bash cURL theme={"system"}
  # Upload file
  curl -X POST https://api.u1.archetypeai.app/v0.5/files \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -F "file=@image.jpg"

  # List files
  curl https://api.u1.archetypeai.app/v0.5/files/metadata \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```
</CodeGroup>

## API Endpoints Summary

### Lens API

| Method | Endpoint                  | Description                                                               |
| ------ | ------------------------- | ------------------------------------------------------------------------- |
| `POST` | `/lens/sessions/create`   | [Create new lens session](/api-reference/lens/create-session)             |
| `POST` | `/lens/sessions/destroy`  | [Destroy lens session](/api-reference/lens/destroy-session)               |
| `GET`  | `/lens/sessions/info`     | [Get sessions summary](/api-reference/lens/get-sessions-info)             |
| `GET`  | `/lens/sessions/metadata` | [Get active sessions metadata](/api-reference/lens/get-sessions-metadata) |
| `POST` | `/lens/register`          | [Register lens](/api-reference/lens/lens-register)                        |
| `POST` | `/lens/clone`             | [Clone lens](/api-reference/lens/lens-clone)                              |
| `POST` | `/lens/modify`            | [Modify lens](/api-reference/lens/lens-modify)                            |
| `POST` | `/lens/delete`            | [Delete lens](/api-reference/lens/lens-delete)                            |
| `GET`  | `/lens/info`              | [Get lens summary info](/api-reference/lens/get-info)                     |
| `GET`  | `/lens/metadata`          | [Get detailed lens metadata](/api-reference/lens/get-metadata)            |

### Files API

| Method   | Endpoint                                      | Description                                                                         |
| -------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
| `POST`   | `/files`                                      | [Upload file](/api-reference/files/upload)                                          |
| `POST`   | `/files/base64`                               | [Upload base64 file](/api-reference/files/upload-base64)                            |
| `DELETE` | `/files/delete/{file_id}`                     | [Delete file](/api-reference/files/delete-file)                                     |
| `GET`    | `/files/download/{file_id}`                   | [Download file](/api-reference/files/download-file)                                 |
| `GET`    | `/files/info`                                 | [Get files info](/api-reference/files/get-info)                                     |
| `GET`    | `/files/metadata`                             | [List all files and their metadata](/api-reference/files/get-all-metadata)          |
| `GET`    | `/files/metadata/{file_id}`                   | [Get a file's metadata](/api-reference/files/get-metadata)                          |
| `POST`   | `/files/uploads/initiate`                     | [Initiate a direct-to-cloud upload](/api-reference/files/initiate-upload)           |
| `POST`   | `/files/uploads/{upload_id}/parts/urls`       | [Generate presigned URLs for upload parts](/api-reference/files/generate-part-urls) |
| `POST`   | `/files/uploads/{upload_id}/parts/checkpoint` | [Checkpoint completed upload parts](/api-reference/files/checkpoint-parts)          |
| `POST`   | `/files/uploads/{upload_id}/complete`         | [Complete a direct-to-cloud upload](/api-reference/files/complete-upload)           |
| `POST`   | `/files/uploads/{upload_id}/abort`            | [Abort a direct-to-cloud upload](/api-reference/files/abort-upload)                 |

### Batch Processing API

| Method                  | Endpoint                                | Description                                                                                    |
| ----------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Jobs**                |                                         |                                                                                                |
| `POST`                  | `/batch/jobs`                           | [Create job](/api-reference/batch/jobs/create-job)                                             |
| `GET`                   | `/batch/jobs`                           | [List jobs](/api-reference/batch/jobs/list-jobs)                                               |
| `GET`                   | `/batch/jobs/{id}`                      | [Get job info](/api-reference/batch/jobs/get-job)                                              |
| `POST`                  | `/batch/jobs/{id}/retry`                | [Retry job](/api-reference/batch/jobs/retry-job)                                               |
| `DELETE`                | `/batch/jobs/{id}`                      | [Delete job](/api-reference/batch/jobs/delete-job)                                             |
| `POST`                  | `/batch/jobs/{id}/cancel`               | [Cancel job](/api-reference/batch/jobs/cancel-job)                                             |
| `GET`                   | `/batch/jobs/queue`                     | [Get global queue depths grouped by pipeline type](/api-reference/batch/jobs/get-queue-depths) |
| **Events**              |                                         |                                                                                                |
| `GET`                   | `/batch/jobs/{id}/events`               | [List job events](/api-reference/batch/events/list-job-events)                                 |
| **I/O**                 |                                         |                                                                                                |
| `GET`                   | `/batch/jobs/{id}/inputs`               | [List job inputs](/api-reference/batch/io/list-inputs)                                         |
| `GET`                   | `/batch/jobs/{id}/outputs`              | [List job outputs](/api-reference/batch/io/list-outputs)                                       |
| **Progress**            |                                         |                                                                                                |
| `GET`                   | `/batch/jobs/{id}/progress`             | [List job progress](/api-reference/batch/progress/list-job-progress)                           |
| **Registry: Pipelines** |                                         |                                                                                                |
| `GET`                   | `/batch/registry/pipelines`             | [List pipelines](/api-reference/batch/registry/pipelines/list-pipelines)                       |
| `GET`                   | `/batch/registry/pipelines/{id}`        | [Get pipeline info](/api-reference/batch/registry/pipelines/get-pipeline)                      |
| `GET`                   | `/batch/registry/pipelines/{id}/schema` | [Get pipeline schema](/api-reference/batch/registry/pipelines/get-pipeline-schema)             |

### Fine-Tuning Service

| Method | Endpoint                               | Description                                                                                                                |
| ------ | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `POST` | `/fine-tuning/create-job`              | [Create a fine-tuning job](/api-reference/fine-tuning/create-job)                                                          |
| `GET`  | `/fine-tuning/get-job`                 | [Get information about a fine-tuning job](/api-reference/fine-tuning/get-job)                                              |
| `GET`  | `/fine-tuning/list-jobs`               | [List fine-tuning jobs](/api-reference/fine-tuning/list-jobs)                                                              |
| `POST` | `/fine-tuning/pause-job`               | [Pause a fine-tuning job](/api-reference/fine-tuning/pause-job)                                                            |
| `POST` | `/fine-tuning/resume-job`              | [Resume a fine-tuning job](/api-reference/fine-tuning/resume-job)                                                          |
| `POST` | `/fine-tuning/cancel-job`              | [Cancel a fine-tuning job](/api-reference/fine-tuning/cancel-job)                                                          |
| `GET`  | `/fine-tuning/list-job-checkpoints`    | [List the checkpoints saved for a given fine-tuning job](/api-reference/fine-tuning/list-job-checkpoints)                  |
| `GET`  | `/fine-tuning/list-job-events`         | [List the job events for a given fine-tuning job](/api-reference/fine-tuning/list-job-events)                              |
| `GET`  | `/fine-tuning/list-job-logs`           | [List the events for a given fine-tuning job](/api-reference/fine-tuning/list-job-logs)                                    |
| `GET`  | `/fine-tuning/list-job-metrics`        | [List a fine-tuning job's metrics](/api-reference/fine-tuning/list-job-metrics)                                            |
| `GET`  | `/fine-tuning/list-checkpoint-options` | [List the checkpoints saved for jobs that match the specified filters](/api-reference/fine-tuning/list-checkpoint-options) |

## Error Handling

```python theme={"system"}
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

```python theme={"system"}
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

<Steps>
  <Step title="Check API Key">
    ```bash theme={"system"}
    curl https://api.u1.archetypeai.app/v0.5/lens/info \
      -H "Authorization: Bearer $ATAI_API_KEY"
    ```
  </Step>

  <Step title="List Available Lenses">
    ```bash theme={"system"}
    curl https://api.u1.archetypeai.app/v0.5/lens/metadata \
      -H "Authorization: Bearer $ATAI_API_KEY" | jq '.[].lens_id'
    ```
  </Step>

  <Step title="Check Active Sessions">
    ```bash theme={"system"}
    curl https://api.u1.archetypeai.app/v0.5/lens/sessions/info \
      -H "Authorization: Bearer $ATAI_API_KEY"
    ```
  </Step>

  <Step title="Clean Up Sessions">
    ```bash theme={"system"}
    # 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\": \"{}\"}"
    ```
  </Step>
</Steps>

## Resources

<CardGroup cols={2}>
  <Card title="Live Monitor" href="https://console.u1.archetypeai.app/monitor">
    View real-time API usage and active sessions
  </Card>

  <Card title="Newton Console" href="https://console.u1.archetypeai.app">
    Manage API keys and organization settings
  </Card>

  <Card title="System Status" href="https://status.archetypeai.dev">
    Check API health and service status
  </Card>

  <Card title="Support" href="mailto:support@archetypeai.dev">
    Get help from our technical team
  </Card>
</CardGroup>