Skip to main content
Sessions are the top-level containers for all agent interactions. They persist state, memory, and history.

​
Create Session

​
agent_id
string
required
Unique identifier for the agent (e.g., finance_bot_v1).
​
metadata
object
Arbitrary JSON key-value pairs for application context (e.g., user tier, region).
​
initial_state
object
The starting state payload for the session.
​
ttl_seconds
integer
default:"86400"
Time-to-live in seconds. Default is 24 hours. Max is 30 days.
​
id
string
The unique session ID (e.g., sess_01H...).
​
ttl_expires_at
string
ISO 8601 timestamp when the session will auto-delete.
curl -X POST https://api.statebase.org/v1/sessions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "coding_agent",
    "metadata": { "env": "prod" },
    "ttl_seconds": 3600
  }'

​
Get Session

Retrieve the full context including current state.
​
session_id
string
required
The ID of the session to retrieve.
curl https://api.statebase.org/v1/sessions/sess_01H... \
  -H "Authorization: Bearer <token>"

​
Get Session Context

The primary endpoint for building your agent’s prompt. It performs a parallel lookup of the current State, relevant Semantic Memories (via vector search), and the most recent N turns.
​
session_id
string
required
The ID of the session to retrieve.
​
query
string
The search query for semantic memory retrieval (usually the user’s current input).
​
memory_limit
integer
default:"5"
Number of semantic memories to retrieve.
​
turn_limit
integer
default:"5"
Number of recent conversation turns to include.
curl -X POST https://api.statebase.org/v1/sessions/sess_01H.../context \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Where did I park my car?",
    "memory_limit": 3
  }'

​
Delete Session

Permanently remove a session and all its distributed state (Redis + Postgres + Vector DB).
​
session_id
string
required
The ID of the session to delete.
curl -X DELETE https://api.statebase.org/v1/sessions/sess_01H... \
  -H "Authorization: Bearer <token>"