SynapSynapDocs
Hub REST API

Memory

The Memory operations of the Hub REST API (7 operations).

For BuildersOpen-source podSynap CloudGenerated from Synap-core/backend@c31e261ab (main)

Full-text search facts

GET
/memory

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Query Parameters

userId?string
query?string
q?string
limit?string

Response Body

Matching facts

application/json
  1. response
[index: integer]?
Example Request
curl -X GET 'https://pod.example.com/api/hub/memory'
Example Response
[  {    "id": "string",    "userId": "string",    "fact": "string",    "confidence": 0,    "sourceEntityId": "string",    "sourceMessageId": "string",    "createdAt": "string",    "updatedAt": "string"  }]

Save a memory fact

POST
/memory

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
userId?string

Defaults to the authenticated agent's user when omitted.

fact*string
Length1 <= length
confidence?number
Range0 <= value <= 1
embedding?array<number>

Optional 1536-d embedding. Falls back to a zero vector when omitted.

sourceEntityId?string
sourceMessageId?string

Response Body

Saved fact

application/json
  1. response
id*string
userId*string
fact*string
confidence?number
Range0 <= value <= 1
sourceEntityId?string|null
sourceMessageId?string|null
createdAt?string|
updatedAt?string|
Example Request
curl -X POST 'https://pod.example.com/api/hub/memory' \  -H 'Content-Type: application/json' \  -d '{  "fact": "string"}'
Example Response
{  "id": "string",  "userId": "string",  "fact": "string",  "confidence": 0,  "sourceEntityId": "string",  "sourceMessageId": "string",  "createdAt": "string",  "updatedAt": "string"}

Semantic search facts by embedding

POST
/memory/search

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
userId*string
embedding*array<number>
limit?integer
Range0 < value <= 100

Response Body

Matching facts

application/json
  1. response
[index: integer]?
Example Request
curl -X POST 'https://pod.example.com/api/hub/memory/search' \  -H 'Content-Type: application/json' \  -d '{  "userId": "string",  "embedding": [    0  ]}'
Example Response
[  {    "id": "string",    "userId": "string",    "fact": "string",    "confidence": 0,    "sourceEntityId": "string",    "sourceMessageId": "string",    "createdAt": "string",    "updatedAt": "string"  }]

Delete a fact

DELETE
/memory/{id}

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Path Parameters

id*string

Query Parameters

userId*string

Response Body

Deleted

application/json
  1. response
success*boolean
Example Request
curl -X DELETE 'https://pod.example.com/api/hub/memory/string?userId=string'
Example Response
{  "success": true}

Store grouped chat turns

POST
/memory/turns

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
userId?string

Defaults to the authenticated agent's user when omitted.

sessionId*string

Session grouping ID.

turns*array<>
Items1 <= items
summary?string

Optional human-readable summary.

confidence?number
Range0 <= value <= 1
embedding?array<number>

Optional 1536-d embedding for the full session. Falls back to zero vector.

sourceEntityId?string
sourceMessageId?string

Response Body

Batch result

application/json
  1. response
success*boolean
facts*array<>
count*integer
Range0 <= value
Example Request
curl -X POST 'https://pod.example.com/api/hub/memory/turns' \  -H 'Content-Type: application/json' \  -d '{  "sessionId": "string",  "turns": [    {      "role": "user",      "content": "string"    }  ]}'
Example Response
{  "success": true,  "facts": [    {      "id": "string",      "userId": "string",      "fact": "string",      "confidence": 0,      "sourceEntityId": "string",      "sourceMessageId": "string",      "createdAt": "string",      "updatedAt": "string"    }  ],  "count": 0}

Store session metadata

POST
/memory/sessions

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
userId?string

Defaults to the authenticated agent's user when omitted.

sessionId*string

Unique session ID.

summary*string

Human-readable session summary.

Length1 <= length
turnCount?integer
Range0 < value
tags?array<string>
metadata?
confidence?number
Range0 <= value <= 1

Response Body

Session metadata stored

application/json
  1. response
success*boolean
facts*array<>
count*integer
Range0 <= value
Example Request
curl -X POST 'https://pod.example.com/api/hub/memory/sessions' \  -H 'Content-Type: application/json' \  -d '{  "sessionId": "string",  "summary": "string"}'
Example Response
{  "success": true,  "facts": [    {      "id": "string",      "userId": "string",      "fact": "string",      "confidence": 0,      "sourceEntityId": "string",      "sourceMessageId": "string",      "createdAt": "string",      "updatedAt": "string"    }  ],  "count": 0}

Batch structured writes

POST
/memory/writes

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Pod API key (Bearer) issued via /api/hub/setup/agent or pod admin tooling. Browser/web clients may use the X-Session-Token header instead. See GET /api/hub/auth/status to introspect the calling key.

Request Body

application/json
  1. body
userId?string

Defaults to the authenticated agent's user when omitted.

entries*array<>
Items1 <= items <= 50
confidence?number
Range0 <= value <= 1

Response Body

Batch result

application/json
  1. response
success*boolean
facts*array<>
count*integer
Range0 <= value
Example Request
curl -X POST 'https://pod.example.com/api/hub/memory/writes' \  -H 'Content-Type: application/json' \  -d '{  "entries": [    {      "action": "remember",      "target": "string",      "content": "string"    }  ]}'
Example Response
{  "success": true,  "facts": [    {      "id": "string",      "userId": "string",      "fact": "string",      "confidence": 0,      "sourceEntityId": "string",      "sourceMessageId": "string",      "createdAt": "string",      "updatedAt": "string"    }  ],  "count": 0}

MCP

The MCP operations of the Hub REST API (1 operation).

Messaging

The Messaging operations of the Hub REST API (17 operations).