> ## Documentation Index > Fetch the complete documentation index at: https://supermemory-personal-brain-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Search documents > Search memories with advanced filtering ## OpenAPI ````yaml https://api.supermemory.ai/v4/openapi post /v3/search openapi: 3.1.0 info: title: supermemory API description: >- The Memory API for the AI era. OpenAPI operations include x-codeSamples for the official TypeScript and Python SDKs (Mintlify-compatible). version: 3.0.0 servers: - description: Production Server url: https://api.supermemory.ai security: - bearerAuth: [] tags: - name: Ingest description: Ingest documents, files, URLs, conversations, and other content - name: Recall (Search) description: >- Semantic recall across your content — supports memories, hybrid, and documents modes - name: Profiles description: >- Entity profiles for users, participants, or any entity — includes profile search - name: Content Management description: List, get, update, and delete content and memories - name: Container Tags description: List and manage container tags (spaces) — settings, merge, and delete - name: Connections description: External service integrations - name: Settings description: Organization settings - name: Documents description: List, get, and search documents paths: /v3/search: post: tags: - Documents summary: Search documents description: Search memories with advanced filtering operationId: postV3Search requestBody: required: true content: application/json: schema: type: object properties: chunkThreshold: description: >- Threshold / sensitivity for chunk selection. 0 is least sensitive (returns most chunks, more results), 1 is most sensitive (returns lesser chunks, accurate results) example: 0.5 maximum: 1 minimum: 0 default: 0 type: number containerTag: description: Optional single container tag. Use this or containerTags. example: user_alex type: string maxLength: 100 pattern: ^[a-zA-Z0-9_:-]+$ containerTags: description: >- 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. type: array items: type: string maxLength: 100 pattern: ^[a-zA-Z0-9_:-]+$ docId: description: >- Optional document ID to search within. You can use this to find chunks in a very large document. type: string maxLength: 255 documentThreshold: description: >- DEPRECATED: This field is no longer used in v3 search. The search now uses chunkThreshold only. This parameter will be ignored. maximum: 1 minimum: 0 deprecated: true default: 0 type: number filters: $ref: '#/components/schemas/QueryFilter' description: >- Optional filters to apply to the search. Can be a JSON string or Query object. includeFullDocs: default: false description: >- If true, include full document in the response. This is helpful if you want a chatbot to know the full context of the document. example: false type: boolean includeSummary: default: false description: >- If true, include document summary in the response. This is helpful if you want a chatbot to know the full context of the document. type: boolean limit: default: 10 description: Maximum number of results to return example: 10 maximum: 100 minimum: 1 type: integer exclusiveMinimum: 0 onlyMatchingChunks: default: true description: >- 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. type: boolean q: type: string minLength: 1 description: Search query string example: what are the API rate limits rerank: default: false description: >- If true, rerank the results based on the query. This is helpful if you want to ensure the most relevant results are returned. example: false type: boolean rewriteQuery: default: false description: >- If true, rewrites the query to make it easier to find documents. This increases the latency by about 400ms example: false type: boolean categoriesFilter: description: 'DEPRECATED: Optional category filters' deprecated: true type: array items: type: string filepath: description: >- Filter search results by filepath. Exact match for full paths, prefix match if ending with / x-hidden: true type: string required: - q responses: '200': content: application/json: schema: type: object properties: results: type: array items: type: object properties: chunks: type: array items: type: object properties: content: type: string description: Content of the matching chunk example: >- Rate limit headers are included in every response. Clients should implement exponential backoff when receiving 429 responses. isRelevant: type: boolean description: Whether this chunk is relevant to the query example: true position: type: number description: >- Position of this chunk within the source document (0-indexed). Use it to order chunks and to locate surrounding context chunks (isRelevant=false) relative to the matching ones. example: 3 score: type: number description: Similarity score for this chunk example: 0.85 maximum: 1 minimum: 0 required: - content - isRelevant - position - score description: Matching content chunk example: content: >- Rate limit headers are included in every response. Clients should implement exponential backoff when receiving 429 responses. isRelevant: true position: 3 score: 0.85 description: Matching content chunks from the document example: - content: >- Rate limit headers are included in every response. Clients should implement exponential backoff when receiving 429 responses. isRelevant: true position: 3 score: 0.85 createdAt: type: string description: Document creation date example: '1970-01-01T00:00:00.000Z' format: datetime documentId: type: string description: ID of the matching document example: doc_xyz789 metadata: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' description: Document metadata example: source: upload language: en score: type: number description: Relevance score of the match example: 0.95 maximum: 1 minimum: 0 summary: description: Document summary example: >- API rate limit policy: 100 req/min free, 1000 req/min pro. anyOf: - type: string - type: 'null' content: description: >- Full document content (only included when includeFullDocs=true) example: >- Our API rate limits are 100 req/min on free and 1000 on pro. Clients should use exponential backoff on 429s. anyOf: - type: string - type: 'null' title: anyOf: - type: string - type: 'null' description: Document title example: API Rate Limiting Policy updatedAt: type: string description: Document last update date example: '1970-01-01T00:00:00.000Z' format: datetime type: anyOf: - type: string - type: 'null' description: Document type example: web required: - chunks - createdAt - documentId - metadata - score - title - updatedAt - type timing: type: number total: type: number required: - results - timing - total description: Search results '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Invalid request parameters '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '402': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Search quota or credits exhausted '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Document not found '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error x-codeSamples: - lang: typescript label: TypeScript SDK source: |- import Supermemory from "supermemory"; const client = new Supermemory({ apiKey: process.env.SUPERMEMORY_API_KEY, }); // Document / SuperRAG search (chunk-level) const results = await client.search.documents({ q: "gift policy for VP promotions", containerTags: ["user_123"], limit: 5, }); for (const hit of results.results) { // document hits expose documentId + score (not memory-style id/similarity) console.log(hit.title ?? hit.documentId, hit.score); } - lang: python label: Python SDK source: |- from supermemory import Supermemory client = Supermemory() # uses SUPERMEMORY_API_KEY results = client.search.documents( q="gift policy for VP promotions", container_tags=["user_123"], limit=5, ) for hit in results.results: print(getattr(hit, "title", None) or hit.document_id, hit.score) - lang: bash label: cURL source: |- curl -X POST "https://api.supermemory.ai/v3/search" \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "q": "gift policy for VP promotions", "containerTags": ["user_123"], "limit": 5 }' components: schemas: QueryFilter: description: >- Root query object that must contain either an AND or OR array of filter expressions anyOf: - type: object properties: OR: type: array items: $ref: '#/components/schemas/LogicalExpression' description: Array of OR filter expressions required: - OR - type: object properties: AND: type: array items: $ref: '#/components/schemas/LogicalExpression' description: Array of AND filter expressions required: - AND ErrorResponse: type: object properties: error: type: string description: Error message example: Invalid request parameters details: type: string description: Additional error details example: Query must be at least 1 character long required: - error LogicalExpression: description: >- A single filter condition or a nested AND/OR expression. The API validates up to 5 levels of nesting. anyOf: - $ref: '#/components/schemas/FilterCondition' - type: object properties: OR: type: array items: $ref: '#/components/schemas/LogicalExpression' description: 'OR: Array of conditions or nested expressions' required: - OR - type: object properties: AND: type: array items: $ref: '#/components/schemas/LogicalExpression' description: 'AND: Array of conditions or nested expressions' required: - AND FilterCondition: type: object properties: filterType: default: metadata type: string enum: - metadata - numeric - array_contains - string_contains key: type: string negate: anyOf: - type: boolean - type: string enum: - 'true' - 'false' ignoreCase: anyOf: - type: boolean - type: string enum: - 'true' - 'false' numericOperator: default: '=' type: string enum: - '>' - < - '>=' - <= - '=' value: type: string required: - key - value description: >- A single filter condition based on metadata, numeric values, array contents, or string matching securitySchemes: bearerAuth: scheme: bearer type: http ````