Skip to main content
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"
  }'

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

​
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

​
lens_id
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.
​
session_id
string
Unique identifier for the created session.
​
lens_id
string
The lens ID associated with this session.
​
lens_name
string
Name of the lens associated with this session.
​
org_id
string
Organization identifier the session belongs to.
​
api_key
string
The caller’s API key, echoed back for downstream WebSocket auth. Sensitive — see warning above.
​
session_endpoint
string
WebSocket URL for streaming data to/from the session.
​
session_status
string
Initial status of the session (typically LensSessionStatus.SESSION_STATUS_REGISTERED).
​
session_ttl_sec
integer
Maximum session lifetime in seconds (default 86400, i.e. 24 hours of inactivity).
​
session_runner
string
Identifier of the backend runner hosting the session.
​
lens_config
object
Resolved lens configuration in use for this session.
​
registration_timestamp
float
Unix timestamp when the session record was created.
​
last_event_timestamp
float
Unix timestamp of the last event processed by the session.
​
last_update_timestamp
float
Unix timestamp of the last update to the session record.
​
session_start_timestamp
float
Unix timestamp when the session began running. null until the runner starts.
​
session_destroyed_timestamp
float
Unix timestamp when the session was destroyed. null while active.
​
input_data_stream_id
string
Identifier of the configured input stream, or null if none is set.
​
output_data_stream_id
string
Identifier of the configured output stream, or null if none is set.
​
num_active_connections
integer
Number of active client connections to the session.
​
num_events
integer
Total number of events processed by the session.
​
num_updates
integer
Number of state updates the session has emitted.
​
num_inputs
integer
Number of input frames/records the session has received.
​
num_outputs
integer
Number of outputs the session has produced.
​
node_tag
string
Tag of the runner node the session is bound to.
​
errors
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"
  }'

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

​
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