Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

feat: expose GET /v1/files on public API surface with SDK support and case-insensitive filename search fix (#2215)

Jason Dongb0c77d0fdb8a
diff --git a/sdks/python/README.md b/sdks/python/README.md
index d3c0b11ad..a818f4f07 100644
--- a/sdks/python/README.md
+++ b/sdks/python/README.md
@@ -171,6 +171,50 @@ result = await client.documents.delete("report.pdf")
print(f"Success: {result.success}")
```
+## Listing Files
+
+`client.documents.list_files()` inventories everything in the knowledge base and
+returns the metadata needed to drive knowledge filters and search.
+
+```python
+import json
+
+# List the first page of files
+page = await client.documents.list_files(page_size=50)
+for f in page.files:
+ print(f"{f.filename} ({f.mimetype}, {f.chunk_count} chunks)")
+
+# Cursor-paginate through all files
+after_key = None
+while True:
+ page = await client.documents.list_files(page_size=100, after_key=after_key)
+ for f in page.files:
+ print(f.filename)
+ if page.after_key is None:
+ break
+ after_key = json.dumps(page.after_key)
+
+# Filter and sort
+page = await client.documents.list_files(
+ connector_type="sharepoint",
+ sort_by="indexed_time",
+ sort_order="desc",
+)
+
+# List → create knowledge filter workflow
+page = await client.documents.list_files(connector_type="sharepoint")
+filenames = [f.filename for f in page.files]
+result = await client.knowledge_filters.create({
+ "name": "SharePoint docs",
+ "queryData": {"filters": {"data_sources": filenames}},
+})
+filter_id = result.id
+
+# Use the filter in search and chat
+results = await client.search.query("quarterly report", filter_id=filter_id)
+response = await client.chat.create(message="Summarise Q3", filter_id=filter_id)
+```
+
## Settings
```python
diff --git a/sdks/python/openrag_sdk/__init__.py b/sdks/python/openrag_sdk/__init__.py
index 86bddffc2..86921232c 100644
--- a/sdks/python/openrag_sdk/__init__.py
+++ b/sdks/python/openrag_sdk/__init__.py
@@ -49,13 +49,16 @@ from .models import (
DeleteDocumentResponse,
DeleteKnowledgeFilterResponse,
DoneEvent,
+ FileRecord,
GetKnowledgeFilterResponse,
IngestResponse,
KnowledgeFilter,
KnowledgeFilterQueryData,
KnowledgeFilterSearchResponse,
KnowledgeSettings,
+ ListFilesResponse,
Message,
+ PrincipalLabel,
SearchFilters,
SearchResponse,
SearchResult,
@@ -82,6 +85,10 @@ __all__ = [
"NotFoundError",
"ValidationError",
"ServerError",
+ # File models
+ "FileRecord",
+ "ListFilesResponse",
+ "PrincipalLabel",
# Models
"ChatResponse",
"ContentEvent",
diff --git a/sdks/python/openrag_sdk/documents.py b/sdks/python/openrag_sdk/documents.py
index 414144c3d..964e39f5b 100644
--- a/sdks/python/openrag_sdk/documents.py
+++ b/sdks/python/openrag_sdk/documents.py
@@ -5,7 +5,13 @@ from pathlib import Path
from typing import TYPE_CHECKING, BinaryIO
from .exceptions import NotFoundError
-from .models import DeleteDocumentResponse, IngestResponse, IngestTaskStatus
+from .models import (
+ DeleteDocumentResponse,
+ FileRecord,
+ IngestResponse,
+ IngestTaskStatus,
+ ListFilesResponse,
+)
if TYPE_CHECKING:
from .client import OpenRAGClient
@@ -176,3 +182,67 @@ class DocumentsClient:
data = response.json()
return DeleteDocumentResponse(**data)
+
+ async def list_files(
+ self,
+ *,
+ page: int = 1,
+ page_size: int = 25,
+ sort_by: str = "filename",
+ sort_order: str = "asc",
+ connector_type: str | None = None,
+ mimetype: str | None = None,
+ owner: str | None = None,
+ search: str | None = None,
+ after_key: str | None = None,
+ ) -> ListFilesResponse:
+ """
+ List ingested files in the knowledge base.
+
+ Args:
+ page: Page number (display only; use after_key for cursor navigation).
+ page_size: Number of files per page (1–500, default 25).
+ sort_by: Field to sort by. One of: filename, file_size, mimetype,
+ indexed_time, connector_type, chunk_count, owner.
+ sort_order: "asc" or "desc".
+ connector_type: Filter to files from a specific connector type.
+ mimetype: Filter to files with a specific MIME type.
+ owner: Filter to files owned by a specific user ID.
+ search: Substring/prefix match against filename.
+ after_key: JSON-encoded composite cursor from a previous response's
+ after_key field. Pass to fetch the next page.
+
+ Returns:
+ ListFilesResponse with files list, total count, and next after_key.
+ """
+ params: dict[str, str | int] = {
+ "page": page,
+ "page_size": page_size,
+ "sort_by": sort_by,
+ "sort_order": sort_order,
+ }
+ if connector_type is not None:
+ params["connector_type"] = connector_type
+ if mimetype is not None:
+ params["mimetype"] = mimetype
+ if owner is not None:
+ params["owner"] = owner
+ if search is not None:
+ params["search"] = search
+ if after_key is not None:
+ params["after_key"] = after_key
+
+ response = await self._client._request(
+ "GET",
+ "/api/v1/files",
+ params=params,
+ )
+ data = response.json()
+ return ListFilesResponse(
+ files=[FileRecord(**f) for f in data.get("files", [])],
+ total=data.get("total", 0),
+ is_approximate=data.get("is_approximate", True),
+ page=data.get("page", page),
+ page_size=data.get("page_size", page_size),
+ after_key=data.get("after_key"),
+ )
diff --git a/sdks/python/openrag_sdk/models.py b/sdks/python/openrag_sdk/models.py
index b0eee0864..d7915267d 100644
--- a/sdks/python/openrag_sdk/models.py
+++ b/sdks/python/openrag_sdk/models.py
@@ -284,3 +284,46 @@ class DeleteKnowledgeFilterResponse(BaseModel):
success: bool
error: str | None = None
+
+
+class PrincipalLabel(BaseModel):
+ """A principal label entry in a file's ACL (connector-ingested files only)."""
+
+ principal: str
+ kind: str
+ provider: str
+ display_name: str = ""
+ email: str = ""
+ external_id: str = ""
+
+
+class FileRecord(BaseModel):
+ """A single ingested file record returned by the list-files endpoint."""
+
+ filename: str
+ document_id: str
+ mimetype: str
+ file_size: int
+ source_url: str
+ owner: str
+ owner_name: str
+ owner_email: str
+ connector_type: str
+ embedding_model: str
+ embedding_dimensions: int | None = None
+ indexed_time: str
+ chunk_count: int
+ allowed_users: list[str] = Field(default_factory=list)
+ allowed_groups: list[str] = Field(default_factory=list)
+ allowed_principal_labels: list[PrincipalLabel] = Field(default_factory=list)
+
+
+class ListFilesResponse(BaseModel):
+ """Response from the list-files endpoint."""
+
+ files: list[FileRecord]
+ total: int
+ is_approximate: bool
+ page: int
+ page_size: int
+ after_key: dict | None = None
diff --git a/sdks/typescript/README.md b/sdks/typescript/README.md
index 6488d1f72..6645f1b13 100644
--- a/sdks/typescript/README.md
+++ b/sdks/typescript/README.md
@@ -201,6 +201,46 @@ const result = await client.documents.delete("report.pdf");
console.log(`Success: ${result.success}`);
```
+## Listing Files
+
+`client.documents.listFiles()` inventories everything in the knowledge base and
+returns the metadata needed to drive knowledge filters and search.
+
+```typescript
+// List the first page of files
+const firstPage = await client.documents.listFiles({ page_size: 50 });
+for (const f of firstPage.files) {
+ console.log(`${f.filename} (${f.mimetype}, ${f.chunk_count} chunks)`);
+}
+
+// Cursor-paginate through all files
+let afterKey: string | undefined;
+do {
+ const page = await client.documents.listFiles({ page_size: 100, after_key: afterKey });
+ for (const f of page.files) console.log(f.filename);
+ afterKey = page.after_key ? JSON.stringify(page.after_key) : undefined;
+} while (afterKey);
+
+// Filter and sort
+const sortedPage = await client.documents.listFiles({
+ connector_type: "sharepoint",
+ sort_by: "indexed_time",
+ sort_order: "desc",
+});
+
+// List → create knowledge filter workflow
+const sharepointPage = await client.documents.listFiles({ connector_type: "sharepoint" });
+const filenames = sharepointPage.files.map(f => f.filename);
+const { id: filterId } = await client.knowledgeFilters.create({
+ name: "SharePoint docs",
+ queryData: { filters: { data_sources: filenames } },
+});
+
+// Use the filter in search and chat
+const results = await client.search.query("quarterly report", { filterId });
+const response = await client.chat.create({ message: "Summarise Q3", filterId });
+```
+
## Settings
```typescript
diff --git a/sdks/typescript/src/documents.ts b/sdks/typescript/src/documents.ts
index 274fce9a2..9cf3fb211 100644
--- a/sdks/typescript/src/documents.ts
+++ b/sdks/typescript/src/documents.ts
@@ -6,8 +6,11 @@ import type { OpenRAGClient } from "./client";
import type {
DeleteDocumentOptions,
DeleteDocumentResponse,
+ FileRecord,
IngestResponse,
IngestTaskStatus,
+ ListFilesOptions,
+ ListFilesResponse,
NotFoundError,
} from "./types";
@@ -144,6 +147,39 @@ export class DocumentsClient {
return new Promise((resolve) => setTimeout(resolve, ms));
}
+ /**
+ * List ingested files in the knowledge base.
+ *
+ * @param options - Filtering, sorting, and pagination options.
+ * @returns ListFilesResponse with files list, total count, and next after_key.
+ */
+ async listFiles(options: ListFilesOptions = {}): Promise<ListFilesResponse> {
+ const params = new URLSearchParams();
+ if (options.page !== undefined) params.set("page", String(options.page));
+ if (options.page_size !== undefined) params.set("page_size", String(options.page_size));
+ if (options.sort_by !== undefined) params.set("sort_by", options.sort_by);
+ if (options.sort_order !== undefined) params.set("sort_order", options.sort_order);
+ if (options.connector_type !== undefined) params.set("connector_type", options.connector_type);
+ if (options.mimetype !== undefined) params.set("mimetype", options.mimetype);
+ if (options.owner !== undefined) params.set("owner", options.owner);
+ if (options.search !== undefined) params.set("search", options.search);
+ 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 response = await this.client._request("GET", path);
+ const data = await response.json();
+
+ return {
+ files: (data.files ?? []) as FileRecord[],
+ total: data.total ?? 0,
+ is_approximate: data.is_approximate ?? true,
+ page: data.page ?? 1,
+ page_size: data.page_size ?? 25,
+ after_key: data.after_key ?? null,
+ };
+ }
+
/**
* Delete document(s) from the knowledge base.
*
diff --git a/sdks/typescript/src/index.ts b/sdks/typescript/src/index.ts
index 3283f118c..0b438b360 100644
--- a/sdks/typescript/src/index.ts
+++ b/sdks/typescript/src/index.ts
@@ -65,6 +65,10 @@ export {
// Document types
IngestResponse,
DeleteDocumentResponse,
+ PrincipalLabel,
+ FileRecord,
+ ListFilesResponse,
+ ListFilesOptions,
// Conversation types
Conversation,
ConversationDetail,
diff --git a/sdks/typescript/src/types.ts b/sdks/typescript/src/types.ts
index 44b7c9acd..941ab9b55 100644
--- a/sdks/typescript/src/types.ts
+++ b/sdks/typescript/src/types.ts
@@ -88,6 +88,68 @@ export interface DeleteDocumentOptions {
filterId?: string;
}
+/** A principal label entry in a file's ACL (connector-ingested files only). */
+export interface PrincipalLabel {
+ principal: string;
+ kind: string;
+ provider: string;
+ display_name?: string;
+ email?: string;
+ external_id?: string;
+}
+
+// File structure type
+export interface FileRecord {
+ filename: string;
+ document_id: string;
+ mimetype: string;
+ file_size: number;
+ source_url: string;
+ owner: string;
+ owner_name: string;
+ owner_email: string;
+ connector_type: string;
+ embedding_model: string;
+ embedding_dimensions: number | null;
+ indexed_time: string;
+ chunk_count: number;
+ allowed_users: string[];
+ allowed_groups: string[];
+ allowed_principal_labels: PrincipalLabel[];
+}
+
+//Response from the list-files endpoint
+export interface ListFilesResponse {
+ files: FileRecord[];
+ total: number;
+ is_approximate: boolean;
+ page: number;
+ page_size: number;
+ after_key: Record<string, unknown> | null;
+}
+
+/** Options for listing files. */
+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;
+}
+
// Chat history types
export interface Message {
role: string;
diff --git a/sdks/typescript/tests/integration.test.ts b/sdks/typescript/tests/integration.test.ts
index b0fff1991..fe21325c4 100644
--- a/sdks/typescript/tests/integration.test.ts
+++ b/sdks/typescript/tests/integration.test.ts
@@ -943,4 +943,107 @@ describe.skipIf(SKIP_TESTS)("OpenRAG TypeScript SDK Integration", () => {
).rejects.toThrow(NotFoundError);
});
});
+
+ describe("Files (listFiles)", () => {
+ it("returns a valid ListFilesResponse shape", async () => {
+ const result = await client.documents.listFiles({ page_size: 10 });
+
+ expect(typeof result.total).toBe("number");
+ expect(result.total).toBeGreaterThanOrEqual(0);
+ expect(typeof result.is_approximate).toBe("boolean");
+ expect(result.page).toBe(1);
+ expect(result.page_size).toBe(10);
+ expect(Array.isArray(result.files)).toBe(true);
+ // after_key is null on a single page or a cursor dict on multi-page
+ expect(result.after_key === null || typeof result.after_key === "object").toBe(true);
+ });
+
+ it("each FileRecord contains fields required for knowledge filter construction", async () => {
+ // Ingest a known file so there is at least one record
+ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-lf-"));
+ const fname = `lf_test_${Date.now()}.md`;
+ const fpath = path.join(tmpDir, fname);
+ fs.writeFileSync(fpath, "# List Files Test\n\nUnique content about silver foxes.\n");
+ await client.documents.ingest({ filePath: fpath });
+
+ try {
+ const result = await client.documents.listFiles({ search: fname });
+ const match = result.files.find((r) => r.filename === fname);
+ expect(match).toBeDefined();
+
+ const f = match!;
+ // Core identity
+ expect(typeof f.filename).toBe("string");
+ expect(f.filename.length).toBeGreaterThan(0);
+ expect(typeof f.document_id).toBe("string");
+ // Knowledge-filter fields
+ expect(typeof f.connector_type).toBe("string");
+ expect(typeof f.mimetype).toBe("string");
+ expect(typeof f.owner).toBe("string");
+ // Pagination / metadata
+ expect(typeof f.chunk_count).toBe("number");
+ expect(f.chunk_count).toBeGreaterThanOrEqual(0);
+ expect(typeof f.file_size).toBe("number");
+ expect(typeof f.indexed_time).toBe("string");
+ // ACL fields
+ expect(Array.isArray(f.allowed_users)).toBe(true);
+ expect(Array.isArray(f.allowed_groups)).toBe(true);
+ expect(Array.isArray(f.allowed_principal_labels)).toBe(true);
+ } finally {
+ await client.documents.delete(fname);
+ }
+ }, 120_000);
+
+ it("cursor pagination returns non-overlapping pages", async () => {
+ const page1 = await client.documents.listFiles({ page_size: 1 });
+ expect(page1.files.length).toBeLessThanOrEqual(1);
+
+ if (page1.after_key !== null && page1.total > 1) {
+ const page2 = await client.documents.listFiles({
+ page_size: 1,
+ after_key: JSON.stringify(page1.after_key),
+ });
+ const p1Names = new Set(page1.files.map((f) => f.filename));
+ const p2Names = new Set(page2.files.map((f) => f.filename));
+ for (const n of p2Names) {
+ expect(p1Names.has(n)).toBe(false);
+ }
+ }
+ });
+
+ it("list → create filter workflow produces a usable filter", async () => {
+ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-lf-wf-"));
+ const fname = `lf_wf_${Date.now()}.md`;
+ const fpath = path.join(tmpDir, fname);
+ fs.writeFileSync(fpath, "# Workflow Test\n\nContent about crimson crabs.\n");
+ await client.documents.ingest({ filePath: fpath });
+ let filterId: string | undefined;
+
+ try {
+ const page = await client.documents.listFiles({ search: fname });
+ const match = page.files.find((f) => f.filename === fname);
+ expect(match).toBeDefined();
+
+ const createResult = await client.knowledgeFilters.create({
+ name: `TS list-files workflow ${Date.now()}`,
+ queryData: {
+ filters: {
+ data_sources: [match!.filename],
+ document_types: ["*"],
+ owners: ["*"],
+ connector_types: ["*"],
+ },
+ limit: 10,
+ scoreThreshold: 0,
+ },
+ });
+ expect(createResult.success).toBe(true);
+ expect(createResult.id).toBeDefined();
+ filterId = createResult.id!;
+ } finally {
+ if (filterId) await client.knowledgeFilters.delete(filterId);
+ await client.documents.delete(fname);
+ }
+ }, 120_000);
+ });
});
diff --git a/src/api/v1/files.py b/src/api/v1/files.py
new file mode 100644
index 000000000..cdce9382d
--- /dev/null
+++ b/src/api/v1/files.py
@@ -0,0 +1,80 @@
+"""
+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.
+"""
+
+from fastapi import Depends, Query
+
+from api.v2 import files as files_v2
+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__)
+
+
+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 /v1/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 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,
+ )
diff --git a/src/app/routes/public_v1.py b/src/app/routes/public_v1.py
index 557745e2c..d3063c39f 100644
--- a/src/app/routes/public_v1.py
+++ b/src/app/routes/public_v1.py
@@ -8,6 +8,9 @@ from api.v1 import (
from api.v1 import (
documents as v1_documents,
)
+from api.v1 import (
+ files as v1_files,
+)
from api.v1 import (
knowledge_filters as v1_knowledge_filters,
)
@@ -130,3 +133,17 @@ 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"],
+ )
+ app.add_api_route(
+ "/v1/files",
+ v1_files.list_files,
+ methods=["GET"],
+ tags=["public"],
+ )
diff --git a/src/mcp_http/server.py b/src/mcp_http/server.py
index ec35ade22..c248dab5a 100644
--- a/src/mcp_http/server.py
+++ b/src/mcp_http/server.py
@@ -188,6 +188,15 @@ 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.",
+ },
}
diff --git a/src/services/file_service.py b/src/services/file_service.py
index dc5f620d7..f18b5269e 100644
--- a/src/services/file_service.py
+++ b/src/services/file_service.py
@@ -123,13 +123,25 @@ class FileService:
filter_clauses.append({"term": {"owner": owner}})
if search:
- # Combine wildcard (partial), prefix, and fuzzy for flexible matching
+ # Combine wildcard (partial) and prefix for flexible matching.
+ # case_insensitive=True so "jason" matches "JASON_RESUME.pdf".
must.append(
{
"bool": {
"should": [
- {"wildcard": {"filename": {"value": f"*{search.lower()}*"}}},
- {"prefix": {"filename": search.lower()}},
+ {
+ "wildcard": {
+ "filename": {
+ "value": f"*{search.lower()}*",
+ "case_insensitive": True,
+ }
+ }
+ },
+ {
+ "prefix": {
+ "filename": {"value": search.lower(), "case_insensitive": True}
+ }
+ },
],
"minimum_should_match": 1,
}
diff --git a/src/services/file_service_v2.py b/src/services/file_service_v2.py
index 6a4607dd0..fc78e24d6 100644
--- a/src/services/file_service_v2.py
+++ b/src/services/file_service_v2.py
@@ -242,8 +242,19 @@ class FileServiceV2:
{
"bool": {
"should": [
- {"wildcard": {"filename": {"value": f"*{search.lower()}*"}}},
- {"prefix": {"filename": search.lower()}},
+ {
+ "wildcard": {
+ "filename": {
+ "value": f"*{search.lower()}*",
+ "case_insensitive": True,
+ }
+ }
+ },
+ {
+ "prefix": {
+ "filename": {"value": search.lower(), "case_insensitive": True}
+ }
+ },
],
"minimum_should_match": 1,
}
@@ -398,7 +409,7 @@ class FileServiceV2:
"""Approximate unique-filename count via cardinality aggregation (O(1)).
Returns (count, is_approximate). is_approximate is always True on
- success (cardinality agg is inherently approximate) and False when the
+ success (cardinality agg is inherently approximate) and True when the
aggregation fails and 0 is returned as a fallback.
"""
body = {
diff --git a/tests/integration/sdk/test_list_files.py b/tests/integration/sdk/test_list_files.py
new file mode 100644
index 000000000..ac36228fb
--- /dev/null
+++ b/tests/integration/sdk/test_list_files.py
@@ -0,0 +1,178 @@
+"""Integration tests for client.documents.list_files().
+
+These tests require a running OpenRAG instance and at least one ingested file.
+They are skipped when SKIP_SDK_INTEGRATION_TESTS=true (CI without a live stack).
+"""
+
+import json
+import os
+import uuid
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.skipif(
+ os.environ.get("SKIP_SDK_INTEGRATION_TESTS") == "true",
+ reason="SDK integration tests skipped",
+)
+
+
+class TestListFiles:
+ """Verify GET /v1/files via the Python SDK."""
+
+ @pytest.mark.asyncio
+ async def test_list_files_returns_valid_response_shape(self, client, test_file: Path):
+ """list_files() returns a ListFilesResponse with required fields."""
+ # Ingest a file so there is at least one result
+ await client.documents.ingest(file_path=str(test_file))
+ try:
+ result = await client.documents.list_files(page_size=10)
+
+ assert result.total >= 0
+ assert isinstance(result.is_approximate, bool)
+ assert result.page == 1
+ assert result.page_size == 10
+ assert isinstance(result.files, list)
+ finally:
+ await client.documents.delete(test_file.name)
+
+ @pytest.mark.asyncio
+ async def test_list_files_record_has_all_knowledge_filter_fields(self, client, test_file: Path):
+ """Each FileRecord contains the fields needed to build a knowledge filter."""
+ await client.documents.ingest(file_path=str(test_file))
+ try:
+ result = await client.documents.list_files(search=test_file.stem)
+ assert len(result.files) >= 1, "Expected the ingested file to appear in results"
+
+ f = result.files[0]
+ # Core identity fields
+ assert isinstance(f.filename, str) and f.filename
+ assert isinstance(f.document_id, str)
+ # Fields needed to build queryData.filters
+ assert isinstance(f.connector_type, str)
+ assert isinstance(f.mimetype, str)
+ assert isinstance(f.owner, str)
+ # Pagination / metadata fields
+ assert isinstance(f.chunk_count, int) and f.chunk_count >= 0
+ assert isinstance(f.file_size, int) and f.file_size >= 0
+ assert isinstance(f.indexed_time, str) and f.indexed_time
+ # ACL fields (may be empty lists but must be present)
+ assert isinstance(f.allowed_users, list)
+ assert isinstance(f.allowed_groups, list)
+ assert isinstance(f.allowed_principal_labels, list)
+ finally:
+ await client.documents.delete(test_file.name)
+
+ @pytest.mark.asyncio
+ async def test_list_files_pagination(self, client, tmp_path: Path):
+ """page_size is respected and after_key cursor enables non-overlapping pages.
+
+ Three files are ingested with a unique token prefix. Both page requests
+ are scoped to that prefix so unrelated index content cannot interfere.
+ With page_size=2 and 3 matching files, page 1 must return an after_key —
+ the assertion is unconditional, not conditional, so the test fails clearly
+ if the cursor is missing.
+ """
+ token = uuid.uuid4().hex[:8]
+ files = []
+ for i in range(3):
+ p = tmp_path / f"pg_{token}_{i}.md"
+ p.write_text(f"# Page test {i}\n\nContent {uuid.uuid4()}.\n")
+ await client.documents.ingest(file_path=str(p))
+ files.append(p)
+
+ try:
+ page1 = await client.documents.list_files(
+ page_size=2,
+ search=f"pg_{token}",
+ )
+ assert len(page1.files) == 2, f"Expected 2 files on page 1, got {len(page1.files)}"
+ assert page1.after_key is not None, (
+ "Expected an after_key cursor with 3 matching files at page_size=2"
+ )
+
+ page2 = await client.documents.list_files(
+ page_size=2,
+ search=f"pg_{token}",
+ after_key=json.dumps(page1.after_key),
+ )
+ assert isinstance(page2.files, list)
+ assert len(page2.files) >= 1, (
+ f"Expected at least 1 file on page 2, got {len(page2.files)}"
+ )
+ # Pages must not overlap by filename
+ p1_names = {f.filename for f in page1.files}
+ p2_names = {f.filename for f in page2.files}
+ assert p1_names.isdisjoint(p2_names), f"Pages overlap: {p1_names & p2_names}"
+ finally:
+ for p in files:
+ await client.documents.delete(p.name)
+
+ @pytest.mark.asyncio
+ async def test_list_files_search_filters_by_filename(self, client, tmp_path: Path):
+ """search= filters by filename and is case-insensitive.
+
+ The needle file has an uppercase prefix (NEEDLE_); the search term is
+ lowercase ('needle_'). This directly exercises the case_insensitive fix
+ in _build_filter_query.
+ """
+ token = uuid.uuid4().hex[:8]
+ # Uppercase filename — search with lowercase to verify case-insensitive matching
+ needle = tmp_path / f"NEEDLE_{token}.md"
+ haystack = tmp_path / f"haystack_{token}.md"
+ needle.write_text("# Needle\n\nUnique needle content.\n")
+ haystack.write_text("# Haystack\n\nUnrelated haystack content.\n")
+
+ await client.documents.ingest(file_path=str(needle))
+ await client.documents.ingest(file_path=str(haystack))
+
+ try:
+ # Search with lowercase — must match the uppercase filename
+ result = await client.documents.list_files(search=f"needle_{token}")
+ filenames = [f.filename for f in result.files]
+ assert any(f"NEEDLE_{token}" in fn for fn in filenames), (
+ f"Case-insensitive search for 'needle_{token}' should match "
+ f"'NEEDLE_{token}.md', got: {filenames}"
+ )
+ assert not any(f"haystack_{token}" in fn for fn in filenames), (
+ f"Haystack should not appear in needle search, got: {filenames}"
+ )
+ finally:
+ await client.documents.delete(needle.name)
+ await client.documents.delete(haystack.name)
+
+ @pytest.mark.asyncio
+ async def test_list_then_create_filter_workflow(self, client, test_file: Path):
+ """Filenames from list_files can be used directly as knowledge filter data_sources."""
+ await client.documents.ingest(file_path=str(test_file))
+ filter_id = None
+
+ try:
+ page = await client.documents.list_files(search=test_file.stem)
+ assert len(page.files) >= 1, "Ingested file must appear in list"
+
+ filenames = [f.filename for f in page.files]
+ result = await client.knowledge_filters.create(
+ {
+ "name": f"list-then-filter {uuid.uuid4().hex[:6]}",
+ "description": "Created by SDK list_files integration test",
+ "queryData": {
+ "query": "",
+ "filters": {
+ "data_sources": filenames,
+ "document_types": ["*"],
+ "owners": ["*"],
+ "connector_types": ["*"],
+ },
+ "limit": 10,
+ "scoreThreshold": 0,
+ },
+ }
+ )
+ assert result.success is True
+ assert result.id is not None
+ filter_id = result.id
+ finally:
+ if filter_id:
+ await client.knowledge_filters.delete(filter_id)
+ await client.documents.delete(test_file.name)
diff --git a/tests/unit/api/test_v1_files.py b/tests/unit/api/test_v1_files.py
new file mode 100644
index 000000000..655912463
--- /dev/null
+++ b/tests/unit/api/test_v1_files.py
@@ -0,0 +1,350 @@
+"""
+Unit tests for the GET /v1/files and GET /v1/files/search route handlers.
+
+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
+"""
+
+import inspect
+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 session_manager import User
+
+# ---------------------------------------------------------------------------
+# Auth-dependency introspection helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_user_dependency(fn) -> object:
+ """Return the raw dependency object wired to the `user` parameter of `fn`."""
+ sig = inspect.signature(fn)
+ user_param = sig.parameters.get("user")
+ assert user_param is not None, f"{fn.__name__} has no `user` parameter"
+ default = user_param.default
+ assert isinstance(default, fastapi_params.Depends), (
+ f"`user` default in {fn.__name__} is not a FastAPI Depends()"
+ )
+ return default.dependency
+
+
+def _extract_permission(dep) -> str:
+ """Extract the permission string from a require_api_key_permission closure."""
+ # require_api_key_permission(perm) returns a closure _dep whose __closure__
+ # holds exactly one cell: the `perm` string.
+ assert dep.__closure__ is not None, "dependency has no closure — not a permission closure"
+ perm_values = [cell.cell_contents for cell in dep.__closure__]
+ assert len(perm_values) == 1, (
+ f"Expected exactly one closure cell, got {len(perm_values)}: {perm_values}"
+ )
+ return perm_values[0]
+
+
+# ---------------------------------------------------------------------------
+# Route-level dependency tests
+# ---------------------------------------------------------------------------
+
+
+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)
+ 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_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 _make_user() -> User:
+ user = MagicMock(spec=User)
+ user.user_id = "test-user-id"
+ user.jwt_token = "test-jwt"
+ return user
+
+
+def _make_file_service(result: dict) -> MagicMock:
+ svc = MagicMock()
+ svc.list_files = AsyncMock(return_value=result)
+ svc.search_files = AsyncMock(return_value=result)
+ return svc
+
+
+_SAMPLE_RESPONSE = {
+ "files": [
+ {
+ "filename": "report.pdf",
+ "document_id": "doc-1",
+ "mimetype": "application/pdf",
+ "file_size": 12345,
+ "source_url": "",
+ "owner": "user-1",
+ "owner_name": "Alice",
+ "owner_email": "[email protected]",
+ "connector_type": "local",
+ "embedding_model": "text-embedding-3-small",
+ "embedding_dimensions": 1536,
+ "indexed_time": "2024-01-01T00:00:00Z",
+ "chunk_count": 5,
+ "allowed_users": [],
+ "allowed_groups": [],
+ "allowed_principal_labels": [],
+ }
+ ],
+ "total": 1,
+ "is_approximate": True,
+ "page": 1,
+ "page_size": 25,
+ "after_key": None,
+}
+
+
+# ---------------------------------------------------------------------------
+# list_files
+# ---------------------------------------------------------------------------
+
+
+class TestListFiles:
+ @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(
+ page=1,
+ page_size=25,
+ sort_by="filename",
+ sort_order="asc",
+ connector_type=None,
+ mimetype=None,
+ owner=None,
+ search=None,
+ after_key=None,
+ file_service=file_service,
+ user=user,
+ )
+
+ assert response.status_code == 200
+ import json
+
+ body = json.loads(response.body)
+ assert body["total"] == 1
+ assert body["files"][0]["filename"] == "report.pdf"
+ # Verify all filter/knowledge fields are present
+ f = body["files"][0]
+ for field in (
+ "document_id",
+ "mimetype",
+ "file_size",
+ "connector_type",
+ "chunk_count",
+ "indexed_time",
+ "allowed_users",
+ ):
+ assert field in f, f"Missing field: {field}"
+
+ @pytest.mark.asyncio
+ async def test_forwards_all_params_to_service(self):
+ """All query params are forwarded to FileServiceV2.list_files."""
+ file_service = _make_file_service(_SAMPLE_RESPONSE)
+ user = _make_user()
+
+ await list_files(
+ page=2,
+ page_size=50,
+ sort_by="indexed_time",
+ sort_order="desc",
+ connector_type="sharepoint",
+ mimetype="application/pdf",
+ owner="user-42",
+ search="report",
+ after_key='{"filename": "a.pdf"}',
+ file_service=file_service,
+ user=user,
+ )
+
+ file_service.list_files.assert_awaited_once()
+ call_kwargs = file_service.list_files.call_args.kwargs
+ assert call_kwargs["page"] == 2
+ assert call_kwargs["page_size"] == 50
+ assert call_kwargs["sort_by"] == "indexed_time"
+ assert call_kwargs["sort_order"] == "desc"
+ assert call_kwargs["connector_type"] == "sharepoint"
+ assert call_kwargs["mimetype"] == "application/pdf"
+ assert call_kwargs["owner"] == "user-42"
+ assert call_kwargs["search"] == "report"
+ assert call_kwargs["after_key"] == {"filename": "a.pdf"}
+
+ @pytest.mark.asyncio
+ async def test_returns_401_on_opensearch_auth_error(self):
+ """OpenSearch auth errors surface as 401, not 500."""
+ from opensearchpy.exceptions import AuthenticationException
+
+ file_service = MagicMock()
+ file_service.list_files = AsyncMock(side_effect=AuthenticationException(401, "auth failed"))
+ user = _make_user()
+
+ response = await list_files(
+ page=1,
+ page_size=25,
+ sort_by="filename",
+ sort_order="asc",
+ connector_type=None,
+ mimetype=None,
+ owner=None,
+ search=None,
+ after_key=None,
+ file_service=file_service,
+ user=user,
+ )
+
+ assert response.status_code == 401
+
+ @pytest.mark.asyncio
+ async def test_returns_500_on_unexpected_error(self):
+ """Unexpected errors return 500."""
+ file_service = MagicMock()
+ file_service.list_files = AsyncMock(side_effect=RuntimeError("boom"))
+ user = _make_user()
+
+ response = await list_files(
+ page=1,
+ page_size=25,
+ sort_by="filename",
+ sort_order="asc",
+ connector_type=None,
+ mimetype=None,
+ owner=None,
+ search=None,
+ after_key=None,
+ file_service=file_service,
+ user=user,
+ )
+
+ assert response.status_code == 500
+
+ @pytest.mark.asyncio
+ async def test_invalid_after_key_returns_400(self):
+ """A non-JSON after_key value raises HTTPException 400 before the service is called."""
+ from fastapi import HTTPException
+
+ file_service = _make_file_service(_SAMPLE_RESPONSE)
+ user = _make_user()
+
+ with pytest.raises(HTTPException) as exc_info:
+ await list_files(
+ page=1,
+ page_size=25,
+ sort_by="filename",
+ sort_order="asc",
+ connector_type=None,
+ mimetype=None,
+ owner=None,
+ search=None,
+ after_key="not-valid-json",
+ file_service=file_service,
+ user=user,
+ )
+
+ assert exc_info.value.status_code == 400
+
+ @pytest.mark.asyncio
+ async def test_after_key_non_dict_returns_400(self):
+ """A valid JSON non-dict after_key (e.g. a string) raises HTTPException 400."""
+ import json
+
+ from fastapi import HTTPException
+
+ file_service = _make_file_service(_SAMPLE_RESPONSE)
+ user = _make_user()
+
+ with pytest.raises(HTTPException) as exc_info:
+ await list_files(
+ page=1,
+ page_size=25,
+ sort_by="filename",
+ sort_order="asc",
+ connector_type=None,
+ mimetype=None,
+ owner=None,
+ search=None,
+ after_key=json.dumps("just-a-string"),
+ file_service=file_service,
+ user=user,
+ )
+
+ assert exc_info.value.status_code == 400
+
+
+# ---------------------------------------------------------------------------
+# search_files
+# ---------------------------------------------------------------------------
+
+
+class TestSearchFiles:
+ @pytest.mark.asyncio
+ async def test_returns_search_results_on_success(self):
+ """search_files delegates to v2.search_files and returns its result."""
+ file_service = _make_file_service(_SAMPLE_RESPONSE)
+ user = _make_user()
+
+ response = await search_files(
+ q="report",
+ page=1,
+ page_size=25,
+ connector_type=None,
+ mimetype=None,
+ owner=None,
+ after_key=None,
+ file_service=file_service,
+ user=user,
+ )
+
+ assert response.status_code == 200
+ import json
+
+ body = json.loads(response.body)
+ assert "files" in body
+
+ @pytest.mark.asyncio
+ async def test_forwards_q_and_filters_to_service(self):
+ """q and all filter params are forwarded to FileServiceV2.search_files."""
+ file_service = _make_file_service(_SAMPLE_RESPONSE)
+ user = _make_user()
+
+ await search_files(
+ q="annual report",
+ page=2,
+ page_size=10,
+ connector_type="gdrive",
+ mimetype="text/plain",
+ owner="user-7",
+ after_key=None,
+ file_service=file_service,
+ user=user,
+ )
+
+ file_service.search_files.assert_awaited_once()
+ kwargs = file_service.search_files.call_args.kwargs
+ assert kwargs["query"] == "annual report"
+ assert kwargs["connector_type"] == "gdrive"
+ assert kwargs["mimetype"] == "text/plain"
+ assert kwargs["owner"] == "user-7"
diff --git a/tests/unit/test_query_acl_filtering.py b/tests/unit/test_query_acl_filtering.py
index 4917996ff..df7833287 100644
--- a/tests/unit/test_query_acl_filtering.py
+++ b/tests/unit/test_query_acl_filtering.py
@@ -23,8 +23,22 @@ def test_file_service_query_omits_application_acl_filter():
{
"bool": {
"should": [
- {"wildcard": {"filename": {"value": "*roadmap*"}}},
- {"prefix": {"filename": "roadmap"}},
+ {
+ "wildcard": {
+ "filename": {
+ "value": "*roadmap*",
+ "case_insensitive": True,
+ }
+ }
+ },
+ {
+ "prefix": {
+ "filename": {
+ "value": "roadmap",
+ "case_insensitive": True,
+ }
+ }
+ },
],
"minimum_should_match": 1,
}