Skip to main content

​
Overview

Manages the session lifecycle of a profile. Each tenant defines a session flow (ordered list of stages) in the admin panel. READY and CHAT are reserved keywords and always occupy the first two positions of the flow. The flow is linear and one-way — once a stage transitions forward, you cannot go back. As soon as the session moves from CHAT to any other stage, the active thread is closed automatically. 
enter → READY → CHAT → SHOPPING → PAYMENT → COMPLETE → end
                  ↑         ↑
             chat allowed   chat blocked (CHAT_ENDED)

​
Chat Allowance Rules

Last stampPOST /v1/chat/{profile_id} behavior
No active session409 NO_ACTIVE_SESSION
READYCreate new thread + auto-push CHAT stamp
CHATContinue on the existing active thread
Any custom stage409 CHAT_ENDED — must end and restart the session

​
Start Session

POST /v1/profile/{profile_id}/session/start

​
Response

{
  "success": true,
  "data": {
    "session_id": "a1b2c3d4-...",
    "profile_id": "d28fd898-...",
    "started_at": "2026-04-20T10:00:00Z"
  }
}
Only one active session is allowed per profile. If one already exists, the API returns 409 SESSION_ACTIVE.

​
Add Status Stamp

POST /v1/profile/{profile_id}/session/stamp

​
Request

{
  "status": "SHOPPING",
  "meta": {
    "zone": "processed_food",
    "cart_items": 3
  }
}
FieldTypeRequiredDescription
statusstringYesOne of the stages registered in the tenant flow
metaobjectNoArbitrary metadata for the stage

​
Response

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

​
Transition Errors

CodeDescription
INVALID_STAGEStage is not registered in the tenant flow
STAGE_REGRESSIONAttempting to move back to an earlier stage (not allowed)
When the session transitions from CHAT to any other stage, the currently active thread is closed automatically.

​
End Session

POST /v1/profile/{profile_id}/session/end
Ends the session and returns the full stamp history. Any active thread is closed as well.

​
Response

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

​
Get Current Session

GET /v1/profile/{profile_id}/session
Returns the active session, current stage, and active thread ID. After an abnormal app termination, use current_stage to restore the client screen on resume.

​
Response

{
  "success": true,
  "data": {
    "session_id": "a1b2c3d4-...",
    "profile_id": "d28fd898-...",
    "is_active": true,
    "started_at": "2026-04-20T10:00:00Z",
    "current_stage": "CHAT",
    "current_thread_id": "thr_a1b2c3d4e5f6",
    "stamps": [
      { "status": "READY", "timestamp": "2026-04-20T10:00:00Z" },
      { "status": "CHAT",  "timestamp": "2026-04-20T10:02:00Z" }
    ],
    "query_results": {
      "session": { "status": "CHAT", "back_list_status": "not_started", "last_error": null }
    }
  }
}
FieldDescription
current_stageThe most recent stamp (use this to decide which screen to show on resume)
current_thread_idActive thread ID when current_stage == "CHAT", otherwise null
query_results.sessionPresent only once POST /v1/chat/{profile_id} has been called. Compact llm-demo snapshot (status / back_list_status / last_error) for restore-time branching; the full pipeline still comes from GET /v1/chat/{profile_id}/recommend/{session_id} polling

​
Code Examples

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

# Advance to the next stage after CHAT
curl -X POST https://api.ones1ght.com/v1/profile/$PERSONA_ID/session/stamp \
  -H "Authorization: Bearer $SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "SHOPPING", "meta": {"zone": "wine"}}'

# Fetch current session (restore resume point)
curl https://api.ones1ght.com/v1/profile/$PERSONA_ID/session \
  -H "Authorization: Bearer $SDK_KEY"

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