Narratives API

Narrative thread management endpoints

GET /api/narratives

List narrative threads

Query parameters:

Parameter	Type	Required	Description
limit	integer	No	Maximum number of narratives to return
offset	integer	No	Number of narratives to skip
state	open \	resolved \	reopened \
topics	string	No	Comma-separated list of topics to filter by

Response: 200 List of narratives

Field	Type	Required	Description
data	NarrativeThread[]	Yes
pagination	object	Yes

Example:

curl -X GET "https://api.memnexus.ai/api/narratives" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

POST /api/narratives

Create a narrative thread

Request body:

Field	Type	Required	Description
title	string	Yes	Title for the narrative thread
rootMemoryId	string	Yes	ID of the first memory in this narrative
topics	string[]	No	Topics to associate with this narrative

Response: 201 Narrative created successfully

Field	Type	Required	Description
data	NarrativeThread	Yes

Example:

curl -X POST "https://api.memnexus.ai/api/narratives" \
  -H "Authorization: Bearer cmk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

---

GET /api/narratives/{id}

Get a narrative thread

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The narrative ID

Response: 200 Narrative retrieved successfully

Field	Type	Required	Description
data	NarrativeThread	Yes

Example:

curl -X GET "https://api.memnexus.ai/api/narratives/mem_abc123" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

PATCH /api/narratives/{id}

Update a narrative thread

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The narrative ID

Request body:

Field	Type	Required	Description
title	string	No	Updated title for the narrative
state	open \	resolved \	reopened \
resolutionMemoryId	string	No	ID of the memory that resolves this narrative
topics	string[]	No	Updated topics for the narrative

Response: 200 Narrative updated successfully

Field	Type	Required	Description
data	NarrativeThread	Yes

Example:

curl -X PATCH "https://api.memnexus.ai/api/narratives/mem_abc123" \
  -H "Authorization: Bearer cmk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

---

DELETE /api/narratives/{id}

Delete a narrative thread

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The narrative ID

Response: 204 Narrative deleted successfully

Example:

curl -X DELETE "https://api.memnexus.ai/api/narratives/mem_abc123" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

POST /api/narratives/{id}/memories

Add a memory to a narrative

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The narrative ID

Request body:

Field	Type	Required	Description
memoryId	string	Yes	ID of the memory to add to the narrative
position	integer	No	Position in the narrative (0-indexed, omit for append)

Response: 200 Memory added to narrative successfully

Field	Type	Required	Description
data	NarrativeThread	Yes

Example:

curl -X POST "https://api.memnexus.ai/api/narratives/mem_abc123/memories" \
  -H "Authorization: Bearer cmk_live_xxx.yyy" \
  -H "Content-Type: application/json" \
  -d '{}'

---

DELETE /api/narratives/{id}/memories/{memoryId}

Remove a memory from a narrative

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The narrative ID
memoryId	string	Yes	The memory ID to remove

Response: 204 Memory removed from narrative successfully

Example:

curl -X DELETE "https://api.memnexus.ai/api/narratives/mem_abc123/memories/mem_abc123" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---

GET /api/narratives/{id}/timeline

Get narrative timeline

Path parameters:

Parameter	Type	Required	Description
id	string	Yes	The narrative ID

Query parameters:

Parameter	Type	Required	Description
limit	integer	No	Maximum number of memories to return
offset	integer	No	Number of memories to skip

Response: 200 Narrative timeline retrieved successfully

Field	Type	Required	Description
data	NarrativeMemory[]	Yes
narrative	NarrativeThread	Yes
pagination	object	Yes

Example:

curl -X GET "https://api.memnexus.ai/api/narratives/mem_abc123/timeline" \
  -H "Authorization: Bearer cmk_live_xxx.yyy"

---