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

# Register Lens

> Register a new lens configuration that can be used to create sessions

## Overview

Register a new lens by providing a configuration. The lens can be a minimal registration (just a name) or a full production lens with model pipeline and parameters.

## Request Body

<ParamField body="lens_config" type="object" required>
  Configuration object for the lens

  <Expandable title="properties">
    <ParamField body="lens_name" type="string" required>
      Name for the lens
    </ParamField>

    <ParamField body="model_pipeline" type="array">
      Array of processor configurations for the lens
    </ParamField>

    <ParamField body="model_parameters" type="object">
      Parameters for the model configuration
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="lens_id" type="string">
  Unique identifier for the registered lens (format: "lns-...")
</ResponseField>

<ResponseField name="lens_name" type="string">
  Name of the registered lens
</ResponseField>

<ResponseField name="lens_modifiable" type="boolean">
  Whether the lens can be modified or deleted
</ResponseField>

<ResponseField name="lens_status" type="string">
  Current status of the lens ("LENS\_STATUS\_MOUNTED" or "LENS\_STATUS\_REGISTERED")
</ResponseField>

<ResponseField name="is_valid" type="boolean">
  If `false`, indicates an error occurred. Check `error_messages` for details.
</ResponseField>

<ResponseField name="error_messages" type="array">
  Array of error messages if registration failed
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl -X POST https://api.u1.archetypeai.app/v0.5/lens/register \
    -H "Authorization: Bearer $ATAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "lens_config": {
        "lens_name": "My Test Lens"
      }
    }'
  ```

  ```python Python theme={"system"}
  import requests
  import os

  api_key = os.environ.get("ATAI_API_KEY")

  response = requests.post(
      "https://api.u1.archetypeai.app/v0.5/lens/register",
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json"
      },
      json={
          "lens_config": {
              "lens_name": "My Test Lens"
          }
      }
  )

  data = response.json()

  if data.get("is_valid") == False:
      print(f"Error: {data.get('error_messages')}")
  else:
      print(f"Lens ID: {data['lens_id']}")
  ```

  ```javascript JavaScript theme={"system"}
  const response = await fetch(
    "https://api.u1.archetypeai.app/v0.5/lens/register",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.ATAI_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        lens_config: {
          lens_name: "My Test Lens",
        },
      }),
    }
  );

  const data = await response.json();

  if (data.is_valid === false) {
    console.error("Error:", data.error_messages);
  } else {
    console.log(`Lens ID: ${data.lens_id}`);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - OK theme={"system"}
  {
    "lens_id": "lns-test-lens-176520-e7885b3f",
    "lens_name": "My Test Lens",
    "lens_status": "LENS_STATUS_MOUNTED",
    "lens_modifiable": true,
    "lens_config": {
      "model_pipeline": [
        {
          "processor_name": "lens_noop_processor",
          "processor_config": {}
        }
      ]
    }
  }
  ```

  ```json 422 - Invalid JSON payload theme={"system"}
  {
    "errors": [
      {
        "code": "invalid_json_payload",
        "message": "Invalid JSON payload.",
        "suggestion": "Ensure the request body contains valid JSON and is properly formatted.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 422 - Missing required field: lens_name theme={"system"}
  {
    "errors": [
      {
        "code": "missing_lens_name",
        "message": "Missing required field: lens_name.",
        "suggestion": "Include the 'lens_name' field in the request payload.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```

  ```json 401 - Unauthorized theme={"system"}
  {
    "errors": [
      {
        "code": "unauthorized_request",
        "message": "Unauthorized or invalid access.",
        "suggestion": "Provide valid authentication credentials and ensure they have the required permissions.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>