OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
feat: public file listing on v2 endpoint with SDK and MCP support (#2251)
Jason Dong85aeec8475d4
diff --git a/frontend/app/api/queries/useListFiles.ts b/frontend/app/api/queries/useListFiles.tsindex 7a28571c6..c9513c591 100644--- a/frontend/app/api/queries/useListFiles.ts+++ b/frontend/app/api/queries/useListFiles.ts@@ -47,7 +47,7 @@ export const useListFiles = (if (params.afterKey)searchParams.set("after_key", JSON.stringify(params.afterKey));- const url = `/api/v2/files?${searchParams.toString()}`; //v2 endpoint+ const url = `/api/files?${searchParams.toString()}`; //internal (cookie auth)const response = await fetch(url);diff --git a/sdks/python/README.md b/sdks/python/README.mdindex a818f4f07..7bb712ddd 100644--- a/sdks/python/README.md+++ b/sdks/python/README.md@@ -215,6 +215,20 @@ results = await client.search.query("quarterly report", filter_id=filter_id)response = await client.chat.create(message="Summarise Q3", filter_id=filter_id)```+For a one-shot listing without managing a cursor, `client.documents.get_all_files()`+returns all files in a single call — no parameters needed.++> **Note:** `get_all_files()` returns at most **500 files**. If your knowledge+> base contains more than 500 files, use `list_files()` with cursor pagination+> (`after_key`) to page through the full set.++```python+# Get all files in a single call (no cursor to track)+page = await client.documents.get_all_files()+for f in page.files:+ print(f.filename)+```+## Settings```pythondiff --git a/sdks/python/openrag_sdk/__init__.py b/sdks/python/openrag_sdk/__init__.pyindex 86921232c..e05df69d1 100644--- a/sdks/python/openrag_sdk/__init__.py+++ b/sdks/python/openrag_sdk/__init__.py@@ -50,6 +50,7 @@ from .models import (DeleteKnowledgeFilterResponse,DoneEvent,FileRecord,+ GetAllFilesResponse,GetKnowledgeFilterResponse,IngestResponse,KnowledgeFilter,@@ -87,6 +88,7 @@ __all__ = ["ServerError",# File models"FileRecord",+ "GetAllFilesResponse","ListFilesResponse","PrincipalLabel",# Modelsdiff --git a/sdks/python/openrag_sdk/documents.py b/sdks/python/openrag_sdk/documents.pyindex 964e39f5b..d67ea4633 100644--- a/sdks/python/openrag_sdk/documents.py+++ b/sdks/python/openrag_sdk/documents.py@@ -8,6 +8,7 @@ from .exceptions import NotFoundErrorfrom .models import (DeleteDocumentResponse,FileRecord,+ GetAllFilesResponse,IngestResponse,IngestTaskStatus,ListFilesResponse,@@ -197,7 +198,7 @@ class DocumentsClient:after_key: str | None = None,) -> ListFilesResponse:"""- List ingested files in the knowledge base.+ List ingested files with cursor-based composite-aggregation pagination (v2).Args:page: Page number (display only; use after_key for cursor navigation).@@ -213,7 +214,8 @@ class DocumentsClient:after_key field. Pass to fetch the next page.Returns:- ListFilesResponse with files list, total count, and next after_key.+ ListFilesResponse with files list, approximate total, and next+ after_key cursor."""params: dict[str, str | int] = {"page": page,@@ -234,7 +236,7 @@ class DocumentsClient:response = await self._client._request("GET",- "/api/v1/files",+ "/api/v2/files",params=params,)data = response.json()@@ -246,3 +248,29 @@ class DocumentsClient:page_size=data.get("page_size", page_size),after_key=data.get("after_key"),)++ async def get_all_files(self) -> GetAllFilesResponse:+ """+ Return all ingested files (v1).++ No parameters — just returns everything in the knowledge base.++ Note:+ Returns at most 500 files. If your knowledge base contains more+ than 500 files, use ``list_files()`` with cursor pagination+ (``after_key``) to page through the full set.++ Returns:+ GetAllFilesResponse with files list, total count, page, and page_size.+ """+ response = await self._client._request(+ "GET",+ "/api/v1/files/get_all",+ )+ data = response.json()+ return GetAllFilesResponse(+ files=[FileRecord(**f) for f in data.get("files", [])],+ total=data.get("total", 0),+ page=data.get("page", 1),+ page_size=data.get("page_size", 500),+ )diff --git a/sdks/python/openrag_sdk/models.py b/sdks/python/openrag_sdk/models.pyindex d7915267d..55349bd16 100644--- a/sdks/python/openrag_sdk/models.py+++ b/sdks/python/openrag_sdk/models.py@@ -318,8 +318,17 @@ class FileRecord(BaseModel):allowed_principal_labels: list[PrincipalLabel] = Field(default_factory=list)+class GetAllFilesResponse(BaseModel):+ """Response from GET /v1/files/get_all — offset pagination, no cursor."""++ files: list[FileRecord]+ total: int+ page: int+ page_size: int++class ListFilesResponse(BaseModel):- """Response from the list-files endpoint."""+ """Response from GET /v2/files — cursor-based composite-aggregation pagination."""files: list[FileRecord]total: intdiff --git a/sdks/typescript/README.md b/sdks/typescript/README.mdindex 6645f1b13..3407919b7 100644--- a/sdks/typescript/README.md+++ b/sdks/typescript/README.md@@ -241,6 +241,19 @@ const results = await client.search.query("quarterly report", { filterId });const response = await client.chat.create({ message: "Summarise Q3", filterId });```+For a one-shot listing without managing a cursor, `client.documents.getAllFiles()`+returns all files in a single call — no parameters needed.++> **Note:** `getAllFiles()` returns at most **500 files**. If your knowledge+> base contains more than 500 files, use `listFiles()` with cursor pagination+> (`after_key`) to page through the full set.++```typescript+// Get all files in a single call (no cursor to track)+const page = await client.documents.getAllFiles();+for (const f of page.files) console.log(f.filename);+```+## Settings```typescriptdiff --git a/sdks/typescript/src/documents.ts b/sdks/typescript/src/documents.tsindex 9cf3fb211..acb9c16e5 100644--- a/sdks/typescript/src/documents.ts+++ b/sdks/typescript/src/documents.ts@@ -7,6 +7,7 @@ import type {DeleteDocumentOptions,DeleteDocumentResponse,FileRecord,+ GetAllFilesResponse,IngestResponse,IngestTaskStatus,ListFilesOptions,@@ -148,10 +149,10 @@ export class DocumentsClient {}/**- * List ingested files in the knowledge base.+ * List ingested files with cursor-based composite-aggregation pagination (v2).*- * @param options - Filtering, sorting, and pagination options.- * @returns ListFilesResponse with files list, total count, and next after_key.+ * @param options - Filtering, sorting, and cursor pagination options.+ * @returns ListFilesResponse with files list, approximate total, and next after_key cursor.*/async listFiles(options: ListFilesOptions = {}): Promise<ListFilesResponse> {const params = new URLSearchParams();@@ -166,7 +167,7 @@ export class DocumentsClient {if (options.after_key !== undefined) params.set("after_key", options.after_key);const qs = params.toString();- const path = qs ? `/api/v1/files?${qs}` : "/api/v1/files";+ const path = qs ? `/api/v2/files?${qs}` : "/api/v2/files";const response = await this.client._request("GET", path);const data = await response.json();@@ -180,6 +181,25 @@ export class DocumentsClient {};}+ /**+ * Return all ingested files (v1).+ *+ * No parameters — just returns everything in the knowledge base.+ *+ * @returns GetAllFilesResponse with files list and total count.+ */+ async getAllFiles(): Promise<GetAllFilesResponse> {+ const response = await this.client._request("GET", "/api/v1/files/get_all");+ const data = await response.json();++ return {+ files: (data.files ?? []) as FileRecord[],+ total: data.total ?? 0,+ page: data.page ?? 1,+ page_size: data.page_size ?? 100,+ };+ }+/*** Delete document(s) from the knowledge base.*diff --git a/sdks/typescript/src/index.ts b/sdks/typescript/src/index.tsindex 0b438b360..3490f5437 100644--- a/sdks/typescript/src/index.ts+++ b/sdks/typescript/src/index.ts@@ -67,6 +67,7 @@ export {DeleteDocumentResponse,PrincipalLabel,FileRecord,+ GetAllFilesResponse,ListFilesResponse,ListFilesOptions,// Conversation typesdiff --git a/sdks/typescript/src/types.ts b/sdks/typescript/src/types.tsindex 941ab9b55..cc91f7c5b 100644--- a/sdks/typescript/src/types.ts+++ b/sdks/typescript/src/types.ts@@ -118,7 +118,15 @@ export interface FileRecord {allowed_principal_labels: PrincipalLabel[];}-//Response from the list-files endpoint+/** Response from GET /v1/files/get_all (original v1 offset pagination) */+export interface GetAllFilesResponse {+ files: FileRecord[];+ total: number;+ page: number;+ page_size: number;+}++/** Response from GET /v2/files (cursor-based composite-aggregation pagination) */export interface ListFilesResponse {files: FileRecord[];total: number;@@ -128,25 +136,16 @@ export interface ListFilesResponse {after_key: Record<string, unknown> | null;}-/** Options for listing files. */+/** Options for GET /v2/files (cursor-based pagination). */export interface ListFilesOptions {- /** Page number (display only; use after_key for cursor navigation). Default: 1. */page?: number;- /** Files per page (1–500). Default: 25. */page_size?: number;- /** Sort field: filename | file_size | mimetype | indexed_time | connector_type | chunk_count | owner. */sort_by?: string;- /** Sort direction. Default: "asc". */sort_order?: "asc" | "desc";- /** Filter by connector type. */connector_type?: string;- /** Filter by MIME type. */mimetype?: string;- /** Filter by owner user ID. */owner?: string;- /** Substring/prefix filename search. */search?: string;- /** JSON-encoded composite cursor from a previous response's after_key. */after_key?: string;}diff --git a/src/api/files.py b/src/api/files.pyindex 889d1e8de..cc4b16c9c 100644--- a/src/api/files.py+++ b/src/api/files.py@@ -1,39 +1,60 @@"""-File listing and search API endpoints.+Internal file listing and search handlers (cookie auth).++Serves the unversioned internal/UI routes GET /files and GET /files/search+using FileServiceV2 (composite-aggregation cursor pagination). Pass `after_key`+(JSON-encoded) to advance pages.-Provides server-side file-level views over the chunk-based OpenSearch index.-Uses terms aggregation with in-memory sort/slice (v1)."""-from fastapi import Depends, Query+import json++from fastapi import Depends, HTTPException, Queryfrom fastapi.responses import JSONResponse-from dependencies import get_current_user, get_session_manager+from dependencies import get_current_user, get_file_service_v2from session_manager import Userfrom utils.logging_config import get_loggerlogger = get_logger(__name__)-def _get_file_service(session_manager=Depends(get_session_manager)):- from services.file_service import FileService+def _parse_after_key(after_key: str | None) -> dict | None:+ """Parse a JSON-encoded composite cursor.- return FileService(session_manager=session_manager)+ Returns None when after_key is absent.+ Raises HTTPException 400 when the value is present but is not valid JSON+ or does not decode to a dict (e.g. a bare string or number is invalid).+ """+ if not after_key:+ return None+ try:+ parsed = json.loads(after_key)+ except (json.JSONDecodeError, ValueError) as err:+ raise HTTPException(status_code=400, detail="after_key is not valid JSON") from err+ if not isinstance(parsed, dict):+ raise HTTPException(status_code=400, detail="after_key must be a JSON object")+ return parsedasync def list_files(- page: int = Query(1, ge=1, description="Page number"),- page_size: int = Query(25, ge=1, le=100, description="Items per page"),+ page: int = Query(+ 1, ge=1, description="Page number (for display only; navigation uses after_key cursor)"+ ),+ page_size: int = Query(25, ge=1, le=500, description="Items per page"),sort_by: str = Query("filename", description="Sort field"),sort_order: str = Query("asc", pattern="^(asc|desc)$", description="Sort order"),connector_type: str | None = Query(None, description="Filter by connector type"),mimetype: str | None = Query(None, description="Filter by MIME type"),owner: str | None = Query(None, description="Filter by owner"),search: str | None = Query(None, description="Search filename"),- file_service=Depends(_get_file_service),+ after_key: str | None = Query(None, description="Composite pagination cursor (JSON-encoded)"),+ file_service=Depends(get_file_service_v2),user: User = Depends(get_current_user),):- """List ingested files with pagination, filtering, and sorting."""+ """List ingested files with composite-aggregation pagination, filtering, and sorting."""+ parsed_after_key = _parse_after_key(after_key)+try:result = await file_service.list_files(user_id=user.user_id,@@ -46,16 +67,17 @@ async def list_files(mimetype=mimetype,owner=owner,search=search,+ after_key=parsed_after_key,)return JSONResponse(result)except Exception as e:- logger.error("Failed to list files", error=str(e))+ logger.error("Failed to list files (v2)", error=str(e))from utils.opensearch_utils import AUTH_ERROR_MESSAGE, is_opensearch_auth_errorif is_opensearch_auth_error(e):return JSONResponse({"error": AUTH_ERROR_MESSAGE}, status_code=401)return JSONResponse(- {"error": "Failed to list files", "detail": str(e)},+ {"error": "Failed to list files"},status_code=500,)@@ -63,14 +85,17 @@ async def list_files(async def search_files(q: str = Query(..., min_length=1, description="Search query"),page: int = Query(1, ge=1, description="Page number"),- page_size: int = Query(25, ge=1, le=100, description="Items per page"),+ page_size: int = Query(25, ge=1, le=500, description="Items per page"),connector_type: str | None = Query(None, description="Filter by connector type"),mimetype: str | None = Query(None, description="Filter by MIME type"),owner: str | None = Query(None, description="Filter by owner"),- file_service=Depends(_get_file_service),+ after_key: str | None = Query(None, description="Composite pagination cursor (JSON-encoded)"),+ file_service=Depends(get_file_service_v2),user: User = Depends(get_current_user),):- """Search files by name with fuzzy/partial matching."""+ """Search files by name with fuzzy/partial matching (composite pagination)."""+ parsed_after_key = _parse_after_key(after_key)+try:result = await file_service.search_files(user_id=user.user_id,@@ -81,15 +106,16 @@ async def search_files(connector_type=connector_type,mimetype=mimetype,owner=owner,+ after_key=parsed_after_key,)return JSONResponse(result)except Exception as e:- logger.error("Failed to search files", error=str(e))+ logger.error("Failed to search files (v2)", error=str(e))from utils.opensearch_utils import AUTH_ERROR_MESSAGE, is_opensearch_auth_errorif is_opensearch_auth_error(e):return JSONResponse({"error": AUTH_ERROR_MESSAGE}, status_code=401)return JSONResponse(- {"error": "Failed to search files", "detail": str(e)},+ {"error": "Failed to search files"},status_code=500,)diff --git a/src/api/v1/files.py b/src/api/v1/files.pyindex cdce9382d..3ba2d8b6e 100644--- a/src/api/v1/files.py+++ b/src/api/v1/files.py@@ -1,80 +1,42 @@"""Public API v1 Files endpoints.-Provides file listing and search over the ingested knowledge base.-Uses API key authentication — delegates to the api/v2/files.py handlers-but overrides the user dependency to use API keys.+Provides a simple file listing over the ingested knowledge base+(GET /v1/files/get_all). Uses API-key authentication and calls FileService+(v1, offset pagination) directly."""-from fastapi import Depends, Query+from fastapi import Depends+from fastapi.responses import JSONResponse-from api.v2 import files as files_v2-from dependencies import get_file_service_v2, require_api_key_permission+from dependencies import get_file_service, require_api_key_permissionfrom session_manager import Userfrom utils.logging_config import get_loggerlogger = get_logger(__name__)-async def list_files(- page: int = Query(- 1, ge=1, description="Page number (for display only; navigation uses after_key cursor)"- ),- page_size: int = Query(25, ge=1, le=500, description="Items per page"),- sort_by: str = Query("filename", description="Sort field"),- sort_order: str = Query("asc", pattern="^(asc|desc)$", description="Sort order"),- connector_type: str | None = Query(None, description="Filter by connector type"),- mimetype: str | None = Query(None, description="Filter by MIME type"),- owner: str | None = Query(None, description="Filter by owner"),- search: str | None = Query(None, description="Search filename"),- after_key: str | None = Query(None, description="Composite pagination cursor (JSON-encoded)"),- file_service=Depends(get_file_service_v2),+async def get_all_files(+ file_service=Depends(get_file_service),user: User = Depends(require_api_key_permission("knowledge:read:own")),):"""- List all ingested files.+ Return all ingested files.- GET /v1/files+ GET /v1/files/get_all"""- return await files_v2.list_files(- page=page,- page_size=page_size,- sort_by=sort_by,- sort_order=sort_order,- connector_type=connector_type,- mimetype=mimetype,- owner=owner,- search=search,- after_key=after_key,- file_service=file_service,- user=user,- )---async def search_files(- q: str = Query(..., min_length=1, description="Search query"),- page: int = Query(1, ge=1, description="Page number"),- page_size: int = Query(25, ge=1, le=500, description="Items per page"),- connector_type: str | None = Query(None, description="Filter by connector type"),- mimetype: str | None = Query(None, description="Filter by MIME type"),- owner: str | None = Query(None, description="Filter by owner"),- after_key: str | None = Query(None, description="Composite pagination cursor (JSON-encoded)"),- file_service=Depends(get_file_service_v2),- user: User = Depends(require_api_key_permission("knowledge:read:own")),-):- """- Search ingested files by name with fuzzy/partial matching.-- GET /v1/files/search- """- return await files_v2.search_files(- q=q,- page=page,- page_size=page_size,- connector_type=connector_type,- mimetype=mimetype,- owner=owner,- after_key=after_key,- file_service=file_service,- user=user,- )+ try:+ result = await file_service.list_files(+ user_id=user.user_id,+ jwt_token=user.jwt_token,+ page=1,+ page_size=500,+ )+ return JSONResponse(result)+ except Exception as e:+ logger.error("Failed to get all files (v1)", error=str(e))+ from utils.opensearch_utils import AUTH_ERROR_MESSAGE, is_opensearch_auth_error++ if is_opensearch_auth_error(e):+ return JSONResponse({"error": AUTH_ERROR_MESSAGE}, status_code=401)+ return JSONResponse({"error": "Failed to get files"}, status_code=500)diff --git a/src/api/v2/files.py b/src/api/v2/files.pyindex b6fc1b1f3..1691ffab9 100644--- a/src/api/v2/files.py+++ b/src/api/v2/files.py@@ -1,38 +1,18 @@"""-File listing and search API endpoints — v2 (composite aggregation).+Public API v2 Files endpoints (API-key auth).-Uses composite aggregation for true O(page_size) server-side pagination.-Cursor-based: pass `after_key` (JSON-encoded) to advance pages.+Cursor-paginated file listing/search over the ingested knowledge base, served+at GET /v2/files and GET /v2/files/search. These handlers delegate to the+internal handlers in api/files.py, overriding only the auth dependency to use+an API key instead of the session cookie."""-import json+from fastapi import Depends, Query-from fastapi import Depends, HTTPException, Query-from fastapi.responses import JSONResponse--from dependencies import get_current_user, get_file_service_v2+from api.files import list_files as _internal_list_files+from api.files import search_files as _internal_search_files+from dependencies import get_file_service_v2, require_api_key_permissionfrom session_manager import User-from utils.logging_config import get_logger--logger = get_logger(__name__)---def _parse_after_key(after_key: str | None) -> dict | None:- """Parse a JSON-encoded composite cursor.-- Returns None when after_key is absent.- Raises HTTPException 400 when the value is present but is not valid JSON- or does not decode to a dict (e.g. a bare string or number is invalid).- """- if not after_key:- return None- try:- parsed = json.loads(after_key)- except (json.JSONDecodeError, ValueError) as err:- raise HTTPException(status_code=400, detail="after_key is not valid JSON") from err- if not isinstance(parsed, dict):- raise HTTPException(status_code=400, detail="after_key must be a JSON object")- return parsedasync def list_files(@@ -48,36 +28,22 @@ async def list_files(search: str | None = Query(None, description="Search filename"),after_key: str | None = Query(None, description="Composite pagination cursor (JSON-encoded)"),file_service=Depends(get_file_service_v2),- user: User = Depends(get_current_user),+ user: User = Depends(require_api_key_permission("knowledge:read:own")),):- """List ingested files with composite-aggregation pagination, filtering, and sorting."""- parsed_after_key = _parse_after_key(after_key)-- try:- result = await file_service.list_files(- user_id=user.user_id,- jwt_token=user.jwt_token,- page=page,- page_size=page_size,- sort_by=sort_by,- sort_order=sort_order,- connector_type=connector_type,- mimetype=mimetype,- owner=owner,- search=search,- after_key=parsed_after_key,- )- return JSONResponse(result)- except Exception as e:- logger.error("Failed to list files (v2)", error=str(e))- from utils.opensearch_utils import AUTH_ERROR_MESSAGE, is_opensearch_auth_error-- if is_opensearch_auth_error(e):- return JSONResponse({"error": AUTH_ERROR_MESSAGE}, status_code=401)- return JSONResponse(- {"error": "Failed to list files"},- status_code=500,- )+ """List all ingested files (API-key auth). GET /v2/files"""+ return await _internal_list_files(+ page=page,+ page_size=page_size,+ sort_by=sort_by,+ sort_order=sort_order,+ connector_type=connector_type,+ mimetype=mimetype,+ owner=owner,+ search=search,+ after_key=after_key,+ file_service=file_service,+ user=user,+ )async def search_files(@@ -89,31 +55,17 @@ async def search_files(owner: str | None = Query(None, description="Filter by owner"),after_key: str | None = Query(None, description="Composite pagination cursor (JSON-encoded)"),file_service=Depends(get_file_service_v2),- user: User = Depends(get_current_user),+ user: User = Depends(require_api_key_permission("knowledge:read:own")),):- """Search files by name with fuzzy/partial matching (v2 — composite pagination)."""- parsed_after_key = _parse_after_key(after_key)-- try:- result = await file_service.search_files(- user_id=user.user_id,- jwt_token=user.jwt_token,- query=q,- page=page,- page_size=page_size,- connector_type=connector_type,- mimetype=mimetype,- owner=owner,- after_key=parsed_after_key,- )- return JSONResponse(result)- except Exception as e:- logger.error("Failed to search files (v2)", error=str(e))- from utils.opensearch_utils import AUTH_ERROR_MESSAGE, is_opensearch_auth_error-- if is_opensearch_auth_error(e):- return JSONResponse({"error": AUTH_ERROR_MESSAGE}, status_code=401)- return JSONResponse(- {"error": "Failed to search files"},- status_code=500,- )+ """Search ingested files by name (API-key auth). GET /v2/files/search"""+ return await _internal_search_files(+ q=q,+ page=page,+ page_size=page_size,+ connector_type=connector_type,+ mimetype=mimetype,+ owner=owner,+ after_key=after_key,+ file_service=file_service,+ user=user,+ )diff --git a/src/app/container.py b/src/app/container.pyindex d001179c7..0527aa23b 100644--- a/src/app/container.py+++ b/src/app/container.py@@ -23,6 +23,7 @@ from services.dls_principal_service import DLSPrincipalServicefrom services.docling_polling_service import DoclingPollingServicefrom services.document_index_writer import DocumentIndexWriterfrom services.document_service import DocumentService+from services.file_service import FileServicefrom services.file_service_v2 import FileServiceV2from services.flows_service import FlowsServicefrom services.group_acl_service import GroupACLService@@ -216,6 +217,7 @@ async def initialize_services():conversation_persistence._session_factory = _lazy_session_factoryfile_service_v2 = FileServiceV2(session_manager=session_manager)+ file_service = FileService(session_manager=session_manager)return {"document_service": document_service,@@ -242,4 +244,5 @@ async def initialize_services():"rbac_service": rbac_service,"workspace_config_service": workspace_config_service,"file_service_v2": file_service_v2,+ "file_service": file_service,}diff --git a/src/app/routes/internal.py b/src/app/routes/internal.pyindex 383f40f06..0fe449026 100644--- a/src/app/routes/internal.py+++ b/src/app/routes/internal.py@@ -33,7 +33,6 @@ from api import (from api import keys as api_keysfrom api.health import health_check, opensearch_health_readyfrom api.schemas.tasks import ErrorResponse, TaskRetryResponse-from api.v2 import files as files_v2from connectors.registry import get_connector_classes@@ -128,14 +127,10 @@ def register_internal_routes(app: FastAPI):# Search endpointapp.add_api_route("/search", search.search, methods=["POST"], tags=["internal"])- # File listing/search endpoints (v1 — terms-agg, in-memory sort)+ # File listing/search endpointsapp.add_api_route("/files", files.list_files, methods=["GET"], tags=["internal"])app.add_api_route("/files/search", files.search_files, methods=["GET"], tags=["internal"])- # File listing/search endpoints (v2 — composite-agg, cursor pagination)- app.add_api_route("/v2/files/search", files_v2.search_files, methods=["GET"], tags=["internal"])- app.add_api_route("/v2/files", files_v2.list_files, methods=["GET"], tags=["internal"])-# Knowledge Filter endpointsapp.add_api_route("/knowledge-filter",diff --git a/src/app/routes/public_v1.py b/src/app/routes/public_v1.pyindex d3063c39f..c87d5fcfd 100644--- a/src/app/routes/public_v1.py+++ b/src/app/routes/public_v1.py@@ -133,17 +133,11 @@ def register_public_v1_routes(app: FastAPI):methods=["DELETE"],tags=["public"],)- # Files endpoints- # /v1/files/search must be registered before /v1/files to avoid path shadowing- app.add_api_route(- "/v1/files/search",- v1_files.search_files,- methods=["GET"],- tags=["public"],- )++ # Files get_all endpointapp.add_api_route(- "/v1/files",- v1_files.list_files,+ "/v1/files/get_all",+ v1_files.get_all_files,methods=["GET"],tags=["public"],)diff --git a/src/app/routes/public_v2.py b/src/app/routes/public_v2.pyindex df8641081..b44e0424d 100644--- a/src/app/routes/public_v2.py+++ b/src/app/routes/public_v2.py@@ -1,80 +1,22 @@"""Public /v2/* route registrations (API-key auth)."""-from fastapi import Depends, FastAPI, Query+from fastapi import FastAPI-from api.v2 import files as files_v2-from dependencies import get_file_service_v2, require_api_key_permission-from session_manager import User---async def _list_files(- page: int = Query(- 1, ge=1, description="Page number (for display only; navigation uses after_key cursor)"- ),- page_size: int = Query(25, ge=1, le=500, description="Items per page"),- sort_by: str = Query("filename", description="Sort field"),- sort_order: str = Query("asc", pattern="^(asc|desc)$", description="Sort order"),- connector_type: str | None = Query(None, description="Filter by connector type"),- mimetype: str | None = Query(None, description="Filter by MIME type"),- owner: str | None = Query(None, description="Filter by owner"),- search: str | None = Query(None, description="Search filename"),- after_key: str | None = Query(None, description="Composite pagination cursor (JSON-encoded)"),- file_service=Depends(get_file_service_v2),- user: User = Depends(require_api_key_permission("knowledge:read:own")),-):- """List all ingested files. GET /v2/files"""- return await files_v2.list_files(- page=page,- page_size=page_size,- sort_by=sort_by,- sort_order=sort_order,- connector_type=connector_type,- mimetype=mimetype,- owner=owner,- search=search,- after_key=after_key,- file_service=file_service,- user=user,- )---async def _search_files(- q: str = Query(..., min_length=1, description="Search query"),- page: int = Query(1, ge=1, description="Page number"),- page_size: int = Query(25, ge=1, le=500, description="Items per page"),- connector_type: str | None = Query(None, description="Filter by connector type"),- mimetype: str | None = Query(None, description="Filter by MIME type"),- owner: str | None = Query(None, description="Filter by owner"),- after_key: str | None = Query(None, description="Composite pagination cursor (JSON-encoded)"),- file_service=Depends(get_file_service_v2),- user: User = Depends(require_api_key_permission("knowledge:read:own")),-):- """Search ingested files by name. GET /v2/files/search"""- return await files_v2.search_files(- q=q,- page=page,- page_size=page_size,- connector_type=connector_type,- mimetype=mimetype,- owner=owner,- after_key=after_key,- file_service=file_service,- user=user,- )+from api.v2 import files as v2_filesdef register_public_v2_routes(app: FastAPI):- # /v2/files/search must be registered before /v2/files to avoid path shadowing+ # Files endpoints (composite-agg cursor pagination)app.add_api_route("/v2/files/search",- _search_files,+ v2_files.search_files,methods=["GET"],tags=["public"],)app.add_api_route("/v2/files",- _list_files,+ v2_files.list_files,methods=["GET"],tags=["public"],)diff --git a/src/dependencies.py b/src/dependencies.pyindex b9fb51654..063970a5a 100644--- a/src/dependencies.py+++ b/src/dependencies.py@@ -66,6 +66,7 @@ __all__ = ["get_api_key_service","get_api_key_user_async","get_auth_service",+ "get_file_service","get_file_service_v2","get_chat_service","get_connector_service",@@ -177,6 +178,10 @@ def get_api_key_service(services: dict = Depends(get_services)):return services["api_key_service"]+def get_file_service(services: dict = Depends(get_services)):+ return services["file_service"]++def get_file_service_v2(services: dict = Depends(get_services)):return services["file_service_v2"]diff --git a/src/mcp_http/server.py b/src/mcp_http/server.pyindex f09ed0710..d147ffc91 100644--- a/src/mcp_http/server.py+++ b/src/mcp_http/server.py@@ -188,18 +188,18 @@ COMPONENT_CUSTOMIZATIONS: dict[tuple[str, str], dict[str, str]] = {"name": "openrag_delete_knowledge_filter","description": "Delete a knowledge filter by ID.",},- # files endpoints- ("/v1/files", "GET"): {- "name": "openrag_list_files",- "description": "List all ingested files",- },- ("/v1/files/search", "GET"): {- "name": "openrag_search_files",- "description": "Search files by query parameters.",+ # files endpoints (v1 — offset pagination)+ ("/v1/files/get_all", "GET"): {+ "name": "openrag_get_all_files",+ "description": (+ "Return all ingested files from the knowledge base. "+ "No parameters — use GET /v2/files for filtering, sorting, or pagination."+ ),},+ # files endpoints (v2 — composite-agg cursor pagination)("/v2/files", "GET"): {"name": "openrag_list_files_v2",- "description": "lists all ingested files.",+ "description": "List all ingested files with cursor-based composite-aggregation pagination.",},("/v2/files/search", "GET"): {"name": "openrag_search_files_v2",@@ -266,13 +266,13 @@ def create_mcp_server(app: FastAPI) -> FastMCP:pattern=r"^/v1/",mcp_type=MCPType.TOOL,),- # expose /v2/files and /v2/files/search as tools+ # Expose v2 file listing/search endpoints as MCP tools.RouteMap(methods=["GET"],pattern=r"^/v2/files",mcp_type=MCPType.TOOL,),- # exclude everything else+ # Exclude everything elseRouteMap(pattern=r".*",mcp_type=MCPType.EXCLUDE,diff --git a/src/services/file_service.py b/src/services/file_service.pyindex f18b5269e..da4a98f18 100644--- a/src/services/file_service.py+++ b/src/services/file_service.py@@ -50,13 +50,7 @@ class FileService:)except Exception as e:logger.error("Failed to list files", error=str(e))- # An auth failure (OpenSearch rejected the credential) must not be- # masked as an empty result — surface it so the route returns 401.- from utils.opensearch_utils import is_opensearch_auth_error-- if is_opensearch_auth_error(e):- raise- return {"files": [], "total": 0, "page": page, "page_size": page_size}+ raisefiles = self._parse_aggregation_buckets(result)files = self._sort_files(files, sort_by, sort_order)diff --git a/tests/integration/sdk/test_list_files.py b/tests/integration/sdk/test_list_files.pyindex ac36228fb..e35cf3f8b 100644--- a/tests/integration/sdk/test_list_files.py+++ b/tests/integration/sdk/test_list_files.py@@ -18,7 +18,7 @@ pytestmark = pytest.mark.skipif(class TestListFiles:- """Verify GET /v1/files via the Python SDK."""+ """Verify GET /v2/files (cursor pagination) via the Python SDK."""@pytest.mark.asyncioasync def test_list_files_returns_valid_response_shape(self, client, test_file: Path):diff --git a/tests/unit/api/test_v1_files.py b/tests/unit/api/test_v1_files.pyindex 655912463..717ef209b 100644--- a/tests/unit/api/test_v1_files.py+++ b/tests/unit/api/test_v1_files.py@@ -1,13 +1,19 @@"""-Unit tests for the GET /v1/files and GET /v1/files/search route handlers.+Unit tests for the public (API-key) file listing/search handlers.++The public files surface is served by two handler sets, all gated by+require_api_key_permission("knowledge:read:own"):+- api.v1.files.get_all_files → GET /v1/files/get_all (offset pagination)+- api.v2.files.list_files → GET /v2/files (cursor pagination)+- api.v2.files.search_files → GET /v2/files/search (cursor pagination)Tests cover:-- Route delegates to the v2 handler with all params forwarded correctly-- Auth dependency is require_api_key_permission("knowledge:read:own"),- NOT get_current_user-- 401 returned on OpenSearch auth errors-- 400 returned on malformed after_key cursor-- 500 returned on unexpected errors+- All public handlers authenticate with require_api_key_permission, NOT+ get_current_user+- The v2 public handlers forward every param to FileServiceV2 and delegate to+ the internal handlers+- The public wrappers do not drift from the internal handler signatures+- 401 on OpenSearch auth errors, 400 on malformed after_key, 500 on unexpected"""import inspect@@ -16,7 +22,15 @@ from unittest.mock import AsyncMock, MagicMockimport pytestfrom fastapi import params as fastapi_params-from api.v1.files import list_files, search_files+from api.files import (+ list_files as internal_list_files,+)+from api.files import (+ search_files as internal_search_files,+)+from api.v1.files import get_all_files+from api.v2.files import list_files as list_files_public+from api.v2.files import search_files as search_files_publicfrom session_manager import User# ---------------------------------------------------------------------------@@ -54,23 +68,50 @@ def _extract_permission(dep) -> str:class TestAuthDependency:- def test_list_files_uses_require_api_key_permission(self):- """list_files must be gated by require_api_key_permission, not get_current_user."""- dep = _get_user_dependency(list_files)+ @pytest.mark.parametrize(+ "handler",+ [get_all_files, list_files_public, search_files_public],+ ids=["get_all_files", "list_files_public", "search_files_public"],+ )+ def test_public_handler_uses_require_api_key_permission(self, handler):+ """Every public handler must be gated by require_api_key_permission."""+ dep = _get_user_dependency(handler)perm = _extract_permission(dep)assert perm == "knowledge:read:own", f"Expected 'knowledge:read:own', got '{perm}'"- def test_search_files_uses_require_api_key_permission(self):- """search_files must be gated by require_api_key_permission, not get_current_user."""- dep = _get_user_dependency(search_files)- perm = _extract_permission(dep)- assert perm == "knowledge:read:own", f"Expected 'knowledge:read:own', got '{perm}'"+ def test_all_public_handlers_use_same_permission(self):+ """All public handlers must require the same permission — no divergence."""+ perms = {+ _extract_permission(_get_user_dependency(h))+ for h in (get_all_files, list_files_public, search_files_public)+ }+ assert perms == {"knowledge:read:own"}+++# ---------------------------------------------------------------------------+# Signature drift guard+# ---------------------------------------------------------------------------+++def _query_params(fn) -> dict:+ """Parameter name -> annotation for every param except the auth `user`.++ `file_service` is kept: internal and public handlers share the same+ injected service, so it should stay identical too.+ """+ return {+ name: p.annotation for name, p in inspect.signature(fn).parameters.items() if name != "user"+ }+++class TestSignatureParity:+ """The public wrappers re-declare the query signature; guard against drift."""++ def test_list_files_public_matches_internal(self):+ assert _query_params(list_files_public) == _query_params(internal_list_files)- def test_list_files_and_search_files_use_same_permission(self):- """Both handlers must require the same permission — no accidental divergence."""- list_perm = _extract_permission(_get_user_dependency(list_files))- search_perm = _extract_permission(_get_user_dependency(search_files))- assert list_perm == search_perm+ def test_search_files_public_matches_internal(self):+ assert _query_params(search_files_public) == _query_params(internal_search_files)def _make_user() -> User:@@ -117,18 +158,18 @@ _SAMPLE_RESPONSE = {# ----------------------------------------------------------------------------# list_files+# list_files_public (GET /v2/files)# ----------------------------------------------------------------------------class TestListFiles:+class TestListFilesPublic:@pytest.mark.asyncioasync def test_returns_file_list_on_success(self):"""Handler returns the service response as JSONResponse."""file_service = _make_file_service(_SAMPLE_RESPONSE)user = _make_user()- response = await list_files(+ response = await list_files_public(page=1,page_size=25,sort_by="filename",@@ -167,7 +208,7 @@ class TestListFiles:file_service = _make_file_service(_SAMPLE_RESPONSE)user = _make_user()- await list_files(+ await list_files_public(page=2,page_size=50,sort_by="indexed_time",@@ -202,7 +243,7 @@ class TestListFiles:file_service.list_files = AsyncMock(side_effect=AuthenticationException(401, "auth failed"))user = _make_user()- response = await list_files(+ response = await list_files_public(page=1,page_size=25,sort_by="filename",@@ -225,7 +266,7 @@ class TestListFiles:file_service.list_files = AsyncMock(side_effect=RuntimeError("boom"))user = _make_user()- response = await list_files(+ response = await list_files_public(page=1,page_size=25,sort_by="filename",@@ -250,7 +291,7 @@ class TestListFiles:user = _make_user()with pytest.raises(HTTPException) as exc_info:- await list_files(+ await list_files_public(page=1,page_size=25,sort_by="filename",@@ -277,7 +318,7 @@ class TestListFiles:user = _make_user()with pytest.raises(HTTPException) as exc_info:- await list_files(+ await list_files_public(page=1,page_size=25,sort_by="filename",@@ -295,18 +336,18 @@ class TestListFiles:# ----------------------------------------------------------------------------# search_files+# search_files_public (GET /v2/files/search)# ----------------------------------------------------------------------------class TestSearchFiles:+class TestSearchFilesPublic:@pytest.mark.asyncioasync def test_returns_search_results_on_success(self):- """search_files delegates to v2.search_files and returns its result."""+ """search_files_public delegates to v2.search_files and returns its result."""file_service = _make_file_service(_SAMPLE_RESPONSE)user = _make_user()- response = await search_files(+ response = await search_files_public(q="report",page=1,page_size=25,@@ -330,7 +371,7 @@ class TestSearchFiles:file_service = _make_file_service(_SAMPLE_RESPONSE)user = _make_user()- await search_files(+ await search_files_public(q="annual report",page=2,page_size=10,