API Reference

Query Memory

Run semantic recall over the caller's memories. The handler embeds the query string, runs nearest-neighbor search in the vector index scoped to tenant + project, joins metadata back from the primary datastore, and optionally reranks.

POST/memory/query

Authentication

Accepts a JWT bearer token (Authorization: Bearer eyJ…) or an API key (X-API-Key: ms_live_…). API-key callers should send X-Project-ID unless the key is project-locked. Cross-tenant operators must send X-Tenant-ID.

Request body

Field	Type	Required	Description
`query`	`string`	required	Natural-language recall string.
`limit`	`integer`	optional	Default 10, max 100.
`filters`	`object`	optional	Equality / range filters over `metadata`, `tags`, `memory_type`.
`min_score`	`number`	optional	Drop hits below this similarity threshold.
`rerank`	`boolean`	optional	Run the reranker pass (slower, more accurate).

request.json

{
  "query": "how does this user like their UI?",
  "limit": 5,
  "filters": {
    "tags": [
      "preferences"
    ]
  }
}

Response

Returns 200 OK with the following body.

Field	Type	Required	Description
`memories`	`array`	optional	Ranked hits ordered by descending score.
`total`	`integer`	optional	Total candidates considered before `limit`.
`request_id`	`string`	optional	Trace id. Quote in support tickets.

200.json

{
  "memories": [
    {
      "id": 184213,
      "text": "User prefers dark mode and concise responses.",
      "score": 0.834,
      "metadata": {
        "source": "chat",
        "user_id": "u_42"
      },
      "created_at": "2026-05-04T12:30:11Z"
    }
  ],
  "total": 1,
  "request_id": "req_01HX..."
}

Errors

Status	Code	Description
400	`validation_error`	Body or query failed schema validation. The error includes the offending `field` name.
401	`unauthenticated`	Missing or invalid bearer token / API key.
403	`forbidden`	Authenticated principal lacks the required scope, role, or project access.
404	`not_found`	Target resource does not exist or is not visible to the calling tenant.
429	`rate_limited`	Per-IP or per-route limit exceeded. Respect the `Retry-After` header.
500	`internal_error`	Unhandled server error. Quote the `request_id` when contacting support.

Examples

cURL

curl -X POST https://api.memorysync.io/memory/query \
  -H "Authorization: Bearer $MEMORYSYNC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "how does this user like their UI?",
  "limit": 5,
  "filters": {
    "tags": [
      "preferences"
    ]
  }
}'

javascript

import { MemorySync } from 'memorysync'

const client = new MemorySync({ apiKey: process.env.MEMORYSYNC_KEY })

const result = await client.request({
  method: 'POST',
  path: '/memory/query',
  body: {
    "query": "how does this user like their UI?",
    "limit": 5,
    "filters": {
      "tags": [
        "preferences"
      ]
    }
  },
})
console.log(result)

python

from memorysync import Client

client = Client(api_key=os.environ["MEMORYSYNC_KEY"])

result = client.request(
    method="POST",
    path="/memory/query",
    json={
      "query": "how does this user like their UI?",
      "limit": 5,
      "filters": {
        "tags": [
          "preferences"
        ]
      }
    },
)
print(result)

Behavior & notes

Read-only and safe to retry. Vector search is scoped to the caller's tenant and project; cross-tenant results are never returned.

When your organisation is over its monthly query quota, the route silently returns 200 with {"memories":[]}. No error is surfaced to the caller. Watch the usage dashboard or configure quota alerts to detect this state.

← Previous

Bulk Add Memory

Get Memory