POST /api/agent/v1/session/create/

Call this endpoint at the start of every agent task or run. The session JWT you receive scopes all events, traces, and logs produced during that task back to a single identifiable session. Pass the returned token in the X-OTAS-AGENT-SESSION-TOKEN header on every subsequent OTAS call made within that run.

Authentication for this endpoint uses the agent’s API key (X-OTAS-AGENT-KEY), not a user token. The key must be active and unexpired.

Endpoint

POST /api/agent/v1/session/create/

Base URL: http://localhost:8000

Request headers

string

required

The agent’s API key in the format agent_<prefix>_<secret>. Obtained when creating the agent or rotating its key.

Request body

object

Optional JSON object with task context. Use it to attach structured metadata to the session for filtering and debugging, e.g. { "task": "summarize", "input_length": 512 }. Defaults to {}.

Response

number

1 on success.

string

"agent_session_created" on success.

object

Hide properties

string

The name of the header in which to pass the session JWT on subsequent calls: "X-OTAS-AGENT-SESSION-TOKEN".

string

Signed HS256 JWT. Valid for 30 days from issuance. The JWT payload contains:

agent_session_id — UUID of the newly created session
agent_id — UUID of the authenticating agent
iat — issued-at timestamp
exp — expiry timestamp (30 days after iat)

Create a new session for every distinct task or process. Never reuse a session JWT across separate, independent runs — doing so conflates their events under a single session, making attribution and debugging unreliable.

Do not share a session JWT between parallel agent instances. Each concurrent run must start its own session so that events are attributed correctly.

Example

cURL

curl --request POST \
  --url http://localhost:8000/api/agent/v1/session/create/ \
  --header "X-OTAS-AGENT-KEY: agent_xYz1Ab2C_s3cr3tT0k3nV4lueG0esH3re..." \
  --header "Content-Type: application/json" \
  --data '{
    "meta": {
      "task": "summarize",
      "input_length": 512
    }
  }'

Response (200)

{
  "status": 1,
  "status_description": "agent_session_created",
  "response": {
    "Header_value": "X-OTAS-AGENT-SESSION-TOKEN",
    "jwt_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

After receiving the token, attach it to all subsequent OTAS calls for this run:

Subsequent call example

curl --request POST \
  --url http://localhost:8000/api/some/v1/endpoint/ \
  --header "X-OTAS-AGENT-SESSION-TOKEN: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --header "Content-Type: application/json" \
  --data '{}'

UASAM — Users & Auth

UASAM — Projects & Keys

UASAM — Agents

Brain — Event Capture

Brain — Analytics

POST /api/agent/v1/session/create/

Endpoint

Request headers

Request body

Response

Example

​Endpoint

​Request headers

​Request body

​Response

​Example

Endpoint

Request headers

Request body

Response

Example