Skip to main content
POST
/
entity-node
Add Entity Node
curl --request POST \
  --url https://memory.stru.ai/entity-node \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '{
  "uuid": "<string>",
  "group_id": "<string>",
  "name": "<string>",
  "summary": "<string>"
}'
{
  "422": {},
  "message": "<string>",
  "uuid": "<string>"
}

​
Overview

Manually add an entity node to the knowledge graph. This allows you to create custom entities with specific UUIDs, useful for linking external data or pre-defining important entities.
Advanced Feature: Do not use this endpoint unless you understand the knowledge graph structure. Incorrect entity creation can affect memory retrieval quality. Most users should rely on automatic entity extraction from episodes.
Most entities are automatically extracted from episodes. Use this endpoint when you need to manually create entities with specific identifiers.

​
Authentication

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

​
Request Body

​
uuid
string
required
The UUID for the entity node (you provide this)
"uuid": "e090f257-c182-4930-819d-161c66bee335"
​
group_id
string
required
User identifier (group ID) that owns this entity
"group_id": "user_oauth_sub"
​
name
string
required
The name/label of the entity
"name": "Presidio Tower Project"
​
summary
string
default:""
Optional summary or description of the entity
"summary": "12-story steel moment frame building in San Francisco"

​
Response

​
message
string
Confirmation message
"message": "Entity node created successfully"
​
uuid
string
The UUID of the created entity node
"uuid": "e090f257-c182-4930-819d-161c66bee335"

​
Example Request

curl -X POST https://memory.stru.ai/entity-node \
  -H "X-API-Key: windowseat" \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "e090f257-c182-4930-819d-161c66bee335",
    "group_id": "user_oauth_sub",
    "name": "Presidio Tower Project",
    "summary": "12-story steel moment frame building in San Francisco"
  }'

​
Example Response

{
  "message": "Entity node created successfully",
  "uuid": "e090f257-c182-4930-819d-161c66bee335"
}

​
Use Cases

Pre-define Important Entities

Create key entities (projects, people, locations) before adding episodes, ensuring consistent UUIDs for later reference

Link External Data

Create entities with UUIDs that match your external database records for easy cross-referencing

Center Node for Retrieval

Create entities to use as center_node_uuid in /get-memory requests for focused retrieval

​
Best Practices

Generate deterministic UUIDs - If linking to external data, use UUID v5 (name-based) for reproducible identifiers
Store the UUID - Save the UUID in your database to use later for center_node_uuid in memory retrieval
You can then use this entity UUID as the center_node_uuid when calling /get-memory to retrieve facts centered around this entity.

​
Error Responses

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