---
title: "Search documents"
method: POST
path: "/v3/search"
tags: ["Documents"]
---

# Search documents

`POST /v3/search`

Search memories with advanced filtering

## Request body

- object
  - `chunkThreshold` number — Threshold / sensitivity for chunk selection. 0 is least sensitive (returns most chunks, more results), 1 is most sensitive (returns lesser chunks, accurate results)
  - `containerTag` string — Optional single container tag. Use this or containerTags.
  - `containerTags` string[] — Optional tags this search should be containerized by. This can be an ID for your user, a project ID, or any other identifier you wish to use to filter documents.
  - `docId` string — Optional document ID to search within. You can use this to find chunks in a very large document.
  - `documentThreshold` number — DEPRECATED: This field is no longer used in v3 search. The search now uses chunkThreshold only. This parameter will be ignored.
  - `filters` union — Optional filters to apply to the search. Can be a JSON string or Query object.
    - object
      - `OR` union[], required — Array of OR filter expressions
        - union — A logical filter expression that can combine conditions using AND/OR operations. Supports up to 5 levels of nesting.
          - object — A single filter condition based on metadata, numeric values, array contents, or string matching
            - `filterType` 'metadata' | 'numeric' | 'array_contains' | 'string_contains'
            - `key` string, required
            - `negate` union
              - …
            - `ignoreCase` union
              - …
            - `numericOperator` '>' | '<' | '>=' | '<=' | '='
            - `value` string, required
          - object
            - `OR` union[], required — OR: Array of conditions or nested expressions
              - …
          - object
            - `AND` union[], required — AND: Array of conditions or nested expressions
              - …
    - object
      - `AND` union[], required — Array of AND filter expressions
        - union — A logical filter expression that can combine conditions using AND/OR operations. Supports up to 5 levels of nesting.
          - object — A single filter condition based on metadata, numeric values, array contents, or string matching
            - `filterType` 'metadata' | 'numeric' | 'array_contains' | 'string_contains'
            - `key` string, required
            - `negate` union
              - …
            - `ignoreCase` union
              - …
            - `numericOperator` '>' | '<' | '>=' | '<=' | '='
            - `value` string, required
          - object
            - `OR` union[], required — OR: Array of conditions or nested expressions
              - …
          - object
            - `AND` union[], required — AND: Array of conditions or nested expressions
              - …
  - `includeFullDocs` boolean — If true, include full document in the response. This is helpful if you want a chatbot to know the full context of the document.
  - `includeSummary` boolean — If true, include document summary in the response. This is helpful if you want a chatbot to know the full context of the document.
  - `limit` integer — Maximum number of results to return
  - `onlyMatchingChunks` boolean — If true, only return matching chunks without context. Normally, we send the previous and next chunk to provide more context for LLMs. If you only want the matching chunk, set this to true.
  - `q` string, required — Search query string
  - `rerank` boolean — If true, rerank the results based on the query. This is helpful if you want to ensure the most relevant results are returned.
  - `rewriteQuery` boolean — If true, rewrites the query to make it easier to find documents. This increases the latency by about 400ms
  - `categoriesFilter` string[] — DEPRECATED: Optional category filters
  - `filepath` string — Filter search results by filepath. Exact match for full paths, prefix match if ending with /

## Response `200`

Search results

- object
  - `results` object[], required
    - `chunks` object[], required — Matching content chunks from the document
      - `content` string, required — Content of the matching chunk
      - `isRelevant` boolean, required — Whether this chunk is relevant to the query
      - `score` number, required — Similarity score for this chunk
    - `createdAt` string, datetime, required — Document creation date
    - `documentId` string, required — ID of the matching document
    - `metadata` object, nullable, required — Document metadata
    - `score` number, required — Relevance score of the match
    - `summary` string, nullable — Document summary
    - `content` string, nullable — Full document content (only included when includeFullDocs=true)
    - `title` string, nullable, required — Document title
    - `updatedAt` string, datetime, required — Document last update date
    - `type` string, nullable, required — Document type
  - `timing` number, required
  - `total` number, required

## Other responses

- `400` — Invalid request parameters
- `401` — Unauthorized
- `404` — Document not found
- `500` — Server error

## Changes

- **2026-04-17** `f09b91ede978` — 1 info
  - added the new optional request property `filepath`
- **2026-04-08** `63361336422f` — 2 info
  - added the new optional request property `containerTag`
  - request property `containerTags` reactivated
- **2026-04-06** `cb825424a780` — 2 info
  - api tag `Documents` added
  - api tag `Search` removed
- **2026-03-15** `b40318167017` — 1 breaking
  - request body became required
- **2026-03-12** `7386f0fb8043` — 1 warning
  - changed the pattern of the request property `containerTags/items/` from `^[a-zA-Z0-9_-]+$` to `^[a-zA-Z0-9_:-]+$`

[Full history](https://skmtc.dev/supermemoryai/apis/supermemory-api/changes/v3/search/post.md)

---

[API](https://skmtc.dev/supermemoryai/apis/supermemory-api.md) · [All operations](https://skmtc.dev/supermemoryai/apis/supermemory-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/supermemoryai/supermemory-api/revisions/f979eba02e97/schema)