supermemory/apps/docs/v5/api-reference/search.mdx

---
title: "Search"
sidebarTitle: "Search"
description: "Semantic recall over memories, document chunks, or both."
icon: "search"
---

Search reads back what ingest wrote. Two contracts are available: the memory-oriented `POST /v4/search`, and the document/SuperRAG-oriented `POST /v3/search`.

## Search memories

`POST /v4/search`

Returns extracted memory entries ranked by similarity to the query.

<CodeGroup>

```bash cURL
curl -X POST "https://api.supermemory.ai/v4/search" \
  --header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "q": "machine learning concepts",
    "containerTag": "user_123",
    "limit": 10
  }'
```

```typescript Typescript
const response = await fetch("https://api.supermemory.ai/v4/search", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    q: "machine learning concepts",
    containerTag: "user_123",
    limit: 10,
  }),
});
```

```python Python
import os, requests

response = requests.post(
    "https://api.supermemory.ai/v4/search",
    headers={
        "Authorization": f"Bearer {os.environ['SUPERMEMORY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "q": "machine learning concepts",
        "containerTag": "user_123",
        "limit": 10,
    },
)
```

</CodeGroup>

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `q` | string | required | Search query (minimum 1 character) |
| `containerTag` | string | — | Scope results to one container |
| `limit` | number | 10 | Maximum results (1–100) |
| `threshold` | number | 0.6 | Similarity cutoff (0–1). Higher returns fewer, more precise results |
| `filters` | object | — | Metadata filters (`AND`/`OR` structure) |
| `rerank` | boolean | false | Re-score results for relevance |
| `rewriteQuery` | boolean | false | Rewrite the query before searching; adds roughly 400 ms of latency |
| `include` | object | — | Opt in to extra context per result |

`include` accepts three booleans, all defaulting to `false`:

| Field | Description |
| --- | --- |
| `documents` | Attach the source documents behind each memory |
| `summaries` | Attach document summaries |
| `relatedMemories` | Attach parent/child memory versions |

### Response

```json
{
  "results": [
    {
      "id": "mem_abc123",
      "memory": "John prefers machine learning over traditional programming",
      "metadata": { "source": "conversation", "confidence": 0.9 },
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "similarity": 0.89,
      "version": 3
    }
  ],
  "timing": 245,
  "total": 5
}
```

| Field | Type | Description |
| --- | --- | --- |
| `results[].id` | string | Memory entry id |
| `results[].memory` | string | The memory content |
| `results[].metadata` | object \| null | Memory metadata |
| `results[].updatedAt` | string | Last update timestamp |
| `results[].similarity` | number | Similarity between query and memory (0–1) |
| `results[].version` | number \| null | Version of this memory entry |
| `results[].context` | object | Present when related versions exist — `parents` and `children` arrays |
| `results[].documents` | array | Present when `include.documents` is set |
| `timing` | number | Execution time in milliseconds |
| `total` | number | Number of results returned |

## Search documents

`POST /v3/search`

Document- and chunk-oriented search, for when you want the raw source content rather than extracted facts.

```bash
curl -X POST "https://api.supermemory.ai/v3/search" \
  --header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "q": "machine learning concepts",
    "containerTags": ["user_123"],
    "limit": 10
  }'
```

### Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `q` | string | required | Search query (minimum 1 character) |
| `containerTags` | string[] | — | Scope results to one or more containers |
| `docId` | string | — | Restrict the search to a single document (max 255 chars) |
| `limit` | number | 10 | Maximum results (1–100) |
| `chunkThreshold` | number | 0 | Chunk selection sensitivity (0–1). `0` returns the most chunks |
| `documentThreshold` | number | 0 | Deprecated — currently no effect on search; ignored |
| `filters` | object | — | Metadata filters (`AND`/`OR` structure) |
| `rerank` | boolean | false | Re-score results for relevance |
| `rewriteQuery` | boolean | false | Rewrite the query before searching |
| `onlyMatchingChunks` | boolean | true | Return only matching chunks instead of including neighbouring chunks as context |
| `includeFullDocs` | boolean | false | Include full document content in each result |
| `includeSummary` | boolean | false | Include the document summary in each result |

### Response

```json
{
  "results": [
    {
      "documentId": "doc_xyz789",
      "title": "Introduction to Machine Learning",
      "type": "web",
      "score": 0.95,
      "chunks": [
        {
          "content": "Machine learning is a subset of artificial intelligence...",
          "isRelevant": true,
          "score": 0.85
        }
      ],
      "metadata": { "category": "technology" },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "timing": 92,
  "total": 5
}
```

Each result carries the document identity plus the chunks that matched. `summary` and `content` appear only when requested through `includeSummary` and `includeFullDocs`.

## Filtering

Both search operations accept the same `filters` object. Filter on metadata keys you set at ingest time.

```json
{
  "filters": {
    "AND": [
      { "key": "group", "negate": false, "value": "jira_users" },
      {
        "filterType": "numeric",
        "key": "timestamp",
        "negate": false,
        "numericOperator": ">",
        "value": "1742745777"
      }
    ]
  }
}
```

See [Organizing & Filtering](/concepts/filtering) for the full filter syntax.

## Choosing an operation

| Use | Operation |
| --- | --- |
| Facts, preferences, and context extracted from content | `POST /v4/search` |
| Raw document chunks and SuperRAG context | `POST /v3/search` |
| Both at once, through the SDK | `client.search({ searchMode: "hybrid" })` |

<Info>
The TypeScript SDK exposes a unified `client.search({ q, searchMode })` where `searchMode` is `"memories"`, `"documents"`, or `"hybrid"`. The HTTP contract stays split across the two paths above.
</Info>

## Next steps

- [Profiles](/v5/api-reference/profiles) — the compacted view of a container
- [Search guide](/recall/search) — patterns and query optimization
- [SuperRAG](/concepts/super-rag) — how document retrieval is assembled