How to Filter by Tags

Learn how to use tags to restrict searches and chats to specific documents.

Problem

You have many documents in the Knowledge Base and want to search only in a specific subset.

Solution

Use the tag_names or tag_ids filters in your requests.

Filter by Tag Name

curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "vacation policy",
    "filters": {
      "tenant_id": "your-tenant-id",
      "tag_names": ["HR", "Policies"]
    },
    "limit": 5
  }'

Filter by Tag ID

curl -X POST https://api-integrations.snackprompt.com/v1/kb/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": "vacation policy",
    "filters": {
      "tenant_id": "your-tenant-id",
      "tag_ids": ["tag-hr-001", "tag-policies-002"]
    },
    "limit": 5
  }'

Understanding the Logic

Multiple Tags = OR

When you provide multiple tags, the API uses OR logic:

{
  "tag_names": ["Marketing", "Sales"]
}

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

Tags + Other Filters = AND

When combining tags with other filters, the logic is AND:

{
  "filters": {
    "tenant_id": "...",
    "source": "document",
    "tag_names": ["Marketing", "Sales"]
  }
}

Returns:

• source = "document" AND

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

Use Cases

Search in a Specific Category

{
  "query": "how to request reimbursement",
  "filters": {
    "tenant_id": "...",
    "tag_names": ["Finance"]
  }
}

Search in Multiple Departments

{
  "query": "hiring process",
  "filters": {
    "tenant_id": "...",
    "tag_names": ["HR", "Legal", "Compliance"]
  }
}

Directed Chat

Use tags in chat to direct the context:

{
  "query": "what are the health insurance benefits?",
  "filters": {
    "tenant_id": "...",
    "tag_names": ["Benefits", "Health"]
  }
}

The AI will only use documents with these tags as context.

Where Do Tags Come From?

Tags are defined in the SnackPrompt platform and inherited during ingestion:

Document (document tags)
    └── Column (column tags)
            └── Item (item tags)

The final item will have all tags combined (no duplicates).

Tips

1. Use tag_names for Readability

// More readable
"tag_names": ["Marketing", "Sales"]

// Works, but less readable
"tag_ids": ["tag-abc123", "tag-def456"]

2. Don't Overdo the Filters

// Too restrictive - may not find anything
- "tag_names": ["Marketing", "Q4", "2023", "Brazil", "Digital"]

// Better - more flexible
+ "tag_names": ["Marketing", "2023"]

3. Test First with Search

Before using tags in chat, test with search to verify it finds results:

# 1. Test the search
curl -X POST .../v1/kb/search \
  -d '{"query": "...", "filters": {"tenant_id": "...", "tag_names": ["Tag"]}, "limit": 1}'

# 2. If it finds results, use in chat
curl -X POST .../v1/kb/chat \
  -d '{"query": "...", "filters": {"tenant_id": "...", "tag_names": ["Tag"]}}'

Related

• Filter Reference

• Semantic Search

• Chat with your Data