Skip to main content
A session in OTAS scopes all observed events to a single agent run or task. Every event your agent generates — whether captured automatically by the server-side middleware or posted manually to Brain — is tied to a session ID. This makes it possible to replay a complete execution, filter analytics by run, and understand exactly what your agent did during a specific task. Sessions are lightweight: creating one is a single HTTP call, and the returned JWT is all you need to authenticate subsequent requests.

​
When to create a session

Create a new session at the very beginning of every new process, task, or agent run. The key constraint is isolation: a session represents one continuous execution, so you must never reuse a session token across separate processes. If your agent crashes and restarts, create a new session. If it handles a new user request, create a new session.
Reusing a session token across separate processes will mix events from different runs into a single session, making it impossible to accurately trace or replay either execution.

​
Creating a session

Send a POST request to the UASAM session endpoint with your agent key in the header. The request body is optional but you should always include a meta object — even an empty one — to leave room for task context. Endpoint: POST http://localhost:8000/api/agent/v1/session/create/ Headers:
HeaderValue
X-OTAS-AGENT-KEYYour agent key (agent_<prefix>_<secret>)
Content-Typeapplication/json
Request body: 
{
  "meta": {}
}
The meta field accepts arbitrary JSON. Use it to record whatever context is meaningful for the task — for example: 
{
  "meta": {
    "task_name": "summarize_documents",
    "user_id": "u_8821",
    "input_count": 5,
    "trace_id": "trace-abc-xyz"
  }
}
Example request: 
curl -X POST http://localhost:8000/api/agent/v1/session/create/ \
  -H "X-OTAS-AGENT-KEY: agent_abc123_yoursecrethere" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": {
      "task_name": "summarize_documents",
      "user_id": "u_8821"
    }
  }'
Successful response: 
{
  "status": 1,
  "status_description": "agent_session_created",
  "response": {
    "Header_value": "X-OTAS-AGENT-SESSION-TOKEN",
    "jwt_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

​
Using the session JWT

Store the jwt_token value from the response and pass it as the X-OTAS-AGENT-SESSION-TOKEN header on every subsequent request for this session — both in-domain requests and out-of-domain log calls. 
# In-domain request
curl -X GET https://your-project-domain.example.com/api/v1/resource \
  -H "X-OTAS-AGENT-SESSION-TOKEN: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Out-of-domain log
curl -X POST http://localhost:8002/api/v1/backend/log/agent/ \
  -H "X-OTAS-AGENT-KEY: agent_abc123_yoursecrethere" \
  -H "X-OTAS-AGENT-SESSION-TOKEN: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{ ... }'
The JWT encodes the agent_session_id and agent_id. Brain validates this token on every event capture request, so there is no separate session activation step.

​
Session expiry

Session JWTs are valid for 30 days from the time of creation. After expiry, requests using the token will be rejected with a 401 invalid_or_expired_token response. If your agent is long-running (spanning multiple days), you should create a new session before the old one expires or at each logical task boundary.

​
Listing sessions

You can retrieve all sessions for a given agent using the list endpoint. This is useful for auditing, debugging, or fetching a session ID to query its events in Brain. Endpoint: GET http://localhost:8000/api/agent/v1/sessions/list/?agent_id=<uuid> Required headers: X-OTAS-USER-TOKEN, X-OTAS-PROJECT-ID Sessions are returned ordered by created_at descending (most recent first). Each session entry includes the session id, the agent_key_id used to create it, the created_at timestamp, and the meta object you provided at creation time.

​
Querying session events in Brain

Once you have a session ID, you can fetch all events captured during that session: Endpoint: GET http://localhost:8002/api/v1/agent/session/events/?session_id=<uuid> Required headers: X-OTAS-USER-TOKEN, X-OTAS-AGENT-ID, X-OTAS-PROJECT-ID Results are ordered by event_time ascending and are capped at 200 events by default (maximum 500 via the limit query parameter). This endpoint is the primary way to replay or inspect what your agent did during a specific run.

Build docs developers (and LLMs) love

Get started for freeTalk to us