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

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. 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, 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. 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 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.
• 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 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

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, the create_knowledge_filter function normalizes the payload and generates a UUID.

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.

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).

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.

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

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.
• The core business logic resides in src/api/knowledge_filter.py, handling normalization, UUID generation, and OpenSearch persistence.
• The Python SDK in 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 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) 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 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, storing filters as documents with generated UUIDs and supporting full-text search across the name, description, and queryData fields.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}