Super Agent Stack
DocsHome
New

Memory API

Programmatically manage conversation sessions and memory from your applications.

Overview

The Memory API allows you to manage conversation sessions programmatically. Create, list, update, and delete sessions directly from your application using the same superAgentKey authentication.

Authentication

All Memory API endpoints require the superAgentKey header for authentication. The same key you use for chat completions works here.

Base URL

text
https://www.superagentstack.com/api/v1/memory

Authentication

Include your Super Agent Stack API key in the request headers:

bash
curl -X GET https://www.superagentstack.com/api/v1/memory/sessions \
  -H "superAgentKey: YOUR_SUPER_AGENT_KEY"

List Sessions

GET/api/v1/memory/sessions

Retrieve all conversation sessions for your account.

Query Parameters

ParameterTypeDescription
limitnumberMax sessions to return (1-100, default: 50)
list-sessions.js
const response = await fetch('https://www.superagentstack.com/api/v1/memory/sessions?limit=20', {
  headers: {
    'superAgentKey': process.env.SUPER_AGENT_KEY
  }
});

const { data } = await response.json();
console.log(data);
// [{ id: "uuid", title: "Chat about AI", createdAt: "...", messageCount: 5 }, ...]

Create Session

POST/api/v1/memory/sessions

Create a new conversation session. You can optionally provide a custom session ID.

Request Body

FieldTypeDescription
titlestring (optional)Session title (max 255 chars)
sessionIdstring (optional)Custom UUID for the session
create-session.js
const response = await fetch('https://www.superagentstack.com/api/v1/memory/sessions', {
  method: 'POST',
  headers: {
    'superAgentKey': process.env.SUPER_AGENT_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Customer Support Chat'
  })
});

const { data } = await response.json();
console.log(data.id); // Use this sessionId in chat completions

Get Session

GET/api/v1/memory/sessions/:sessionId

Retrieve details of a specific session.

get-session.js
const sessionId = 'your-session-uuid';
const response = await fetch(`https://www.superagentstack.com/api/v1/memory/sessions/${sessionId}`, {
  headers: {
    'superAgentKey': process.env.SUPER_AGENT_KEY
  }
});

const { data } = await response.json();
console.log(data);
// { id: "uuid", title: "...", createdAt: "...", messageCount: 10, isArchived: false }

Delete Session

DELETE/api/v1/memory/sessions/:sessionId

Permanently delete a session and all its messages. This action cannot be undone.

Destructive Action

This permanently deletes the session, all messages, and associated memory embeddings. Use archive instead if you want to preserve the data.
delete-session.js
const sessionId = 'your-session-uuid';
const response = await fetch(`https://www.superagentstack.com/api/v1/memory/sessions/${sessionId}`, {
  method: 'DELETE',
  headers: {
    'superAgentKey': process.env.SUPER_AGENT_KEY
  }
});

const result = await response.json();
console.log(result);
// { success: true, message: "Session deleted successfully" }

Python Example

delete_session.py
import requests
import os

session_id = "your-session-uuid"
response = requests.delete(
    f"https://www.superagentstack.com/api/v1/memory/sessions/{session_id}",
    headers={
        "superAgentKey": os.environ.get("SUPER_AGENT_KEY")
    }
)

result = response.json()
print(result)  # {"success": True, "message": "Session deleted successfully"}

cURL Example

bash
curl -X DELETE https://www.superagentstack.com/api/v1/memory/sessions/YOUR_SESSION_ID \
  -H "superAgentKey: YOUR_SUPER_AGENT_KEY"

Archive Session

POST/api/v1/memory/sessions/:sessionId/archive

Archive a session instead of deleting it. Archived sessions are hidden from the default list but can be restored later.

archive-session.js
const sessionId = 'your-session-uuid';
const response = await fetch(`https://www.superagentstack.com/api/v1/memory/sessions/${sessionId}/archive`, {
  method: 'POST',
  headers: {
    'superAgentKey': process.env.SUPER_AGENT_KEY
  }
});

const result = await response.json();
// { success: true, message: "Session archived successfully" }

Get Session Messages

GET/api/v1/memory/sessions/:sessionId/messages

Retrieve all messages from a specific session.

get-messages.js
const sessionId = 'your-session-uuid';
const response = await fetch(`https://www.superagentstack.com/api/v1/memory/sessions/${sessionId}/messages?limit=50`, {
  headers: {
    'superAgentKey': process.env.SUPER_AGENT_KEY
  }
});

const { data } = await response.json();
console.log(data);
// [{ role: "user", content: "Hello", createdAt: "..." }, { role: "assistant", content: "Hi!", createdAt: "..." }]

Complete Example: Session Lifecycle

Here's a complete example showing how to manage sessions in a chat application:

session-lifecycle.js
import OpenAI from 'openai';

const SUPER_AGENT_KEY = process.env.SUPER_AGENT_KEY;
const BASE_URL = 'https://www.superagentstack.com';

// 1. Create a new session
async function createSession(title) {
  const response = await fetch(`${BASE_URL}/api/v1/memory/sessions`, {
    method: 'POST',
    headers: {
      'superAgentKey': SUPER_AGENT_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ title })
  });
  const { data } = await response.json();
  return data.id;
}

// 2. Use the session for chat
async function chat(sessionId, message) {
  const client = new OpenAI({
    baseURL: `${BASE_URL}/api/v1`,
    apiKey: process.env.OPENROUTER_API_KEY,
    defaultHeaders: {
      'superAgentKey': SUPER_AGENT_KEY,
      'sessionId': sessionId
    }
  });

  const response = await client.chat.completions.create({
    model: 'google/gemini-2.0-flash-exp:free',
    messages: [{ role: 'user', content: message }]
  });

  return response.choices[0].message.content;
}

// 3. Delete session when done
async function deleteSession(sessionId) {
  const response = await fetch(`${BASE_URL}/api/v1/memory/sessions/${sessionId}`, {
    method: 'DELETE',
    headers: { 'superAgentKey': SUPER_AGENT_KEY }
  });
  return response.json();
}

// Usage
async function main() {
  // Create session
  const sessionId = await createSession('Customer Support');
  console.log('Created session:', sessionId);

  // Chat with memory
  const reply1 = await chat(sessionId, 'My name is Alice');
  console.log('AI:', reply1);

  const reply2 = await chat(sessionId, 'What is my name?');
  console.log('AI:', reply2); // Will remember "Alice"

  // Clean up when done
  await deleteSession(sessionId);
  console.log('Session deleted');
}

main();

Error Responses

StatusErrorDescription
401UnauthorizedMissing or invalid superAgentKey
404Not FoundSession does not exist or belongs to another user
500Server ErrorInternal error - contact support if persistent