Create Lens Session - Archetype AI Documentation

curl -X POST 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"
  }'

import requests
import os

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

response = requests.post(
    "https://api.u1.archetypeai.app/v0.5/lens/sessions/create",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "lens_id": "lns-fd669361822b07e2-237ab3ffd79199b0"
    }
)

data = response.json()

if "errors" in data:
    print(f"Error: {data['errors']}")
else:
    print(f"Session created: {data['session_id']}")
    print(f"WebSocket endpoint: {data['session_endpoint']}")

const response = await fetch('https://api.u1.archetypeai.app/v0.5/lens/sessions/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    lens_id: 'lns-fd669361822b07e2-237ab3ffd79199b0'
  })
});

const data = await response.json();

if (data.errors) {
  console.error('Error:', data.errors);
} else {
  console.log(`Session created: ${data.session_id}`);
}

{
  "org_id": "your-org",
  "api_key": "<echoed-api-key>",
  "session_id": "lsn-251207a89f948ed4e30d8f80aaba77",
  "lens_id": "lns-test-lens-b2ba0058",
  "lens_name": "Test Lens",
  "input_data_stream_id": null,
  "output_data_stream_id": null,
  "registration_timestamp": 1779428775.5983343,
  "last_event_timestamp": 1779428775.5983343,
  "last_update_timestamp": 1779428775.5983343,
  "session_start_timestamp": null,
  "session_destroyed_timestamp": null,
  "num_active_connections": 0,
  "num_updates": 0,
  "num_inputs": 0,
  "num_outputs": 0,
  "num_events": 0,
  "lens_config": {
    "model_pipeline": [
      {"processor_name": "lens_noop_processor", "processor_config": {}}
    ]
  },
  "session_status": "LensSessionStatus.SESSION_STATUS_REGISTERED",
  "session_runner": "lens_service:runner:lens-node-worker-node-abc123",
  "session_endpoint": "wss://api.u1.archetypeai.app/v0.5/lens/sessions/lsn-251207a89f948ed4e30d8f80aaba77",
  "node_tag": "default",
  "session_ttl_sec": 86400
}

{
  "errors": [
    "Invalid lens_id: None"
  ]
}

{
  "errors": [
    "Invalid lens config"
  ]
}

{
  "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"
    }
  ]
}

POST

lens

sessions

create

curl -X POST 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"
  }'

import requests
import os

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

response = requests.post(
    "https://api.u1.archetypeai.app/v0.5/lens/sessions/create",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "lens_id": "lns-fd669361822b07e2-237ab3ffd79199b0"
    }
)

data = response.json()

if "errors" in data:
    print(f"Error: {data['errors']}")
else:
    print(f"Session created: {data['session_id']}")
    print(f"WebSocket endpoint: {data['session_endpoint']}")

const response = await fetch('https://api.u1.archetypeai.app/v0.5/lens/sessions/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    lens_id: 'lns-fd669361822b07e2-237ab3ffd79199b0'
  })
});

const data = await response.json();

if (data.errors) {
  console.error('Error:', data.errors);
} else {
  console.log(`Session created: ${data.session_id}`);
}

{
  "org_id": "your-org",
  "api_key": "<echoed-api-key>",
  "session_id": "lsn-251207a89f948ed4e30d8f80aaba77",
  "lens_id": "lns-test-lens-b2ba0058",
  "lens_name": "Test Lens",
  "input_data_stream_id": null,
  "output_data_stream_id": null,
  "registration_timestamp": 1779428775.5983343,
  "last_event_timestamp": 1779428775.5983343,
  "last_update_timestamp": 1779428775.5983343,
  "session_start_timestamp": null,
  "session_destroyed_timestamp": null,
  "num_active_connections": 0,
  "num_updates": 0,
  "num_inputs": 0,
  "num_outputs": 0,
  "num_events": 0,
  "lens_config": {
    "model_pipeline": [
      {"processor_name": "lens_noop_processor", "processor_config": {}}
    ]
  },
  "session_status": "LensSessionStatus.SESSION_STATUS_REGISTERED",
  "session_runner": "lens_service:runner:lens-node-worker-node-abc123",
  "session_endpoint": "wss://api.u1.archetypeai.app/v0.5/lens/sessions/lsn-251207a89f948ed4e30d8f80aaba77",
  "node_tag": "default",
  "session_ttl_sec": 86400
}

{
  "errors": [
    "Invalid lens_id: None"
  ]
}

{
  "errors": [
    "Invalid lens config"
  ]
}

{
  "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"
    }
  ]
}

Requires version 1.1.5 or later of the Archetype platform.

Overview

This endpoint creates and allocates a new lens session that can process sensor data streams. Each session is associated with a specific lens and returns a unique session ID and endpoint for real-time data streaming.

Request

string

required

The ID of the lens to use for this session. Get available lens IDs from /lens/metadata

Response

The response contains an api_key field that echoes back the caller’s real API key. Treat this field as a secret — do not log, persist, or expose it in client-side code.

string

Unique identifier for the created session.

string

The lens ID associated with this session.

string

Name of the lens associated with this session.

string

Organization identifier the session belongs to.

string

The caller’s API key, echoed back for downstream WebSocket auth. Sensitive — see warning above.

string

WebSocket URL for streaming data to/from the session.

string

Initial status of the session (typically LensSessionStatus.SESSION_STATUS_REGISTERED).

integer

Maximum session lifetime in seconds (default 86400, i.e. 24 hours of inactivity).

string

Identifier of the backend runner hosting the session.

object

Resolved lens configuration in use for this session.

float

Unix timestamp when the session record was created.

float

Unix timestamp of the last event processed by the session.

float

Unix timestamp of the last update to the session record.

float

Unix timestamp when the session began running. null until the runner starts.

float

Unix timestamp when the session was destroyed. null while active.

string

Identifier of the configured input stream, or null if none is set.

string

Identifier of the configured output stream, or null if none is set.

integer

Number of active client connections to the session.

integer

Total number of events processed by the session.

integer

Number of state updates the session has emitted.

integer

Number of input frames/records the session has received.

integer

Number of outputs the session has produced.

string

Tag of the runner node the session is bound to.

array

Array of error messages if the request failed (check for this field to detect errors).

curl -X POST 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"
  }'

import requests
import os

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

response = requests.post(
    "https://api.u1.archetypeai.app/v0.5/lens/sessions/create",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "lens_id": "lns-fd669361822b07e2-237ab3ffd79199b0"
    }
)

data = response.json()

if "errors" in data:
    print(f"Error: {data['errors']}")
else:
    print(f"Session created: {data['session_id']}")
    print(f"WebSocket endpoint: {data['session_endpoint']}")

const response = await fetch('https://api.u1.archetypeai.app/v0.5/lens/sessions/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    lens_id: 'lns-fd669361822b07e2-237ab3ffd79199b0'
  })
});

const data = await response.json();

if (data.errors) {
  console.error('Error:', data.errors);
} else {
  console.log(`Session created: ${data.session_id}`);
}

{
  "org_id": "your-org",
  "api_key": "<echoed-api-key>",
  "session_id": "lsn-251207a89f948ed4e30d8f80aaba77",
  "lens_id": "lns-test-lens-b2ba0058",
  "lens_name": "Test Lens",
  "input_data_stream_id": null,
  "output_data_stream_id": null,
  "registration_timestamp": 1779428775.5983343,
  "last_event_timestamp": 1779428775.5983343,
  "last_update_timestamp": 1779428775.5983343,
  "session_start_timestamp": null,
  "session_destroyed_timestamp": null,
  "num_active_connections": 0,
  "num_updates": 0,
  "num_inputs": 0,
  "num_outputs": 0,
  "num_events": 0,
  "lens_config": {
    "model_pipeline": [
      {"processor_name": "lens_noop_processor", "processor_config": {}}
    ]
  },
  "session_status": "LensSessionStatus.SESSION_STATUS_REGISTERED",
  "session_runner": "lens_service:runner:lens-node-worker-node-abc123",
  "session_endpoint": "wss://api.u1.archetypeai.app/v0.5/lens/sessions/lsn-251207a89f948ed4e30d8f80aaba77",
  "node_tag": "default",
  "session_ttl_sec": 86400
}

{
  "errors": [
    "Invalid lens_id: None"
  ]
}

{
  "errors": [
    "Invalid lens config"
  ]
}

{
  "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"
    }
  ]
}

Important Notes

Sessions remain active until explicitly destroyed or timeout after no sensor activity
Always destroy sessions when done to free up resources
Check which sessions are running via /lens/sessions/metadata

⌘I

​Overview

​Request

​Response

​Important Notes

Overview

Request

Response

Important Notes