Skip to content

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.ts
index 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.md
index 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
```python
diff --git a/sdks/python/openrag_sdk/__init__.py b/sdks/python/openrag_sdk/__init__.py
index 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",
# Models
diff --git a/sdks/python/openrag_sdk/documents.py b/sdks/python/openrag_sdk/documents.py
index 964e39f5b..d67ea4633 100644
--- a/sdks/python/openrag_sdk/documents.py
+++ b/sdks/python/openrag_sdk/documents.py
@@ -8,6 +8,7 @@ from .exceptions import NotFoundError
from .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.py
index 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: int
diff --git a/sdks/typescript/README.md b/sdks/typescript/README.md
index 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
```typescript
diff --git a/sdks/typescript/src/documents.ts b/sdks/typescript/src/documents.ts
index 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.ts
index 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 types
diff --git a/sdks/typescript/src/types.ts b/sdks/typescript/src/types.ts
index 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.py
index 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, Query
from fastapi.responses import JSONResponse
-from dependencies import get_current_user, get_session_manager
+from dependencies import get_current_user, get_file_service_v2
from session_manager import User
from utils.logging_config import get_logger
logger = 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 parsed
async 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_error
if 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_error
if 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.py
index 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_permission
from session_manager import User
from utils.logging_config import get_logger
logger = 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.py
index 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_permission
from 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 parsed
async 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.py
index d001179c7..0527aa23b 100644
--- a/src/app/container.py
+++ b/src/app/container.py
@@ -23,6 +23,7 @@ from services.dls_principal_service import DLSPrincipalService
from services.docling_polling_service import DoclingPollingService
from services.document_index_writer import DocumentIndexWriter
from services.document_service import DocumentService
+from services.file_service import FileService
from services.file_service_v2 import FileServiceV2
from services.flows_service import FlowsService
from services.group_acl_service import GroupACLService
@@ -216,6 +217,7 @@ async def initialize_services():
conversation_persistence._session_factory = _lazy_session_factory
file_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.py
index 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_keys
from api.health import health_check, opensearch_health_ready
from api.schemas.tasks import ErrorResponse, TaskRetryResponse
-from api.v2 import files as files_v2
from connectors.registry import get_connector_classes
@@ -128,14 +127,10 @@ def register_internal_routes(app: FastAPI):
# Search endpoint
app.add_api_route("/search", search.search, methods=["POST"], tags=["internal"])
- # File listing/search endpoints (v1 — terms-agg, in-memory sort)
+ # File listing/search endpoints
app.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 endpoints
app.add_api_route(
"/knowledge-filter",
diff --git a/src/app/routes/public_v1.py b/src/app/routes/public_v1.py
index 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 endpoint
app.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.py
index 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_files
def 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.py
index 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.py
index 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 else
RouteMap(
pattern=r".*",
mcp_type=MCPType.EXCLUDE,
diff --git a/src/services/file_service.py b/src/services/file_service.py
index 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}
+ raise
files = 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.py
index 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.asyncio
async 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.py
index 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, MagicMock
import pytest
from 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_public
from 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.asyncio
async 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.asyncio
async 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,