# How to Use the OpenRAG API for Knowledge Filter Management: A Complete Guide

> Master OpenRAG API knowledge filter management with this guide. Learn to create, search, update, and delete reusable query bundles in OpenSearch for efficient data querying.

- Repository: [Langflow/openrag](https://github.com/langflow-ai/openrag)
- Tags: how-to-guide
- Published: 2026-03-13

---

**The OpenRAG API provides REST endpoints and a Python SDK to create, search, retrieve, update, and delete knowledge filters—reusable query bundles stored in OpenSearch that can be applied to indexed data.**

The `langflow-ai/openrag` repository implements a full-stack, REST-first interface for managing these filters programmatically. Whether you are building automated data pipelines or administrative dashboards, understanding the OpenRAG API for knowledge filter management enables you to control query access patterns across your OpenSearch indexes with precision.

## Understanding the Knowledge Filter Architecture

The system follows a layered architecture that separates routing, business logic, and client abstraction.

### FastAPI Route Layer

The public API surface is defined in [`src/api/v1/knowledge_filters.py`](https://github.com/langflow-ai/openrag/blob/main/src/api/v1/knowledge_filters.py). This module registers five primary endpoints: `POST /knowledge-filters`, `POST /knowledge-filters/search`, `GET /knowledge-filters/{id}`, `PUT /knowledge-filters/{id}`, and `DELETE /knowledge-filters/{id}`. Each endpoint injects the authenticated user via `get_api_key_user_async` and delegates processing to the core handler module.

### Core Handler Layer

Located in [`src/api/knowledge_filter.py`](https://github.com/langflow-ai/openrag/blob/main/src/api/knowledge_filter.py), the core handler implements the business logic for all CRUD operations. It normalizes the `queryData` payload to ensure required fields are present, generates UUIDs for new filters, and interacts with the `knowledge_filter_service` to persist documents in OpenSearch. Functions like `create_knowledge_filter`, `search_knowledge_filters`, and `update_knowledge_filter` handle error normalization and HTTP status code mapping.

### SDK Client Layer

The Python SDK wraps the HTTP interface in [`sdks/python/openrag_sdk/knowledge_filters.py`](https://github.com/langflow-ai/openrag/blob/main/sdks/python/openrag_sdk/knowledge_filters.py). The `KnowledgeFiltersClient` class provides async methods that serialize `query_data` correctly, parse JSON-stringified responses back into typed Pydantic models, and manage connection pooling. The corresponding models in [`sdks/python/openrag_sdk/models.py`](https://github.com/langflow-ai/openrag/blob/main/sdks/python/openrag_sdk/models.py) define shapes like `KnowledgeFilter` and `KnowledgeFilterQueryData`.

## Available API Endpoints for Knowledge Filter Management

The following REST endpoints are exposed by the OpenRAG API:

- **POST `/api/v1/knowledge-filters`** — Creates a new filter. Accepts `name`, `queryData`, and optional fields like `description`, `allowedUsers`, and `allowedGroups`. Implemented in [`src/api/v1/knowledge_filters.py`](https://github.com/langflow-ai/openrag/blob/main/src/api/v1/knowledge_filters.py).
- **POST `/api/v1/knowledge-filters/search`** — Searches existing filters by name, description, or query content. Accepts `query` and `limit` parameters.
- **GET `/api/v1/knowledge-filters/{filter_id}`** — Retrieves a specific filter by its UUID.
- **PUT `/api/v1/knowledge-filters/{filter_id}`** — Updates filter fields. Partial updates are supported.
- **DELETE `/api/v1/knowledge-filters/{filter_id}`** — Removes a filter permanently.

All endpoints delegate to the internal functions in [`src/api/knowledge_filter.py`](https://github.com/langflow-ai/openrag/blob/main/src/api/knowledge_filter.py) after authenticating the request via API key.

## Managing Knowledge Filters with the Python SDK

The `KnowledgeFiltersClient` provides a type-safe interface to the API endpoints. Below are practical examples for each operation.

### Initialize the Client

```python
from openrag_sdk.client import OpenRAGClient

client = OpenRAGClient(
    base_url="https://your-openrag-instance.com",
    api_key="YOUR_API_KEY",
)

kf = client.knowledge_filters

```

### Create a Knowledge Filter

The SDK serializes the `query_data` model and POSTs to the create endpoint. In [`src/api/knowledge_filter.py`](https://github.com/langflow-ai/openrag/blob/main/src/api/knowledge_filter.py), the `create_knowledge_filter` function normalizes the payload and generates a UUID.

```python
from openrag_sdk.models import CreateKnowledgeFilterOptions, KnowledgeFilterQueryData

options = CreateKnowledgeFilterOptions(
    name="Recent Articles",
    description="Filters documents from the last 30 days",
    query_data=KnowledgeFilterQueryData(
        query="*",
        filters={"data_sources": ["news"], "owners": ["*"]},
        limit=50,
        score_threshold=0.2,
        color="blue",
        icon="filter",
    ),
)

response = await kf.create(options)
print("Created filter ID:", response.id)

```

### Search for Filters

The `search` method sends a POST body containing `query` and `limit` to `/api/v1/knowledge-filters/search`, handled by `search_knowledge_filters` in the core handler.

```python
filters = await kf.search(query="Recent", limit=10)
for f in filters:
    print(f.id, f.name, f.description)

```

### Retrieve a Specific Filter

When fetching by ID, the SDK parses the JSON-stringified `query_data` returned by the API back into a `KnowledgeFilterQueryData` object using the internal `_parse_filter` helper (lines 4-20 of [`sdks/python/openrag_sdk/knowledge_filters.py`](https://github.com/langflow-ai/openrag/blob/main/sdks/python/openrag_sdk/knowledge_filters.py)).

```python
filter_id = "c5a1b2e3-4f6d-7a89-b0c1-d2e3f4567890"
my_filter = await kf.get(filter_id)
print(my_filter.query_data)   # Access the parsed KnowledgeFilterQueryData object

```

### Update an Existing Filter

Updates are processed by `update_knowledge_filter` in the core handler, which implements a delete-then-recreate flow to ensure data consistency.

```python
update_opts = {
    "description": "Updated description",
    "queryData": {
        "query": "updated*",
        "filters": {"data_sources": ["blog"]},
    },
}
success = await kf.update(filter_id, update_opts)
print("Update succeeded:", success)

```

### Delete a Filter

```python
deleted = await kf.delete(filter_id)
print("Deleted:", deleted)

```

## Summary

- The OpenRAG API for knowledge filter management exposes five REST endpoints defined in [`src/api/v1/knowledge_filters.py`](https://github.com/langflow-ai/openrag/blob/main/src/api/v1/knowledge_filters.py).
- The core business logic resides in [`src/api/knowledge_filter.py`](https://github.com/langflow-ai/openrag/blob/main/src/api/knowledge_filter.py), handling normalization, UUID generation, and OpenSearch persistence.
- The Python SDK in [`sdks/python/openrag_sdk/knowledge_filters.py`](https://github.com/langflow-ai/openrag/blob/main/sdks/python/openrag_sdk/knowledge_filters.py) provides async, type-safe methods for all CRUD operations.
- Authentication requires an API key processed through `get_api_key_user_async`.
- Filters are stored as JSON documents in OpenSearch with ACL support via `allowedUsers` and `allowedGroups`.

## Frequently Asked Questions

### What authentication method does the OpenRAG API use for knowledge filter operations?

The API uses API-key-based authentication. Each endpoint in [`src/api/v1/knowledge_filters.py`](https://github.com/langflow-ai/openrag/blob/main/src/api/v1/knowledge_filters.py) injects the user context via the `get_api_key_user_async` dependency, which validates the bearer token before delegating to the core handler functions.

### How does the SDK handle the query_data serialization?

The `KnowledgeFiltersClient` automatically JSON-encodes the `query_data` field when creating filters (lines 49-55 of [`sdks/python/openrag_sdk/knowledge_filters.py`](https://github.com/langflow-ai/openrag/blob/main/sdks/python/openrag_sdk/knowledge_filters.py)) and parses the JSON-stringified response back into `KnowledgeFilterQueryData` Pydantic models when retrieving filters, ensuring type safety throughout the request lifecycle.

### Can I perform partial updates on knowledge filters?

Yes. The `PUT /api/v1/knowledge-filters/{id}` endpoint accepts partial payloads. The `update_knowledge_filter` handler in [`src/api/knowledge_filter.py`](https://github.com/langflow-ai/openrag/blob/main/src/api/knowledge_filter.py) processes these updates using a delete-then-recreate pattern to maintain data integrity while allowing you to modify only specific fields like `description` or `queryData`.

### What database backend stores the knowledge filters?

Knowledge filters are persisted in **OpenSearch**. The `knowledge_filter_service` interacts with the search engine through helper functions in [`src/utils/opensearch_utils.py`](https://github.com/langflow-ai/openrag/blob/main/src/utils/opensearch_utils.py), storing filters as documents with generated UUIDs and supporting full-text search across the `name`, `description`, and `queryData` fields.