curl -X POST https://platform.u1.archetypeai.app/api/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://platform.u1.archetypeai.app/api/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://platform.u1.archetypeai.app/api/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://platform.u1.archetypeai.app/api/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"
}
]
}
Lens API
Create Lens Session
Create a new lens session for processing sensor data
POST
/
lens
/
sessions
/
create
curl -X POST https://platform.u1.archetypeai.app/api/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://platform.u1.archetypeai.app/api/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://platform.u1.archetypeai.app/api/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://platform.u1.archetypeai.app/api/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
The ID of the lens to use for this session. Get available lens IDs from
/lens/metadataResponse
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.The caller’s API key, echoed back for downstream WebSocket auth. Sensitive — see warning above.
curl -X POST https://platform.u1.archetypeai.app/api/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://platform.u1.archetypeai.app/api/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://platform.u1.archetypeai.app/api/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://platform.u1.archetypeai.app/api/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
Was this page helpful?