Filters

Complete reference for filters available in the SnackPrompt AI Engine API.

Overview

Filters are used to restrict the scope of searches, chats, and deletions. They are passed in the filters object of the request body.

{
  "query": "your search",
  "filters": {
    "tenant_id": "required",
    "elemental_id": "optional",
    ...
  }
}

Filter List

Filter	Type	Required	Description
tenant_id	string	YES	Multi-tenant isolation
elemental_id	string	No	Elemental ID
user_id	string	No	User ID
tag_ids	string[]	No	Tag IDs
tag_names	string[]	No	Tag names
source	string	No	Source type
type_name	string	No	Elemental type
category_name	string	No	Category

---

Details

tenant_id

Tenant identifier for data isolation. Required in all operations.

Property	Value
Type	string
Required	Yes
Example	"tenant-abc123"

Behavior:

• Ensures complete isolation between tenants

• A tenant cannot access another tenant's data

• Optimized in Qdrant with is_tenant=True

Example:

{
  "filters": {
    "tenant_id": "tenant-abc123"
  }
}

Error if missing:

{
  "detail": "tenant_id is required in filters"
}

---

elemental_id

Filters by a specific elemental (table/document).

Property	Value
Type	string
Required	No
Example	"elem-xyz789"

Example:

{
  "filters": {
    "tenant_id": "tenant-abc123",
    "elemental_id": "elem-xyz789"
  }
}

---

user_id

Filters by data from a specific user (within the tenant).

Property	Value
Type	string
Required	No
Example	"user-123"

Example:

{
  "filters": {
    "tenant_id": "tenant-abc123",
    "user_id": "user-123"
  }
}

---

tag_ids

Filters by tag IDs. OR logic (any of the tags).

Property	Value
Type	string[]
Required	No
Logic	OR
Example	["tag-1", "tag-2"]

Example:

{
  "filters": {
    "tenant_id": "tenant-abc123",
    "tag_ids": ["tag-marketing", "tag-sales"]
  }
}

Returns documents that have the tag "tag-marketing" OR "tag-sales".

---

tag_names

Filters by tag names. OR logic (any of the tags).

Property	Value
Type	string[]
Required	No
Logic	OR
Example	["Marketing", "Sales"]

Example:

{
  "filters": {
    "tenant_id": "tenant-abc123",
    "tag_names": ["Marketing", "Sales"]
  }
}

Returns documents that have the tag "Marketing" OR "Sales".

---

source

Filters by data source type.

Property	Value
Type	string
Required	No
Values	elemental, document, file

Possible values:

Value	Description
elemental	SnackPrompt tables
document	Documents
file	Uploaded files

Example:

{
  "filters": {
    "tenant_id": "tenant-abc123",
    "source": "document"
  }
}

---

type_name

Filters by elemental type.

Property	Value
Type	string
Required	No
Values	Table, Document, etc.

Example:

{
  "filters": {
    "tenant_id": "tenant-abc123",
    "type_name": "Table"
  }
}

---

category_name

Filters by elemental category.

Property	Value
Type	string
Required	No
Example	"Finance"

Example:

{
  "filters": {
    "tenant_id": "tenant-abc123",
    "category_name": "Finance"
  }
}

---

Combining Filters

Combination Logic

• Between different filters: AND

• Within arrays (tags): OR

Example:

{
  "filters": {
    "tenant_id": "tenant-abc123",
    "source": "elemental",
    "tag_names": ["Marketing", "Sales"]
  }
}

This means:

• tenant_id = "tenant-abc123" AND

• source = "elemental" AND

• (tag_names contains "Marketing" OR "Sales")

---

Usage by Endpoint

Endpoint	Supported Filters
/v1/kb/search	All
/v1/kb/chat	All
/v1/kb/chat/stream	All
/v1/kb/delete	tenant_id, elemental_id, user_id, tag_ids, tag_names, source

---

Practical Examples

Search in a Specific Document

{
  "query": "delivery time",
  "filters": {
    "tenant_id": "tenant-123",
    "elemental_id": "doc-logistics-001"
  }
}

Search by Multiple Tags

{
  "query": "benefits",
  "filters": {
    "tenant_id": "tenant-123",
    "tag_names": ["HR", "Benefits", "Policies"]
  }
}

Search Only in Tables

{
  "query": "products",
  "filters": {
    "tenant_id": "tenant-123",
    "source": "elemental",
    "type_name": "Table"
  }
}

Delete User Data

{
  "filters": {
    "tenant_id": "tenant-123",
    "user_id": "user-456"
  }
}