Octopus
Episodic Memory API
The Episodic Memory REST API allows external systems and the conversation history UI to query, replay, and manage episodes. All endpoints are tenant-scoped and require a valid bearer token.
API Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /api/octopus/episodes | List episodes for the authenticated user, paginated |
| GET | /api/octopus/episodes/{id} | Get a specific episode by ID (with full messages if active) |
| GET | /api/octopus/episodes?agentId=&userId= | Filter by agent and user (admin only) |
| POST | /api/octopus/episodes/search | Semantic search across episodes |
| DELETE | /api/octopus/episodes/{id} | Delete a specific episode (GDPR erasure) |
| DELETE | /api/octopus/users/{userId}/episodes | Erase all episodes for a user |
List Episodes
GET /api/octopus/episodes?page=1&pageSize=20&agentId={guid}
Authorization: Bearer {token}
// Response
{
"items": [
{
"id": "3f2a...",
"sessionId": "9b1c...",
"agentId": "5e7d...",
"agentDisplayName": "HR Agent",
"startedAt": "2025-05-20T09:14:22Z",
"endedAt": "2025-05-20T09:28:10Z",
"messageCount": 12,
"summary": "User inquired about annual leave policy...",
"isArchived": false
}
],
"totalCount": 47,
"page": 1,
"pageSize": 20
}Semantic Episode Search
POST /api/octopus/episodes/search
Authorization: Bearer {token}
Content-Type: application/json
{
"query": "annual leave balance",
"agentId": "5e7d...",
"topK": 5,
"includeArchived": false
}
// Response
{
"results": [
{
"episodeId": "3f2a...",
"summary": "User inquired about annual leave policy...",
"date": "2025-05-20T09:14:22Z",
"relevanceScore": 0.91,
"isArchived": false
}
]
}TypeScript Client Example
// Fetching conversation history in chat-app
interface EpisodeListItem {
id: string;
agentDisplayName: string;
startedAt: string;
messageCount: number;
summary: string;
}
async function getConversationHistory(
agentId: string, token: string
): Promise<EpisodeListItem[]> {
const res = await fetch(
`/api/octopus/episodes?agentId=${agentId}&pageSize=10`,
{ headers: { Authorization: `Bearer ${token}` } }
);
const data = await res.json();
return data.items;
}