> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useskald.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filters

> Advanced filtering for search, chat, and generate endpoints

## 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:

```json theme={null}
{
    "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:**

```json theme={null}
{
    "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:**

```json theme={null}
{
    "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:**

```json theme={null}
{
    "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:**

```json theme={null}
{
    "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:**

```json theme={null}
{
    "field": "source",
    "operator": "in",
    "value": ["notion", "confluence", "docs"],
    "filter_type": "native_field"
}
```

**Tags Example (always requires array):**

```json theme={null}
{
    "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:**

```json theme={null}
{
    "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:

```json theme={null}
{
    "field": "source",
    "operator": "in",
    "value": ["notion", "confluence"],
    "filter_type": "native_field"
}
```

### Filter by Tags

Include memos with specific tags:

```json theme={null}
{
    "field": "tags",
    "operator": "in",
    "value": ["meeting", "important"],
    "filter_type": "native_field"
}
```

Exclude memos with specific tags:

```json theme={null}
{
    "field": "tags",
    "operator": "not_in",
    "value": ["archived", "draft"],
    "filter_type": "native_field"
}
```

### Filter by Custom Metadata

Filter by any custom metadata field:

```json theme={null}
{
    "field": "department",
    "operator": "eq",
    "value": "engineering",
    "filter_type": "custom_metadata"
}
```

### Partial String Match

Find memos with titles containing specific text:

```json theme={null}
{
    "field": "title",
    "operator": "contains",
    "value": "roadmap",
    "filter_type": "native_field"
}
```

### Multiple Conditions

Combine filters for precise results:

```json theme={null}
{
    "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):**

```json theme={null}
{
    "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:

```json theme={null}
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](/docs/api-reference/search) for details.

### Chat Endpoint

Filters control which memos are used as context for chat responses:

```json theme={null}
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](/docs/api-reference/chat) for details.

### Generate Endpoint

Filters determine which memos provide context for document generation:

```json theme={null}
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](/docs/api-reference/generate-doc) 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`