Skip to main content
POST
/
episodes
Add Episodes
curl --request POST \
  --url https://memory.stru.ai/episodes \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '{
  "group_id": "<string>",
  "messages": [
    {
      "content": "<string>",
      "role_type": "<string>",
      "role": {},
      "timestamp": "<string>",
      "uuid": "<string>",
      "name": "<string>",
      "source_description": "<string>"
    }
  ],
  "json_data": [
    {
      "content": {},
      "timestamp": "<string>",
      "uuid": "<string>",
      "name": "<string>",
      "source_description": "<string>"
    }
  ],
  "text_data": [
    {
      "content": "<string>",
      "timestamp": "<string>",
      "uuid": "<string>",
      "name": "<string>",
      "source_description": "<string>"
    }
  ]
}'
{
  "422": {},
  "message": "<string>",
  "success": true
}

​
Overview

Add episodes to the knowledge graph for automatic knowledge extraction. Supports three types of episodes:
  • Messages: Conversational episodes with role information
  • JSON Data: Structured JSON data episodes
  • Text Data: Plain text episodes
Only one episode type can be provided per request. Processing is asynchronous and takes 1-5 minutes.

​
Authentication

​
X-API-Key
string
required
Your API key for authentication
X-API-Key: windowseat

​
Request Body

​
group_id
string
required
User identifier (group ID) for the episodes
"group_id": "user_oauth_sub"
​
messages
array
Message episodes to add (conversational data)
"messages": [
  {
    "content": "I'm working on a 12-story building",
    "role_type": "user",
    "role": "bhosh",
    "timestamp": "2025-10-11T03:00:00Z",
    "source_description": "conv_12345"
  }
]
​
json_data
array
JSON episodes to add (structured data)
"json_data": [
  {
    "content": {
      "project": "Presidio Tower",
      "location": "San Francisco",
      "stories": 12
    },
    "timestamp": "2025-10-11T03:00:00Z",
    "source_description": "conv_12345"
  }
]
​
text_data
array
Text episodes to add (unstructured text)
"text_data": [
  {
    "content": "Analysis Results: Max drift 1.8% at Story 8",
    "timestamp": "2025-10-11T03:00:00Z",
    "source_description": "conv_12345"
  }
]

​
Response

​
message
string
Confirmation message indicating episodes were queued
"message": "2 message episodes added to processing queue"
​
success
boolean
Always true for successful requests
"success": true

​
Example Requests

curl -X POST https://memory.stru.ai/episodes \
  -H "X-API-Key: windowseat" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "user_oauth_sub",
    "messages": [
      {
        "content": "I'm working on a 12-story building in SF",
        "role_type": "user",
        "role": "bhosh",
        "timestamp": "2025-10-11T03:00:00Z",
        "source_description": "conv_12345"
      },
      {
        "content": "For SF, use ASCE 7-22 seismic standards",
        "role_type": "assistant",
        "role": "assistant",
        "timestamp": "2025-10-11T03:00:15Z",
        "source_description": "conv_12345"
      }
    ]
  }'

​
Example Response

{
  "message": "2 message episodes added to processing queue",
  "success": true
}
Status Code: 202 Accepted - Episodes are queued for async processing (1-5 minutes)

​
Error Responses

​
422
Validation Error
Request validation failed
{
  "detail": [
    {
      "loc": ["body", "group_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
Best Practices

Always use source_description - Group related episodes together for easy batch cleanup when users delete conversations
Include timestamps - The knowledge graph uses these for temporal fact tracking
One episode type per request - Don’t mix messages, json_data, and text_data in the same request
Wait for processing - Knowledge extraction takes 1-5 minutes. You can continue adding episodes while previous ones process.
For JSON data, use meaningful keys (e.g., "height_ft": 144 not "h": 144) to improve entity extraction quality.