Create Session

POST

api

sessions

Create Session

curl --request POST \
  --url https://api.example.com/api/v1/sessions \
  --header 'X-API-Key: <x-api-key>'

const options = {method: 'POST', headers: {'X-API-Key': '<x-api-key>'}};

fetch('https://api.example.com/api/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/sessions"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("X-API-Key", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

{
  "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

string

required

Your OpenViking API key for authentication

string

default:"application/json"

Must be application/json

Response

string

Response status (ok or error)

object

Session creation result

string

Auto-generated session identifier

object

User information associated with the session

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"

import openviking as ov

# Initialize client
client = ov.OpenViking(path="./my_data")
client.initialize()

# Create new session (auto-generated ID)
session = client.session()
print(f"Session created: {session.session_id}")
print(f"Session URI: {session.uri}")

import requests

response = requests.post(
    "http://localhost:1933/api/v1/sessions",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "your-api-key"
    }
)

result = response.json()
print(f"Session ID: {result['result']['session_id']}")

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:

Add messages - Track conversation turns with add_message()
Search with context - Improve retrieval using session history
Track usage - Record which contexts and skills were actually used
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/

Add Message - Add messages to the session
Commit Session - Archive and extract memories
Get Session - Retrieve session details
Delete Session - Remove a session

⌘I

Create Session

curl --request POST \
  --url https://api.example.com/api/v1/sessions \
  --header 'X-API-Key: <x-api-key>'

const options = {method: 'POST', headers: {'X-API-Key': '<x-api-key>'}};

fetch('https://api.example.com/api/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/sessions"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("X-API-Key", "<x-api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'

response = http.request(request)
puts response.read_body

{
  "status": "<string>",
  "result": {
    "session_id": "<string>",
    "user": {}
  },
  "time": 123
}

Overview

Resources

Filesystem

Search & Retrieval

Sessions

Skills

System

Admin

Request

Headers

Response

Examples

Response Example

Session Lifecycle

Session URI Structure

​Request

​Headers

​Response

​Examples

​Response Example

​Session Lifecycle

​Session URI Structure

​Related Endpoints

Request

Headers

Response

Examples

Response Example

Session Lifecycle

Session URI Structure

Related Endpoints