Sessions

Sessions provide stateful, multi-turn conversation management for AI agents. Store messages, maintain context, and manage conversation lifecycle — all scoped to your organization.

Create a session

curl -X POST https://api.fold.run/sessions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer support chat",
    "ttl_seconds": 3600,
    "context": { "customer_id": "cust_123", "plan": "pro" }
  }'

Field	Type	Required	Description
name	string	Yes	Human-readable session name
ttl_seconds	number	No	Time-to-live in seconds (default: 3600)
context	object	No	Arbitrary JSON for agent state

Response:

{
  "id": "sess_abc123",
  "name": "Customer support chat",
  "status": "active",
  "ttl_seconds": 3600,
  "expires_at": 1710547200000,
  "message_count": 0,
  "context": { "customer_id": "cust_123", "plan": "pro" }
}

Add messages

Append messages to a session:

curl -X POST https://api.fold.run/sessions/sess_abc123/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "content": "What is my current usage?"
  }'

Field	Type	Required	Description
role	string	Yes	user or assistant
content	string	Yes	Message text
tool_call_id	string	No	ID of the tool call this message responds to
tool_name	string	No	Name of the tool that was called

You cannot add messages to expired or completed sessions.

Get session with messages

curl https://api.fold.run/sessions/sess_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns the session metadata plus all messages in order.

Update context

Store or update arbitrary agent state:

curl -X PUT https://api.fold.run/sessions/sess_abc123/context \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "cust_123", "plan": "pro", "last_action": "checked_usage" }'

Context is replaced entirely (not merged), so always send the full object.

List sessions

curl "https://api.fold.run/sessions?status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"

Filter by status: active, completed, or expired.

Delete a session

curl -X DELETE https://api.fold.run/sessions/sess_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Close a session

Close a session to mark it as complete and persist a conversation summary to vector memory. This enables cross-session context — future sessions can query memory to find relevant prior conversations.

curl -X POST https://api.fold.run/sessions/sess_abc123/close \
  -H "Authorization: Bearer YOUR_TOKEN"

The response returns the session with status: "closed". A conversation summary is generated in the background via AI and stored in vector memory with the session-memory namespace.

Session lifecycle

Sessions move through four states:

Status	Description
active	Accepting new messages
closed	Explicitly closed; summary persisted to vector memory
completed	Manually marked complete
expired	TTL elapsed; read-only

Close sessions when the conversation is done to capture a summary. Expired sessions can still be read but not modified. Delete sessions you no longer need to keep storage clean.

Use cases

• Multi-turn chat — Store user/assistant message history for conversational agents.
• Agent state — Use the context field to persist agent decisions, preferences, or intermediate results across tool calls.
• Audit trail — Review complete conversation transcripts for debugging or compliance.