Filters - Skald Docs

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

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

​Overview

​Filter Structure

​Filter Types

​Native Fields

​Custom Metadata

​Operators

​Equality Operators

​String Operators

​Array Operators

​Combining Filters

​Common Filter Patterns

​Filter by Source

​Filter by Tags

​Filter by Custom Metadata

​Partial String Match

​Multiple Conditions

​Error Responses

​Using Filters Across Endpoints

​Search Endpoint

​Chat Endpoint

​Generate Endpoint

​Tips and Best Practices

Overview

Filter Structure

Filter Types

Native Fields

Custom Metadata

Operators

Equality Operators

String Operators

Array Operators

Combining Filters

Common Filter Patterns

Filter by Source

Filter by Tags

Filter by Custom Metadata

Partial String Match

Multiple Conditions

Error Responses

Using Filters Across Endpoints

Search Endpoint

Chat Endpoint

Generate Endpoint

Tips and Best Practices