supermemory/apps/docs/search/examples/document-search.mdx

---
title: "Documents Search (/v3/search)"
description: "Full-featured search with extensive control over ranking, filtering, and results"
---

Documents search (`POST /v3/search`) provides maximum control over search behavior with extensive parameters for fine-tuning results.

## Basic Implementation

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    import Supermemory from 'supermemory';

    const client = new Supermemory({
      apiKey: process.env.SUPERMEMORY_API_KEY!
    });

    const results = await client.search.documents({
      q: "machine learning neural networks",
      limit: 5
    });

    console.log(`Found ${results.total} documents in ${results.timing}ms`);

    // Sample output structure
    results.results.forEach((doc, i) => {
      console.log(`${i + 1}. ${doc.title} (Score: ${doc.score})`);
      console.log(`   ${doc.chunks.length} chunks found`);
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    from supermemory import Supermemory
    import os

    client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))

    results = client.search.documents(
        q="machine learning neural networks",
        limit=5
    )

    print(f"Found {results.total} documents in {results.timing}ms")

    # Sample output structure
    for i, doc in enumerate(results.results):
        print(f"{i + 1}. {doc.title} (Score: {doc.score})")
        print(f"   {len(doc.chunks)} chunks found")
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/search" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "q": "machine learning neural networks",
        "limit": 5
      }'
    ```
  </Tab>
</Tabs>

**Sample Output:**
```json
{
  "results": [
    {
      "documentId": "doc_ml_guide_2024",
      "title": "Machine Learning with Neural Networks: A Comprehensive Guide",
      "score": 0.89,
      "chunks": [
        {
          "content": "Neural networks are computational models inspired by biological neural networks. They consist of interconnected nodes (neurons) that process information through weighted connections...",
          "score": 0.92,
          "isRelevant": true
        },
        {
          "content": "Deep learning, a subset of machine learning, uses neural networks with multiple hidden layers to learn complex patterns in data...",
          "score": 0.87,
          "isRelevant": true
        }
      ],
      "createdAt": "2024-01-15T10:30:00Z",
      "metadata": {
        "category": "ai",
        "difficulty": "intermediate"
      }
    }
  ],
  "total": 12,
  "timing": 156
}
```

## Container Tags Filtering

Container tags are the primary way to isolate search results by user, project, or organization.

**Key behaviors:**
- **Array-based**: Unlike `/v4/search`, this endpoint accepts multiple container tags as an array
- **Exact array matching**: Documents must have the EXACT same container tags array to match

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.documents({
      q: "quarterly reports",
      containerTags: ["user_123"],
      limit: 10
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.documents(
        q="quarterly reports",
        container_tags=["user_123"],
        limit=10
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/search" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "q": "quarterly reports",
        "containerTags": ["user_123"],
        "limit": 10
      }'
    ```
  </Tab>
</Tabs>

## Metadata Filtering

Metadata filtering allows complex conditions on structured data attached to your documents. This uses SQL-like query construction in the backend, requiring explicit AND/OR structures.

**Filter structure rules:**
- **Must wrap conditions** in AND or OR arrays, even for single conditions
- **Supports string matching** (exact), numeric operators, and array contains
- **Negate any condition** with `negate: true`
- **Combines with container tags** - both filters are applied

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.documents({
      q: "machine learning",
      filters: {
        AND: [
          {
            key: "category",
            value: "technology",
            negate: false
          },
          {
            filterType: "numeric",
            key: "readingTime",
            value: "5",
            negate: false,
            numericOperator: "<="
          }
        ]
      },
      limit: 10
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.documents(
        q="machine learning",
        filters={
            "AND": [
                {
                    "key": "category",
                    "value": "technology",
                    "negate": False
                },
                {
                    "filterType": "numeric",
                    "key": "readingTime",
                    "value": "5",
                    "negate": False,
                    "numericOperator": "<="
                }
            ]
        },
        limit=10
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/search" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "q": "machine learning",
        "filters": {
          "AND": [
            {
              "key": "category",
              "value": "technology",
              "negate": false
            },
            {
              "filterType": "numeric",
              "key": "readingTime",
              "value": "5",
              "negate": false,
              "numericOperator": "<="
            }
          ]
        },
        "limit": 10
      }'
    ```
  </Tab>
</Tabs>

**Sample Output:**
```json
{
  "results": [
    {
      "documentId": "doc_tech_trends_2024",
      "title": "Technology Trends in Machine Learning",
      "score": 0.91,
      "chunks": [
        {
          "content": "Machine learning continues to evolve with new architectures and optimization techniques. Reading time for this comprehensive overview is approximately 8 minutes...",
          "score": 0.88,
          "isRelevant": true
        }
      ],
      "metadata": {
        "category": "technology",
        "readingTime": 8,
        "difficulty": "intermediate",
        "published": true
      }
    }
  ],
  "total": 6,
  "timing": 189
}
```

## Array Contains Filtering

When your metadata includes arrays (like participant lists, tags, or categories), use `array_contains` to check if the array includes a specific value.

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.documents({
      q: "meeting discussion",
      filters: {
        AND: [
          {
            key: "participants",
            value: "john.doe",
            filterType: "array_contains"
          }
        ]
      },
      limit: 5
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.documents(
        q="meeting discussion",
        filters={
            "AND": [
                {
                    "key": "participants",
                    "value": "john.doe",
                    "filterType": "array_contains"
                }
            ]
        },
        limit=5
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/search" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "q": "meeting discussion",
        "filters": {
          "AND": [
            {
              "key": "participants",
              "value": "john.doe",
              "filterType": "array_contains"
            }
          ]
        },
        "limit": 5
      }'
    ```
  </Tab>
</Tabs>

## Threshold Control

Control result quality with sensitivity thresholds:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.documents({
      q: "artificial intelligence",
      documentThreshold: 0.7,  // Higher = fewer, more relevant documents
      chunkThreshold: 0.8,     // Higher = fewer, more relevant chunks
      limit: 10
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.documents(
        q="artificial intelligence",
        document_threshold=0.7,  # Higher = fewer, more relevant documents
        chunk_threshold=0.8,     # Higher = fewer, more relevant chunks
        limit=10
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/search" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "q": "artificial intelligence",
        "documentThreshold": 0.7,
        "chunkThreshold": 0.8,
        "limit": 10
      }'
    ```
  </Tab>
</Tabs>

## Query Rewriting

Improve search accuracy with automatic query rewriting:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.documents({
      q: "What is the capital of France?",
      rewriteQuery: true,  // +400ms latency but better results
      limit: 5
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.documents(
        q="What is the capital of France?",
        rewrite_query=True,  # +400ms latency but better results
        limit=5
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/search" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "q": "What is the capital of France?",
        "rewriteQuery": true,
        "limit": 5
      }'
    ```
  </Tab>
</Tabs>

<Note>
Query rewriting generates multiple query variations and searches through all of them, then merges results. No additional cost but adds ~400ms latency.
</Note>

## Reranking

Improve result quality with secondary ranking:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.documents({
      q: "machine learning applications",
      rerank: true,  // Apply secondary ranking algorithm
      limit: 10
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.documents(
        q="machine learning applications",
        rerank=True,  # Apply secondary ranking algorithm
        limit=10
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/search" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "q": "machine learning applications",
        "rerank": true,
        "limit": 10
      }'
    ```
  </Tab>
</Tabs>

## Document-Specific Search

Search within a specific large document:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.documents({
      q: "neural networks",
      docId: "doc_123",  // Search only within this document
      limit: 10
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.documents(
        q="neural networks",
        doc_id="doc_123",  # Search only within this document
        limit=10
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/search" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "q": "neural networks",
        "docId": "doc_123",
        "limit": 10
      }'
    ```
  </Tab>
</Tabs>

## Full Context Options

Include complete document content and summaries:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.documents({
      q: "research findings",
      includeFullDocs: true,    // Include complete document content
      includeSummary: true,     // Include document summaries
      onlyMatchingChunks: false, // Include all chunks, not just matching ones
      limit: 5
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.documents(
        q="research findings",
        include_full_docs=True,    # Include complete document content
        include_summary=True,      # Include document summaries
        only_matching_chunks=False, # Include all chunks, not just matching ones
        limit=5
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/search" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "q": "research findings",
        "includeFullDocs": true,
        "includeSummary": true,
        "onlyMatchingChunks": false,
        "limit": 5
      }'
    ```
  </Tab>
</Tabs>

## Complete Advanced Example

Combining all features for maximum control:

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    const results = await client.search.documents({
      q: "machine learning performance metrics",
      containerTags: ["research_project"],
      filters: {
        AND: [
          { key: "category", value: "ai", negate: false },
          { key: "status", value: "published", negate: false }
        ]
      },
      documentThreshold: 0.6,
      chunkThreshold: 0.7,
      rewriteQuery: true,
      rerank: true,
      includeFullDocs: false,
      includeSummary: true,
      onlyMatchingChunks: true,
      limit: 10
    });
    ```
  </Tab>
  <Tab title="Python">
    ```python
    results = client.search.documents(
        q="machine learning performance metrics",
        container_tags=["research_project"],
        filters={
            "AND": [
                {"key": "category", "value": "ai", "negate": False},
                {"key": "status", "value": "published", "negate": False}
            ]
        },
        document_threshold=0.6,
        chunk_threshold=0.7,
        rewrite_query=True,
        rerank=True,
        include_full_docs=False,
        include_summary=True,
        only_matching_chunks=True,
        limit=10
    )
    ```
  </Tab>
  <Tab title="cURL">
    ```bash
    curl -X POST "https://api.supermemory.ai/v3/search" \
      -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "q": "machine learning performance metrics",
        "containerTags": ["research_project"],
        "filters": {
          "AND": [
            {"key": "category", "value": "ai", "negate": false},
            {"key": "status", "value": "published", "negate": false}
          ]
        },
        "documentThreshold": 0.6,
        "chunkThreshold": 0.7,
        "rewriteQuery": true,
        "rerank": true,
        "includeFullDocs": false,
        "includeSummary": true,
        "onlyMatchingChunks": true,
        "limit": 10
      }'
    ```
  </Tab>
</Tabs>