Skip to main content
POST
/
api
/
v1
/
sessions
Create Session
curl --request POST \
  --url https://api.example.com/api/v1/sessions \
  --header 'X-API-Key: <x-api-key>'
{
  "status": "<string>",
  "result": {
    "session_id": "<string>",
    "user": {}
  },
  "time": 123
}
Create a new session to track conversation state, context usage, and extract long-term memories. Each session is assigned a unique ID automatically.

​
Request

​
Headers

​
X-API-Key
string
required
Your OpenViking API key for authentication
​
Content-Type
string
default:"application/json"
Must be application/json

​
Response

​
status
string
Response status (ok or error)
​
result
object
Session creation result
​
session_id
string
Auto-generated session identifier
​
user
object
User information associated with the session
​
time
number
Request processing time in seconds

​
Examples

curl -X POST http://localhost:1933/api/v1/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key"

​
Response Example

{
  "status": "ok",
  "result": {
    "session_id": "a1b2c3d4",
    "user": {
      "user_id": "alice",
      "agent_id": "default"
    }
  },
  "time": 0.1
}

​
Session Lifecycle

Once created, a session can be used to:
  1. Add messages - Track conversation turns with add_message()
  2. Search with context - Improve retrieval using session history
  3. Track usage - Record which contexts and skills were actually used
  4. Commit - Archive messages and extract long-term memories

​
Session URI Structure

Each session is stored at: 
viking://session/{user_space}/{session_id}/
├── messages.jsonl          # Current messages
├── .abstract.md            # L0: One-sentence summary
├── .overview.md            # L1: Session structure description
├── tools/                  # Tool execution records
└── history/                # Archived message archives
    ├── archive_001/
    └── archive_002/