Skip to main content

​
Overview

Filters allow you to narrow down results and context in the /api/v1/search, /api/v1/chat, and /api/v1/generate endpoints. You can filter by native memo fields or custom metadata fields using various operators. Filters are applied using AND logic - all filters must match for a memo to be included.

​
Filter Structure

Each filter object has the following structure: 
{
    "field": "field_name",
    "operator": "operator_name",
    "value": "value or [array]",
    "filter_type": "native_field | custom_metadata"
}
Required Fields:
  • field (string): The field name to filter on
  • operator (string): The comparison operator to use
  • value (string | array): The value to compare against (arrays required for in and not_in)
  • filter_type (string): Either native_field or custom_metadata

​
Filter Types

​
Native Fields

Filter on built-in memo properties using filter_type: "native_field":
  • title - Memo title
  • source - Source system name
  • client_reference_id - External reference ID
  • tags - Memo tags (must use in or not_in operator with array value)
Example: 
{
    "field": "source",
    "operator": "eq",
    "value": "notion",
    "filter_type": "native_field"
}

​
Custom Metadata

Filter on any field from a memo’s metadata JSON object using filter_type: "custom_metadata": Example: 
{
    "field": "category",
    "operator": "contains",
    "value": "tutorial",
    "filter_type": "custom_metadata"
}
This filters memos where metadata.category contains “tutorial”.

​
Operators

​
Equality Operators

  • eq - Equals (exact match)
  • neq - Not equals
Example: 
{
    "field": "source",
    "operator": "eq",
    "value": "confluence",
    "filter_type": "native_field"
}

​
String Operators

  • contains - Contains substring (case-insensitive)
  • startswith - Starts with (case-sensitive)
  • endswith - Ends with (case-sensitive)
Example: 
{
    "field": "title",
    "operator": "contains",
    "value": "meeting",
    "filter_type": "native_field"
}

​
Array Operators

  • in - Value is in array (requires array value)
  • not_in - Value is not in array (requires array value)
Example: 
{
    "field": "source",
    "operator": "in",
    "value": ["notion", "confluence", "docs"],
    "filter_type": "native_field"
}
Tags Example (always requires array): 
{
    "field": "tags",
    "operator": "in",
    "value": ["meeting", "q1"],
    "filter_type": "native_field"
}

​
Combining Filters

Multiple filters use AND logic - all filters must match for a memo to be included in results. Example: 
{
    "query": "python tutorial",
    "search_method": "chunk_vector_search",
    "filters": [
        {
            "field": "source",
            "operator": "eq",
            "value": "docs.python.org",
            "filter_type": "native_field"
        },
        {
            "field": "level",
            "operator": "eq",
            "value": "beginner",
            "filter_type": "custom_metadata"
        },
        {
            "field": "tags",
            "operator": "in",
            "value": ["tutorial"],
            "filter_type": "native_field"
        }
    ]
}
This returns only memos where:
  • Title/content matches “python tutorial” AND
  • Source equals “docs.python.org” AND
  • Metadata field “level” equals “beginner” AND
  • Has at least one tag in [“tutorial”]

​
Common Filter Patterns

​
Filter by Source

Limit results to specific source systems: 
{
    "field": "source",
    "operator": "in",
    "value": ["notion", "confluence"],
    "filter_type": "native_field"
}

​
Filter by Tags

Include memos with specific tags: 
{
    "field": "tags",
    "operator": "in",
    "value": ["meeting", "important"],
    "filter_type": "native_field"
}
Exclude memos with specific tags: 
{
    "field": "tags",
    "operator": "not_in",
    "value": ["archived", "draft"],
    "filter_type": "native_field"
}

​
Filter by Custom Metadata

Filter by any custom metadata field: 
{
    "field": "department",
    "operator": "eq",
    "value": "engineering",
    "filter_type": "custom_metadata"
}

​
Partial String Match

Find memos with titles containing specific text: 
{
    "field": "title",
    "operator": "contains",
    "value": "roadmap",
    "filter_type": "native_field"
}

​
Multiple Conditions

Combine filters for precise results: 
{
    "filters": [
        {
            "field": "source",
            "operator": "eq",
            "value": "product-docs",
            "filter_type": "native_field"
        },
        {
            "field": "status",
            "operator": "eq",
            "value": "published",
            "filter_type": "custom_metadata"
        },
        {
            "field": "tags",
            "operator": "in",
            "value": ["feature", "specification"],
            "filter_type": "native_field"
        }
    ]
}

​
Error Responses

Invalid filter structure (400): 
{
    "error": "Invalid filter: <specific error message>"
}
Common filter errors:
  • Missing required fields (field, operator, value, filter_type)
  • Invalid operator (must be one of: eq, neq, contains, startswith, endswith, in, not_in)
  • Invalid filter_type (must be native_field or custom_metadata)
  • Invalid native field (must be title, source, client_reference_id, or tags)
  • Tags filter must use in or not_in operator with array value
  • in and not_in operators require array value

​
Using Filters Across Endpoints

​
Search Endpoint

Filters narrow down search results: 
POST /api/v1/search
{
    "query": "api documentation",
    "search_method": "chunk_vector_search",
    "filters": [
        {
            "field": "source",
            "operator": "eq",
            "value": "technical-docs",
            "filter_type": "native_field"
        }
    ]
}
See Search API for details.

​
Chat Endpoint

Filters control which memos are used as context for chat responses: 
POST /api/v1/chat
{
    "query": "What are our Q1 goals?",
    "filters": [
        {
            "field": "tags",
            "operator": "in",
            "value": ["q1", "goals"],
            "filter_type": "native_field"
        }
    ]
}
See Chat API for details.

​
Generate Endpoint

Filters determine which memos provide context for document generation: 
POST /api/v1/generate
{
    "prompt": "Create a technical overview document",
    "filters": [
        {
            "field": "document_type",
            "operator": "eq",
            "value": "specification",
            "filter_type": "custom_metadata"
        }
    ]
}
See Generate API for details.

​
Tips and Best Practices

  1. Use specific filters - Narrow your scope to improve relevance and reduce noise
  2. Combine native and custom fields - Mix source/tags filters with metadata filters for precision
  3. Test filters incrementally - Add filters one at a time to understand their impact
  4. Empty filters array - Equivalent to no filters, searches entire project
  5. Case sensitivity - contains is case-insensitive, but startswith and endswith are case-sensitive
  6. Tags always use arrays - Even for single tag, use ["tag"] format with in or not_in
⌘I