Skip to main content

​
Session Endpoints

Manage agent sessions via the REST API.

​
Activate Agent

Endpoint: 
POST /api/v2/agents/{agent_id}/activate
Headers: 
Authorization: Bearer mk_your_api_key
Response (200 OK): 
{
  "agent_id": "customer-support",
  "session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "created_at": "2025-03-30T16:30:00Z",
  "expires_at": "2025-03-31T22:30:00Z"
}
Example: 
response = httpx.post(
    "http://localhost:8000/api/v2/agents/my-agent/activate",
    headers={"Authorization": f"Bearer {api_key}"}
)
session = response.json()
session_token = session["session_token"]

​
Deactivate Agent

Endpoint: 
POST /api/v2/agents/{agent_id}/deactivate
Headers: 
Authorization: Bearer mk_your_api_key
X-Session-Token: {session_token}
Response (200 OK): 
{
  "agent_id": "customer-support",
  "session_duration_minutes": 135,
  "memories_stored": 12,
  "memories_recalled": 8
}

​
Get Current Session

Endpoint: 
GET /api/v2/session/current
Headers: 
Authorization: Bearer mk_your_api_key
X-Session-Token: {session_token}
Response (200 OK): 
{
  "agent_id": "customer-support",
  "session_token": "eyJhbGc...",
  "created_at": "2025-03-30T16:30:00Z",
  "expires_at": "2025-03-31T22:30:00Z",
  "time_remaining_minutes": 345
}

​
Extend Session

Endpoint: 
POST /api/v2/session/extend
Headers: 
Authorization: Bearer mk_your_api_key
X-Session-Token: {session_token}
Query Parameters:
  • extend_hours (int) - Hours to extend (default: 6)
Response (200 OK): 
{
  "agent_id": "customer-support",
  "new_expires_at": "2025-04-01T04:30:00Z",
  "hours_added": 6
}
Example: 
response = httpx.post(
    "http://localhost:8000/api/v2/session/extend",
    params={"extend_hours": 6},
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-Session-Token": session_token
    }
)

​
Workflow: Session Management

import httpx
import time

api_key = "mk_api_key"
agent_id = "my-agent"
base_url = "http://localhost:8000/api/v2"

# 1. Activate session
activate_resp = httpx.post(
    f"{base_url}/agents/{agent_id}/activate",
    headers={"Authorization": f"Bearer {api_key}"}
)
session = activate_resp.json()
token = session["session_token"]
print(f"Session expires: {session['expires_at']}")

# 2. Check session
headers = {
    "Authorization": f"Bearer {api_key}",
    "X-Session-Token": token
}

check_resp = httpx.get(
    f"{base_url}/session/current",
    headers=headers
)
print(f"Time remaining: {check_resp.json()['time_remaining_minutes']}m")

# 3. Use session for memory operations
# ... store/recall memories ...

# 4. Extend if needed
extend_resp = httpx.post(
    f"{base_url}/session/extend",
    params={"extend_hours": 6},
    headers=headers
)
print(f"Extended to: {extend_resp.json()['new_expires_at']}")

# 5. Deactivate
deactivate_resp = httpx.post(
    f"{base_url}/agents/{agent_id}/deactivate",
    headers=headers
)

​
Next Steps