Skip to main content

​
Overview

Manage the session lifecycle of a persona. Status labels are freely defined by each tenant, and every transition is recorded with a timestamp. 
Enter → CHAT → SHOPPING → PAYMENT → COMPLETE → Exit
 ↑       ↑        ↑          ↑         ↑        ↑
 t1      t2       t3         t4        t5       t6

​
Start Session

POST /v1/persona/{persona_id}/session/start

​
Response

{
  "success": true,
  "data": {
    "session_id": "a1b2c3d4-...",
    "persona_id": "d28fd898-...",
    "started_at": "2026-04-17T10:00:00Z"
  }
}
Only one active session is allowed per persona. If an active session already exists, 409 SESSION_ACTIVE is returned.

​
Record Status Stamp

POST /v1/persona/{persona_id}/session/stamp

​
Request

{
  "status": "SHOPPING",
  "meta": {
    "zone": "processed_food",
    "cart_items": 3
  }
}
FieldTypeRequiredDescription
statusstringYesStatus label (freely defined by tenant)
metaobjectNoAdditional data related to the status

​
Response

{
  "success": true,
  "data": {
    "session_id": "a1b2c3d4-...",
    "status": "SHOPPING",
    "timestamp": "2026-04-17T10:05:00Z"
  }
}

​
End Session

POST /v1/persona/{persona_id}/session/end
Ends the session and returns the full stamp history.

​
Response

{
  "success": true,
  "data": {
    "session_id": "a1b2c3d4-...",
    "persona_id": "d28fd898-...",
    "started_at": "2026-04-17T10:00:00Z",
    "ended_at": "2026-04-17T11:30:00Z",
    "stamps": [
      { "status": "ENTER", "timestamp": "2026-04-17T10:00:00Z" },
      { "status": "CHAT", "timestamp": "2026-04-17T10:02:00Z" },
      { "status": "SHOPPING", "timestamp": "2026-04-17T10:15:00Z" },
      { "status": "PAYMENT", "timestamp": "2026-04-17T11:20:00Z" },
      { "status": "COMPLETE", "timestamp": "2026-04-17T11:25:00Z" }
    ]
  }
}

​
Get Current Session

GET /v1/persona/{persona_id}/session
Returns the active session with stamps recorded so far.

​
Code Examples

# Start session
curl -X POST https://api.ones1ght.com/v1/persona/$PERSONA_ID/session/start \
  -H "Authorization: Bearer $SDK_KEY"

# Record stamp
curl -X POST https://api.ones1ght.com/v1/persona/$PERSONA_ID/session/stamp \
  -H "Authorization: Bearer $SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "SHOPPING", "meta": {"zone": "wine"}}'

# Get current session
curl https://api.ones1ght.com/v1/persona/$PERSONA_ID/session \
  -H "Authorization: Bearer $SDK_KEY"

# End session
curl -X POST https://api.ones1ght.com/v1/persona/$PERSONA_ID/session/end \
  -H "Authorization: Bearer $SDK_KEY"