From 0824eaa014b7e22bb1968c2ff3b770c926cb1af4 Mon Sep 17 00:00:00 2001
From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com>
Date: Thu, 3 Sep 2026 15:38:32 +0530
Subject: [PATCH 1/4] fix(*): knowledge base pre signed url

---
 backend/app/api/routes/documents.py           |  3 +
 backend/app/core/cloud/storage.py             | 28 +++++++--
 backend/app/models/document.py                |  7 ++-
 backend/app/services/doctransform/job.py      |  9 ++-
 backend/app/services/documents/helpers.py     | 18 +++++-
 backend/app/tests/core/cloud/test_storage.py  | 54 +++++++++++++++-
 .../tests/services/documents/test_helpers.py  | 62 +++++++++++++++++++
 docs/wiki/modules/knowledge-base.md           |  1 +
 8 files changed, 169 insertions(+), 13 deletions(-)

diff --git a/backend/app/api/routes/documents.py b/backend/app/api/routes/documents.py
index f2e3f2d6b..648a7c537 100644
--- a/backend/app/api/routes/documents.py
+++ b/backend/app/api/routes/documents.py
@@ -179,6 +179,9 @@ async def upload_doc(
         source_document, from_attributes=True
     )
     document_schema.signed_url = storage.get_signed_url(
+        source_document.object_store_url, filename=source_document.fname
+    )
+    document_schema.preview_url = storage.get_signed_url(
         source_document.object_store_url
     )
 
diff --git a/backend/app/core/cloud/storage.py b/backend/app/core/cloud/storage.py
index a0b451edd..a65d43fc5 100644
--- a/backend/app/core/cloud/storage.py
+++ b/backend/app/core/cloud/storage.py
@@ -7,7 +7,7 @@
 import functools as ft
 from pathlib import Path
 from dataclasses import dataclass, asdict
-from urllib.parse import ParseResult, urlparse, urlunparse
+from urllib.parse import ParseResult, quote, urlparse, urlunparse
 
 from abc import ABC, abstractmethod
 from typing import Any
@@ -32,6 +32,18 @@ def _mask(value: str | None) -> str:
 logger = logging.getLogger(__name__)
 
 
+def _attachment_disposition(filename: str) -> str:
+    """
+    Build a Content-Disposition header that forces a download.
+    """
+    ascii_fallback = (
+        filename.encode("ascii", "replace").decode("ascii").replace('"', "")
+    )
+    return (
+        f"attachment; filename=\"{ascii_fallback}\"; filename*=UTF-8''{quote(filename)}"
+    )
+
+
 class CloudStorageError(Exception):
     pass
 
@@ -151,7 +163,9 @@ def get_file_size_kb(self, url: str) -> float:
         pass
 
     @abstractmethod
-    def get_signed_url(self, url: str, expires_in: int = 3600) -> str:
+    def get_signed_url(
+        self, url: str, expires_in: int = 3600, filename: str | None = None
+    ) -> str:
         """Generate a signed URL with an optional expiry"""
         pass
 
@@ -255,11 +269,14 @@ def get_file_size_kb(self, url: str) -> float:
     # Maximum allowed expiry for signed URLs (24 hours)
     MAX_SIGNED_URL_EXPIRY = 86400
 
-    def get_signed_url(self, url: str, expires_in: int = 3600) -> str:
+    def get_signed_url(
+        self, url: str, expires_in: int = 3600, filename: str | None = None
+    ) -> str:
         """
         Generate a signed S3 URL for the given file.
         :param url: S3 url (e.g., s3://bucket/key)
         :param expires_in: Expiry time in seconds (default: 1 hour, max: 24 hours)
+        :param filename: When set, the URL forces a download under this name
         :return: Signed URL as string
         """
         # Cap expiry at maximum allowed value to prevent excessively long-lived URLs
@@ -267,9 +284,12 @@ def get_signed_url(self, url: str, expires_in: int = 3600) -> str:
 
         name = SimpleStorageName.from_url(url)
         try:
+            params: dict[str, str] = {"Bucket": name.Bucket, "Key": name.Key}
+            if filename:
+                params["ResponseContentDisposition"] = _attachment_disposition(filename)
             signed_url = self.aws.client.generate_presigned_url(
                 "get_object",
-                Params={"Bucket": name.Bucket, "Key": name.Key},
+                Params=params,
                 ExpiresIn=expires_in,
             )
             logger.info(
diff --git a/backend/app/models/document.py b/backend/app/models/document.py
index 3f3c80996..79c73706e 100644
--- a/backend/app/models/document.py
+++ b/backend/app/models/document.py
@@ -82,7 +82,12 @@ class Document(DocumentBase, table=True):
 class DocumentPublic(DocumentBase):
     id: UUID = Field(description="The unique identifier of the document")
     signed_url: str | None = Field(
-        default=None, description="A signed URL for accessing the document"
+        default=None,
+        description="A signed URL that downloads the document under its original name",
+    )
+    preview_url: str | None = Field(
+        default=None,
+        description="A signed URL that renders the document inline in the browser",
     )
     inserted_at: datetime = Field(
         description="The timestamp when the document was inserted"
diff --git a/backend/app/services/doctransform/job.py b/backend/app/services/doctransform/job.py
index d87a38a32..854142e33 100644
--- a/backend/app/services/doctransform/job.py
+++ b/backend/app/services/doctransform/job.py
@@ -245,11 +245,14 @@ def execute_job(
                 ),
             )
 
-            signed_url = None
+            url_update: dict[str, str] = {}
             try:
                 get_signed_url = getattr(storage, "get_signed_url", None)
                 if callable(get_signed_url):
-                    signed_url = get_signed_url(created.object_store_url)
+                    url_update["signed_url"] = get_signed_url(
+                        created.object_store_url, filename=created.fname
+                    )
+                    url_update["preview_url"] = get_signed_url(created.object_store_url)
             except Exception as e:
                 logger.warning(
                     "[doc_transform] failed to generate signed URL for doc %s: %s",
@@ -259,7 +262,7 @@ def execute_job(
 
             transformed_public = TransformedDocumentPublic.model_validate(
                 created,
-                update={"signed_url": signed_url} if signed_url else None,
+                update=url_update or None,
             )
 
             success_payload = build_success_payload(job_for_payload, transformed_public)
diff --git a/backend/app/services/documents/helpers.py b/backend/app/services/documents/helpers.py
index ffbb1096b..ea566d282 100644
--- a/backend/app/services/documents/helpers.py
+++ b/backend/app/services/documents/helpers.py
@@ -179,6 +179,18 @@ def _to_public_schema(doc: Document) -> PublicDoc:
     return TransformedDocumentPublic.model_validate(doc, from_attributes=True)
 
 
+def _attach_urls(schema: PublicDoc, document: Document, storage: CloudStorage) -> None:
+    """
+    Two links for the same object: the download one carries a Content-Disposition
+    that forces a save under the original filename, the preview one is left bare
+    so browsers render it inline (iframe previews).
+    """
+    schema.signed_url = storage.get_signed_url(
+        document.object_store_url, filename=document.fname
+    )
+    schema.preview_url = storage.get_signed_url(document.object_store_url)
+
+
 def build_document_schema(
     *,
     document: Document,
@@ -187,7 +199,7 @@ def build_document_schema(
 ) -> PublicDoc:
     schema = _to_public_schema(document)
     if include_url and storage:
-        schema.signed_url = storage.get_signed_url(document.object_store_url)
+        _attach_urls(schema, document, storage)
     return schema
 
 
@@ -201,7 +213,7 @@ def build_document_schemas(
     for doc in documents:
         schema = _to_public_schema(doc)
         if include_url and storage:
-            schema.signed_url = storage.get_signed_url(doc.object_store_url)
+            _attach_urls(schema, doc, storage)
         out.append(schema)
     return out
 
@@ -225,7 +237,7 @@ def build_job_schema(
         object_url = doc.object_store_url
 
         if include_url and storage and object_url:
-            transformed_doc_schema.signed_url = storage.get_signed_url(object_url)
+            _attach_urls(transformed_doc_schema, doc, storage)
 
     job_schema = DocTransformationJobPublic.model_validate(job, from_attributes=True)
     return job_schema.model_copy(
diff --git a/backend/app/tests/core/cloud/test_storage.py b/backend/app/tests/core/cloud/test_storage.py
index 95e9ff7ff..e7ffb8cab 100644
--- a/backend/app/tests/core/cloud/test_storage.py
+++ b/backend/app/tests/core/cloud/test_storage.py
@@ -1,8 +1,14 @@
 """Tests for app.core.cloud.storage helpers."""
 
-from unittest.mock import patch
+from types import SimpleNamespace
+from unittest.mock import MagicMock, patch
+from uuid import uuid4
 
-from app.core.cloud.storage import GCS_SCOPES, build_gcp_sa_credentials
+from app.core.cloud.storage import (
+    GCS_SCOPES,
+    AmazonCloudStorage,
+    build_gcp_sa_credentials,
+)
 
 
 def test_build_gcp_sa_credentials_passes_key_and_scopes():
@@ -14,3 +20,47 @@ def test_build_gcp_sa_credentials_passes_key_and_scopes():
 
     mock_from_info.assert_called_once_with(sa_key, scopes=list(GCS_SCOPES))
     assert creds is mock_from_info.return_value
+
+
+def _amazon_storage_with_mock_client(mock_client):
+    storage = AmazonCloudStorage(project_id=1, storage_path=uuid4())
+    storage.aws = SimpleNamespace(client=mock_client)
+    return storage
+
+
+def test_get_signed_url_without_filename_omits_content_disposition():
+    mock_client = MagicMock()
+    storage = _amazon_storage_with_mock_client(mock_client)
+
+    storage.get_signed_url("s3://bucket/key.pdf")
+
+    params = mock_client.generate_presigned_url.call_args.kwargs["Params"]
+    assert "ResponseContentDisposition" not in params
+
+
+def test_get_signed_url_with_filename_forces_attachment():
+    mock_client = MagicMock()
+    storage = _amazon_storage_with_mock_client(mock_client)
+
+    storage.get_signed_url("s3://bucket/key.pdf", filename="report.pdf")
+
+    disposition = mock_client.generate_presigned_url.call_args.kwargs["Params"][
+        "ResponseContentDisposition"
+    ]
+    assert (
+        disposition
+        == "attachment; filename=\"report.pdf\"; filename*=UTF-8''report.pdf"
+    )
+
+
+def test_get_signed_url_encodes_non_ascii_filename():
+    mock_client = MagicMock()
+    storage = _amazon_storage_with_mock_client(mock_client)
+
+    storage.get_signed_url("s3://bucket/key.pdf", filename="रिपोर्ट.pdf")
+
+    disposition = mock_client.generate_presigned_url.call_args.kwargs["Params"][
+        "ResponseContentDisposition"
+    ]
+    assert disposition.startswith('attachment; filename="')
+    assert "filename*=UTF-8''%E0%A4%B0" in disposition
diff --git a/backend/app/tests/services/documents/test_helpers.py b/backend/app/tests/services/documents/test_helpers.py
index 3da9ba30c..05ea93089 100644
--- a/backend/app/tests/services/documents/test_helpers.py
+++ b/backend/app/tests/services/documents/test_helpers.py
@@ -1,10 +1,14 @@
 import csv
 from io import BytesIO
+from uuid import uuid4
 
 import pytest
 from fastapi import HTTPException, UploadFile
 
+from app.models import Document
 from app.services.documents.helpers import (
+    build_document_schema,
+    build_document_schemas,
     calculate_file_size,
     validate_upload,
 )
@@ -338,3 +342,61 @@ def test_missing_filename_raises_400(self) -> None:
             validate_upload(src=src, target_format=None, transformer=None)
         assert exc_info.value.status_code == 400
         assert exc_info.value.detail == "Uploaded file has no filename"
+
+
+def make_document(fname: str = "policy.pdf") -> Document:
+    return Document(
+        id=uuid4(),
+        fname=fname,
+        object_store_url="s3://bucket/key",
+        project_id=1,
+    )
+
+
+class FakeStorage:
+    """Records how each signed URL was requested."""
+
+    def __init__(self) -> None:
+        self.calls: list[dict] = []
+
+    def get_signed_url(
+        self, url: str, expires_in: int = 3600, filename: str | None = None
+    ) -> str:
+        self.calls.append({"url": url, "filename": filename})
+        return f"https://signed/{'download' if filename else 'preview'}"
+
+
+class TestDocumentUrls:
+    def test_download_url_carries_filename_preview_url_does_not(self) -> None:
+        storage = FakeStorage()
+        document = make_document()
+
+        schema = build_document_schema(
+            document=document, include_url=True, storage=storage
+        )
+
+        assert schema.signed_url == "https://signed/download"
+        assert schema.preview_url == "https://signed/preview"
+        assert [c["filename"] for c in storage.calls] == ["policy.pdf", None]
+
+    def test_no_urls_when_include_url_is_false(self) -> None:
+        storage = FakeStorage()
+
+        schema = build_document_schema(
+            document=make_document(), include_url=False, storage=storage
+        )
+
+        assert schema.signed_url is None
+        assert schema.preview_url is None
+        assert storage.calls == []
+
+    def test_list_attaches_both_urls_per_document(self) -> None:
+        storage = FakeStorage()
+        documents = [make_document("a.pdf"), make_document("b.pdf")]
+
+        schemas = build_document_schemas(
+            documents=documents, include_url=True, storage=storage
+        )
+
+        assert all(s.signed_url and s.preview_url for s in schemas)
+        assert [c["filename"] for c in storage.calls] == ["a.pdf", None, "b.pdf", None]
diff --git a/docs/wiki/modules/knowledge-base.md b/docs/wiki/modules/knowledge-base.md
index c6b8462df..735bc0215 100644
--- a/docs/wiki/modules/knowledge-base.md
+++ b/docs/wiki/modules/knowledge-base.md
@@ -33,6 +33,7 @@ All paths relative to `backend/app/`.
 - OpenAI vector stores / file uploads, object storage (`core/cloud/storage.py`), Zerox/OCR for transforms.
 
 ## Gotchas
+- Document responses carry two links for the same object: `signed_url` downloads, `preview_url` renders inline. `put()` stores the upload's `Content-Type`, so a bare presigned URL for a PDF opens in a tab (CSV/XLSX datasets happen to download, which is why only KB docs looked broken). `get_signed_url(..., filename=...)` adds `ResponseContentDisposition: attachment`; `_attach_urls()` in `services/documents/helpers.py` sets both fields, and `api/routes/documents.py` plus `services/doctransform/job.py` do the same for their responses. An attachment URL will not render in an `<iframe>` — preview must use `preview_url`. Leave `filename` unset for URLs meant to play inline (TTS audio in `api/routes/llm.py`).
 - Uploads de-duplicate by provider file ID (see deep dive §7).
 - Collections are immutable-ish: deletion semantics in deep dive §10.
 - OpenAI file-batch id: the SDK's `file_batches.poll()` / `upload_and_poll()` final return deserializes a vector-store body, so its `.id` is the `vs_` id, not the `vsfb_` batch id. `crud/rag/open_ai.py` captures the batch id from `create()` before polling and uses it for `list_files`. Any failed file is a hard failure (whole vector store rolled back); partial indexing needs an add-documents endpoint first.

From c3e2962b9e02f62c4ef6a6ed43138081ddcef715 Mon Sep 17 00:00:00 2001
From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com>
Date: Fri, 4 Sep 2026 11:19:31 +0530
Subject: [PATCH 2/4] fix(*): update the knowledge base url

---
 backend/app/api/routes/collections.py         | 12 +++++-
 .../app/api/routes/doc_transformation_job.py  | 16 ++++++++
 backend/app/api/routes/documents.py           | 19 +++++++--
 backend/app/models/document.py                |  7 +---
 backend/app/services/doctransform/job.py      |  9 ++--
 backend/app/services/documents/helpers.py     | 25 ++++++-----
 .../documents/test_route_document_info.py     | 41 +++++++++++++++++++
 .../tests/services/documents/test_helpers.py  | 40 ++++++++++++------
 docs/wiki/modules/knowledge-base.md           |  2 +-
 9 files changed, 131 insertions(+), 40 deletions(-)

diff --git a/backend/app/api/routes/collections.py b/backend/app/api/routes/collections.py
index fcfeeea53..828db79e5 100644
--- a/backend/app/api/routes/collections.py
+++ b/backend/app/api/routes/collections.py
@@ -249,6 +249,13 @@ def collection_info(
     include_url: bool = Query(
         False, description="Include a signed URL to access the document"
     ),
+    download: bool = Query(
+        False,
+        description=(
+            "When true the signed URL forces a download under the document's "
+            "original filename; when false it opens inline in the browser"
+        ),
+    ),
     limit: int
     | None = Query(
         None,
@@ -275,7 +282,10 @@ def collection_info(
             )
 
         collection_with_docs.documents = build_document_schemas(
-            documents=documents, storage=storage, include_url=include_url
+            documents=documents,
+            storage=storage,
+            include_url=include_url,
+            download=download,
         )
 
     return APIResponse[CollectionWithDocsPublic].success_response(collection_with_docs)
diff --git a/backend/app/api/routes/doc_transformation_job.py b/backend/app/api/routes/doc_transformation_job.py
index 0522b47a9..367a2745e 100644
--- a/backend/app/api/routes/doc_transformation_job.py
+++ b/backend/app/api/routes/doc_transformation_job.py
@@ -32,6 +32,13 @@ def get_transformation_job(
     include_url: bool = Query(
         False, description="Include a signed URL for the transformed document"
     ),
+    download: bool = Query(
+        False,
+        description=(
+            "When true the signed URL forces a download under the document's "
+            "original filename; when false it opens inline in the browser"
+        ),
+    ),
 ):
     job_crud = DocTransformationJobCrud(session, current_user.project_.id)
     doc_crud = DocumentCrud(session, current_user.project_.id)
@@ -48,6 +55,7 @@ def get_transformation_job(
         doc_crud=doc_crud,
         include_url=include_url,
         storage=storage,
+        download=download,
     )
     return APIResponse.success_response(job_schema)
 
@@ -70,6 +78,13 @@ def get_multiple_transformation_jobs(
     include_url: bool = Query(
         False, description="Include a signed URL for each transformed document"
     ),
+    download: bool = Query(
+        False,
+        description=(
+            "When true the signed URL forces a download under the document's "
+            "original filename; when false it opens inline in the browser"
+        ),
+    ),
 ):
     job_crud = DocTransformationJobCrud(session, project_id=current_user.project_.id)
     doc_crud = DocumentCrud(session, project_id=current_user.project_.id)
@@ -89,6 +104,7 @@ def get_multiple_transformation_jobs(
         doc_crud=doc_crud,
         include_url=include_url,
         storage=storage,
+        download=download,
     )
 
     return APIResponse.success_response(
diff --git a/backend/app/api/routes/documents.py b/backend/app/api/routes/documents.py
index 648a7c537..43e5e378c 100644
--- a/backend/app/api/routes/documents.py
+++ b/backend/app/api/routes/documents.py
@@ -82,6 +82,13 @@ def list_docs(
     include_url: bool = Query(
         False, description="Include a signed URL to access each document"
     ),
+    download: bool = Query(
+        False,
+        description=(
+            "When true the signed URL forces a download under the document's "
+            "original filename; when false it opens inline in the browser"
+        ),
+    ),
 ) -> APIResponse[list[Union[DocumentPublic, TransformedDocumentPublic]]]:
     crud = DocumentCrud(session, current_user.project_.id)
     documents, has_more = crud.read_many(skip, limit)
@@ -96,6 +103,7 @@ def list_docs(
         documents=documents,
         include_url=include_url,
         storage=storage,
+        download=download,
     )
     return APIResponse[
         list[Union[DocumentPublic, TransformedDocumentPublic]]
@@ -179,9 +187,6 @@ async def upload_doc(
         source_document, from_attributes=True
     )
     document_schema.signed_url = storage.get_signed_url(
-        source_document.object_store_url, filename=source_document.fname
-    )
-    document_schema.preview_url = storage.get_signed_url(
         source_document.object_store_url
     )
 
@@ -271,6 +276,13 @@ def doc_info(
     include_url: bool = Query(
         False, description="Include a signed URL to access the document"
     ),
+    download: bool = Query(
+        False,
+        description=(
+            "When true the signed URL forces a download under the document's "
+            "original filename; when false it opens inline in the browser"
+        ),
+    ),
 ) -> APIResponse[Union[DocumentPublic, TransformedDocumentPublic]]:
     crud = DocumentCrud(session, current_user.project_.id)
     document = crud.read_one(doc_id)
@@ -285,6 +297,7 @@ def doc_info(
         document=document,
         include_url=include_url,
         storage=storage,
+        download=download,
     )
 
     return APIResponse[
diff --git a/backend/app/models/document.py b/backend/app/models/document.py
index 79c73706e..3f3c80996 100644
--- a/backend/app/models/document.py
+++ b/backend/app/models/document.py
@@ -82,12 +82,7 @@ class Document(DocumentBase, table=True):
 class DocumentPublic(DocumentBase):
     id: UUID = Field(description="The unique identifier of the document")
     signed_url: str | None = Field(
-        default=None,
-        description="A signed URL that downloads the document under its original name",
-    )
-    preview_url: str | None = Field(
-        default=None,
-        description="A signed URL that renders the document inline in the browser",
+        default=None, description="A signed URL for accessing the document"
     )
     inserted_at: datetime = Field(
         description="The timestamp when the document was inserted"
diff --git a/backend/app/services/doctransform/job.py b/backend/app/services/doctransform/job.py
index 854142e33..d87a38a32 100644
--- a/backend/app/services/doctransform/job.py
+++ b/backend/app/services/doctransform/job.py
@@ -245,14 +245,11 @@ def execute_job(
                 ),
             )
 
-            url_update: dict[str, str] = {}
+            signed_url = None
             try:
                 get_signed_url = getattr(storage, "get_signed_url", None)
                 if callable(get_signed_url):
-                    url_update["signed_url"] = get_signed_url(
-                        created.object_store_url, filename=created.fname
-                    )
-                    url_update["preview_url"] = get_signed_url(created.object_store_url)
+                    signed_url = get_signed_url(created.object_store_url)
             except Exception as e:
                 logger.warning(
                     "[doc_transform] failed to generate signed URL for doc %s: %s",
@@ -262,7 +259,7 @@ def execute_job(
 
             transformed_public = TransformedDocumentPublic.model_validate(
                 created,
-                update=url_update or None,
+                update={"signed_url": signed_url} if signed_url else None,
             )
 
             success_payload = build_success_payload(job_for_payload, transformed_public)
diff --git a/backend/app/services/documents/helpers.py b/backend/app/services/documents/helpers.py
index ea566d282..6b18f1af4 100644
--- a/backend/app/services/documents/helpers.py
+++ b/backend/app/services/documents/helpers.py
@@ -179,16 +179,14 @@ def _to_public_schema(doc: Document) -> PublicDoc:
     return TransformedDocumentPublic.model_validate(doc, from_attributes=True)
 
 
-def _attach_urls(schema: PublicDoc, document: Document, storage: CloudStorage) -> None:
+def _signed_url(document: Document, storage: CloudStorage, download: bool) -> str:
     """
-    Two links for the same object: the download one carries a Content-Disposition
-    that forces a save under the original filename, the preview one is left bare
-    so browsers render it inline (iframe previews).
+    One URL, two behaviours: with ``download`` the link carries a
+    Content-Disposition that forces a save under the original filename, without
+    it the link is bare so browsers render it inline (iframe previews).
     """
-    schema.signed_url = storage.get_signed_url(
-        document.object_store_url, filename=document.fname
-    )
-    schema.preview_url = storage.get_signed_url(document.object_store_url)
+    filename = document.fname if download else None
+    return storage.get_signed_url(document.object_store_url, filename=filename)
 
 
 def build_document_schema(
@@ -196,10 +194,11 @@ def build_document_schema(
     document: Document,
     include_url: bool,
     storage: CloudStorage | None,
+    download: bool = False,
 ) -> PublicDoc:
     schema = _to_public_schema(document)
     if include_url and storage:
-        _attach_urls(schema, document, storage)
+        schema.signed_url = _signed_url(document, storage, download)
     return schema
 
 
@@ -208,12 +207,13 @@ def build_document_schemas(
     documents: Iterable[Document],
     include_url: bool,
     storage: CloudStorage | None,
+    download: bool = False,
 ) -> list[PublicDoc]:
     out: list[PublicDoc] = []
     for doc in documents:
         schema = _to_public_schema(doc)
         if include_url and storage:
-            _attach_urls(schema, doc, storage)
+            schema.signed_url = _signed_url(doc, storage, download)
         out.append(schema)
     return out
 
@@ -224,6 +224,7 @@ def build_job_schema(
     doc_crud: DocumentCrud,
     include_url: bool,
     storage: CloudStorage | None,
+    download: bool = False,
 ) -> DocTransformationJobPublic:
     """Build a single job schema, optionally attaching a signed URL."""
     transformed_doc_schema: TransformedDocumentPublic | None = None
@@ -237,7 +238,7 @@ def build_job_schema(
         object_url = doc.object_store_url
 
         if include_url and storage and object_url:
-            _attach_urls(transformed_doc_schema, doc, storage)
+            transformed_doc_schema.signed_url = _signed_url(doc, storage, download)
 
     job_schema = DocTransformationJobPublic.model_validate(job, from_attributes=True)
     return job_schema.model_copy(
@@ -251,6 +252,7 @@ def build_job_schemas(
     doc_crud: DocumentCrud,
     include_url: bool,
     storage: CloudStorage | None,
+    download: bool = False,
 ) -> list[DocTransformationJobPublic]:
     """Build many job schemas efficiently."""
     out: list[DocTransformationJobPublic] = []
@@ -261,6 +263,7 @@ def build_job_schemas(
                 doc_crud=doc_crud,
                 include_url=include_url,
                 storage=storage,
+                download=download,
             )
         )
     return out
diff --git a/backend/app/tests/api/routes/documents/test_route_document_info.py b/backend/app/tests/api/routes/documents/test_route_document_info.py
index 26198348f..e8a1d5a45 100644
--- a/backend/app/tests/api/routes/documents/test_route_document_info.py
+++ b/backend/app/tests/api/routes/documents/test_route_document_info.py
@@ -1,6 +1,9 @@
+from unittest.mock import patch
+
 import pytest
 from sqlmodel import Session
 
+from app.models import Document
 from app.tests.utils.document import (
     DocumentComparator,
     DocumentMaker,
@@ -50,3 +53,41 @@ def test_cannot_info_unknown_document(
         response = crawler.get(route.append(next(maker)))
 
         assert response.is_error
+
+
+class TestDocumentRouteInfoSignedUrl:
+    """The `download` flag decides whether the signed URL forces a save."""
+
+    @staticmethod
+    def _sign_and_capture(
+        db: Session, route: Route, crawler: WebCrawler
+    ) -> tuple[Document, list[str | None]]:
+        store = DocumentStore(db=db, project_id=crawler.user_api_key.project_id)
+        document = store.put()
+        with patch("app.api.routes.documents.get_cloud_storage") as mock_storage:
+            mock_storage.return_value.get_signed_url.return_value = "https://signed"
+            response = crawler.get(route.append(document))
+            assert response.is_success
+            filenames = [
+                call.kwargs.get("filename")
+                for call in mock_storage.return_value.get_signed_url.call_args_list
+            ]
+        return document, filenames
+
+    def test_download_true_signs_with_filename(
+        self, db: Session, crawler: WebCrawler
+    ) -> None:
+        route = Route("", include_url="true", download="true")
+
+        document, filenames = self._sign_and_capture(db, route, crawler)
+
+        assert filenames == [document.fname]
+
+    def test_download_omitted_signs_without_filename(
+        self, db: Session, crawler: WebCrawler
+    ) -> None:
+        route = Route("", include_url="true")
+
+        _, filenames = self._sign_and_capture(db, route, crawler)
+
+        assert filenames == [None]
diff --git a/backend/app/tests/services/documents/test_helpers.py b/backend/app/tests/services/documents/test_helpers.py
index 05ea93089..0e5f9d766 100644
--- a/backend/app/tests/services/documents/test_helpers.py
+++ b/backend/app/tests/services/documents/test_helpers.py
@@ -367,36 +367,52 @@ def get_signed_url(
 
 
 class TestDocumentUrls:
-    def test_download_url_carries_filename_preview_url_does_not(self) -> None:
+    def test_download_true_signs_with_filename(self) -> None:
         storage = FakeStorage()
-        document = make_document()
 
         schema = build_document_schema(
-            document=document, include_url=True, storage=storage
+            document=make_document(),
+            include_url=True,
+            storage=storage,
+            download=True,
         )
 
         assert schema.signed_url == "https://signed/download"
-        assert schema.preview_url == "https://signed/preview"
-        assert [c["filename"] for c in storage.calls] == ["policy.pdf", None]
+        assert [c["filename"] for c in storage.calls] == ["policy.pdf"]
 
-    def test_no_urls_when_include_url_is_false(self) -> None:
+    def test_download_defaults_to_false_and_signs_without_filename(self) -> None:
         storage = FakeStorage()
 
         schema = build_document_schema(
-            document=make_document(), include_url=False, storage=storage
+            document=make_document(), include_url=True, storage=storage
+        )
+
+        assert schema.signed_url == "https://signed/preview"
+        assert [c["filename"] for c in storage.calls] == [None]
+
+    def test_no_url_when_include_url_is_false(self) -> None:
+        storage = FakeStorage()
+
+        schema = build_document_schema(
+            document=make_document(),
+            include_url=False,
+            storage=storage,
+            download=True,
         )
 
         assert schema.signed_url is None
-        assert schema.preview_url is None
         assert storage.calls == []
 
-    def test_list_attaches_both_urls_per_document(self) -> None:
+    def test_list_applies_download_flag_to_every_document(self) -> None:
         storage = FakeStorage()
         documents = [make_document("a.pdf"), make_document("b.pdf")]
 
         schemas = build_document_schemas(
-            documents=documents, include_url=True, storage=storage
+            documents=documents,
+            include_url=True,
+            storage=storage,
+            download=True,
         )
 
-        assert all(s.signed_url and s.preview_url for s in schemas)
-        assert [c["filename"] for c in storage.calls] == ["a.pdf", None, "b.pdf", None]
+        assert all(s.signed_url == "https://signed/download" for s in schemas)
+        assert [c["filename"] for c in storage.calls] == ["a.pdf", "b.pdf"]
diff --git a/docs/wiki/modules/knowledge-base.md b/docs/wiki/modules/knowledge-base.md
index 735bc0215..4cefd5719 100644
--- a/docs/wiki/modules/knowledge-base.md
+++ b/docs/wiki/modules/knowledge-base.md
@@ -33,7 +33,7 @@ All paths relative to `backend/app/`.
 - OpenAI vector stores / file uploads, object storage (`core/cloud/storage.py`), Zerox/OCR for transforms.
 
 ## Gotchas
-- Document responses carry two links for the same object: `signed_url` downloads, `preview_url` renders inline. `put()` stores the upload's `Content-Type`, so a bare presigned URL for a PDF opens in a tab (CSV/XLSX datasets happen to download, which is why only KB docs looked broken). `get_signed_url(..., filename=...)` adds `ResponseContentDisposition: attachment`; `_attach_urls()` in `services/documents/helpers.py` sets both fields, and `api/routes/documents.py` plus `services/doctransform/job.py` do the same for their responses. An attachment URL will not render in an `<iframe>` — preview must use `preview_url`. Leave `filename` unset for URLs meant to play inline (TTS audio in `api/routes/llm.py`).
+- `signed_url` behaviour is chosen per request by the `download` query param (default false = inline, as before). `put()` stores the upload's `Content-Type`, so a bare presigned URL for a PDF opens in a tab (CSV/XLSX datasets happen to download, which is why only KB docs looked broken). `get_signed_url(..., filename=...)` adds `ResponseContentDisposition: attachment`; `_signed_url()` in `services/documents/helpers.py` passes `fname` only when `download` is set, and the flag threads through `build_document_schema(s)` / `build_job_schema(s)` from `api/routes/documents.py`, `doc_transformation_job.py` and `collections.py`. An attachment URL will not render in an `<iframe>`, so preview callers must leave `download` off. The upload response and the doc-transform callback have no request to carry the flag and always sign inline. Leave `filename` unset for URLs meant to play inline (TTS audio in `api/routes/llm.py`).
 - Uploads de-duplicate by provider file ID (see deep dive §7).
 - Collections are immutable-ish: deletion semantics in deep dive §10.
 - OpenAI file-batch id: the SDK's `file_batches.poll()` / `upload_and_poll()` final return deserializes a vector-store body, so its `.id` is the `vs_` id, not the `vsfb_` batch id. `crud/rag/open_ai.py` captures the batch id from `create()` before polling and uses it for `list_files`. Any failed file is a hard failure (whole vector store rolled back); partial indexing needs an add-documents endpoint first.

From db6304537fcbb8e6bc5f52cdd83d8b7f916c74d8 Mon Sep 17 00:00:00 2001
From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com>
Date: Fri, 4 Sep 2026 11:23:21 +0530
Subject: [PATCH 3/4] fix(*): update the params name

---
 backend/app/api/routes/collections.py         |  4 +--
 .../app/api/routes/doc_transformation_job.py  |  8 +++---
 backend/app/api/routes/documents.py           |  8 +++---
 backend/app/services/documents/helpers.py     | 26 +++++++++++--------
 .../documents/test_route_document_info.py     |  8 +++---
 .../tests/services/documents/test_helpers.py  | 12 ++++-----
 docs/wiki/modules/knowledge-base.md           |  2 +-
 7 files changed, 36 insertions(+), 32 deletions(-)

diff --git a/backend/app/api/routes/collections.py b/backend/app/api/routes/collections.py
index 828db79e5..d499f4fcd 100644
--- a/backend/app/api/routes/collections.py
+++ b/backend/app/api/routes/collections.py
@@ -249,7 +249,7 @@ def collection_info(
     include_url: bool = Query(
         False, description="Include a signed URL to access the document"
     ),
-    download: bool = Query(
+    is_downloadable: bool = Query(
         False,
         description=(
             "When true the signed URL forces a download under the document's "
@@ -285,7 +285,7 @@ def collection_info(
             documents=documents,
             storage=storage,
             include_url=include_url,
-            download=download,
+            is_downloadable=is_downloadable,
         )
 
     return APIResponse[CollectionWithDocsPublic].success_response(collection_with_docs)
diff --git a/backend/app/api/routes/doc_transformation_job.py b/backend/app/api/routes/doc_transformation_job.py
index 367a2745e..debf2029b 100644
--- a/backend/app/api/routes/doc_transformation_job.py
+++ b/backend/app/api/routes/doc_transformation_job.py
@@ -32,7 +32,7 @@ def get_transformation_job(
     include_url: bool = Query(
         False, description="Include a signed URL for the transformed document"
     ),
-    download: bool = Query(
+    is_downloadable: bool = Query(
         False,
         description=(
             "When true the signed URL forces a download under the document's "
@@ -55,7 +55,7 @@ def get_transformation_job(
         doc_crud=doc_crud,
         include_url=include_url,
         storage=storage,
-        download=download,
+        is_downloadable=is_downloadable,
     )
     return APIResponse.success_response(job_schema)
 
@@ -78,7 +78,7 @@ def get_multiple_transformation_jobs(
     include_url: bool = Query(
         False, description="Include a signed URL for each transformed document"
     ),
-    download: bool = Query(
+    is_downloadable: bool = Query(
         False,
         description=(
             "When true the signed URL forces a download under the document's "
@@ -104,7 +104,7 @@ def get_multiple_transformation_jobs(
         doc_crud=doc_crud,
         include_url=include_url,
         storage=storage,
-        download=download,
+        is_downloadable=is_downloadable,
     )
 
     return APIResponse.success_response(
diff --git a/backend/app/api/routes/documents.py b/backend/app/api/routes/documents.py
index 43e5e378c..91257e00f 100644
--- a/backend/app/api/routes/documents.py
+++ b/backend/app/api/routes/documents.py
@@ -82,7 +82,7 @@ def list_docs(
     include_url: bool = Query(
         False, description="Include a signed URL to access each document"
     ),
-    download: bool = Query(
+    is_downloadable: bool = Query(
         False,
         description=(
             "When true the signed URL forces a download under the document's "
@@ -103,7 +103,7 @@ def list_docs(
         documents=documents,
         include_url=include_url,
         storage=storage,
-        download=download,
+        is_downloadable=is_downloadable,
     )
     return APIResponse[
         list[Union[DocumentPublic, TransformedDocumentPublic]]
@@ -276,7 +276,7 @@ def doc_info(
     include_url: bool = Query(
         False, description="Include a signed URL to access the document"
     ),
-    download: bool = Query(
+    is_downloadable: bool = Query(
         False,
         description=(
             "When true the signed URL forces a download under the document's "
@@ -297,7 +297,7 @@ def doc_info(
         document=document,
         include_url=include_url,
         storage=storage,
-        download=download,
+        is_downloadable=is_downloadable,
     )
 
     return APIResponse[
diff --git a/backend/app/services/documents/helpers.py b/backend/app/services/documents/helpers.py
index 6b18f1af4..761d9c98d 100644
--- a/backend/app/services/documents/helpers.py
+++ b/backend/app/services/documents/helpers.py
@@ -179,13 +179,15 @@ def _to_public_schema(doc: Document) -> PublicDoc:
     return TransformedDocumentPublic.model_validate(doc, from_attributes=True)
 
 
-def _signed_url(document: Document, storage: CloudStorage, download: bool) -> str:
+def _signed_url(
+    document: Document, storage: CloudStorage, is_downloadable: bool
+) -> str:
     """
-    One URL, two behaviours: with ``download`` the link carries a
+    One URL, two behaviours: with ``is_downloadable`` the link carries a
     Content-Disposition that forces a save under the original filename, without
     it the link is bare so browsers render it inline (iframe previews).
     """
-    filename = document.fname if download else None
+    filename = document.fname if is_downloadable else None
     return storage.get_signed_url(document.object_store_url, filename=filename)
 
 
@@ -194,11 +196,11 @@ def build_document_schema(
     document: Document,
     include_url: bool,
     storage: CloudStorage | None,
-    download: bool = False,
+    is_downloadable: bool = False,
 ) -> PublicDoc:
     schema = _to_public_schema(document)
     if include_url and storage:
-        schema.signed_url = _signed_url(document, storage, download)
+        schema.signed_url = _signed_url(document, storage, is_downloadable)
     return schema
 
 
@@ -207,13 +209,13 @@ def build_document_schemas(
     documents: Iterable[Document],
     include_url: bool,
     storage: CloudStorage | None,
-    download: bool = False,
+    is_downloadable: bool = False,
 ) -> list[PublicDoc]:
     out: list[PublicDoc] = []
     for doc in documents:
         schema = _to_public_schema(doc)
         if include_url and storage:
-            schema.signed_url = _signed_url(doc, storage, download)
+            schema.signed_url = _signed_url(doc, storage, is_downloadable)
         out.append(schema)
     return out
 
@@ -224,7 +226,7 @@ def build_job_schema(
     doc_crud: DocumentCrud,
     include_url: bool,
     storage: CloudStorage | None,
-    download: bool = False,
+    is_downloadable: bool = False,
 ) -> DocTransformationJobPublic:
     """Build a single job schema, optionally attaching a signed URL."""
     transformed_doc_schema: TransformedDocumentPublic | None = None
@@ -238,7 +240,9 @@ def build_job_schema(
         object_url = doc.object_store_url
 
         if include_url and storage and object_url:
-            transformed_doc_schema.signed_url = _signed_url(doc, storage, download)
+            transformed_doc_schema.signed_url = _signed_url(
+                doc, storage, is_downloadable
+            )
 
     job_schema = DocTransformationJobPublic.model_validate(job, from_attributes=True)
     return job_schema.model_copy(
@@ -252,7 +256,7 @@ def build_job_schemas(
     doc_crud: DocumentCrud,
     include_url: bool,
     storage: CloudStorage | None,
-    download: bool = False,
+    is_downloadable: bool = False,
 ) -> list[DocTransformationJobPublic]:
     """Build many job schemas efficiently."""
     out: list[DocTransformationJobPublic] = []
@@ -263,7 +267,7 @@ def build_job_schemas(
                 doc_crud=doc_crud,
                 include_url=include_url,
                 storage=storage,
-                download=download,
+                is_downloadable=is_downloadable,
             )
         )
     return out
diff --git a/backend/app/tests/api/routes/documents/test_route_document_info.py b/backend/app/tests/api/routes/documents/test_route_document_info.py
index e8a1d5a45..75d73fb28 100644
--- a/backend/app/tests/api/routes/documents/test_route_document_info.py
+++ b/backend/app/tests/api/routes/documents/test_route_document_info.py
@@ -56,7 +56,7 @@ def test_cannot_info_unknown_document(
 
 
 class TestDocumentRouteInfoSignedUrl:
-    """The `download` flag decides whether the signed URL forces a save."""
+    """The `is_downloadable` flag decides whether the signed URL forces a save."""
 
     @staticmethod
     def _sign_and_capture(
@@ -74,16 +74,16 @@ def _sign_and_capture(
             ]
         return document, filenames
 
-    def test_download_true_signs_with_filename(
+    def test_is_downloadable_true_signs_with_filename(
         self, db: Session, crawler: WebCrawler
     ) -> None:
-        route = Route("", include_url="true", download="true")
+        route = Route("", include_url="true", is_downloadable="true")
 
         document, filenames = self._sign_and_capture(db, route, crawler)
 
         assert filenames == [document.fname]
 
-    def test_download_omitted_signs_without_filename(
+    def test_is_downloadable_omitted_signs_without_filename(
         self, db: Session, crawler: WebCrawler
     ) -> None:
         route = Route("", include_url="true")
diff --git a/backend/app/tests/services/documents/test_helpers.py b/backend/app/tests/services/documents/test_helpers.py
index 0e5f9d766..caa7e6bcc 100644
--- a/backend/app/tests/services/documents/test_helpers.py
+++ b/backend/app/tests/services/documents/test_helpers.py
@@ -367,20 +367,20 @@ def get_signed_url(
 
 
 class TestDocumentUrls:
-    def test_download_true_signs_with_filename(self) -> None:
+    def test_is_downloadable_true_signs_with_filename(self) -> None:
         storage = FakeStorage()
 
         schema = build_document_schema(
             document=make_document(),
             include_url=True,
             storage=storage,
-            download=True,
+            is_downloadable=True,
         )
 
         assert schema.signed_url == "https://signed/download"
         assert [c["filename"] for c in storage.calls] == ["policy.pdf"]
 
-    def test_download_defaults_to_false_and_signs_without_filename(self) -> None:
+    def test_is_downloadable_defaults_to_false_and_signs_without_filename(self) -> None:
         storage = FakeStorage()
 
         schema = build_document_schema(
@@ -397,13 +397,13 @@ def test_no_url_when_include_url_is_false(self) -> None:
             document=make_document(),
             include_url=False,
             storage=storage,
-            download=True,
+            is_downloadable=True,
         )
 
         assert schema.signed_url is None
         assert storage.calls == []
 
-    def test_list_applies_download_flag_to_every_document(self) -> None:
+    def test_list_applies_is_downloadable_to_every_document(self) -> None:
         storage = FakeStorage()
         documents = [make_document("a.pdf"), make_document("b.pdf")]
 
@@ -411,7 +411,7 @@ def test_list_applies_download_flag_to_every_document(self) -> None:
             documents=documents,
             include_url=True,
             storage=storage,
-            download=True,
+            is_downloadable=True,
         )
 
         assert all(s.signed_url == "https://signed/download" for s in schemas)
diff --git a/docs/wiki/modules/knowledge-base.md b/docs/wiki/modules/knowledge-base.md
index 4cefd5719..1d7e3493c 100644
--- a/docs/wiki/modules/knowledge-base.md
+++ b/docs/wiki/modules/knowledge-base.md
@@ -33,7 +33,7 @@ All paths relative to `backend/app/`.
 - OpenAI vector stores / file uploads, object storage (`core/cloud/storage.py`), Zerox/OCR for transforms.
 
 ## Gotchas
-- `signed_url` behaviour is chosen per request by the `download` query param (default false = inline, as before). `put()` stores the upload's `Content-Type`, so a bare presigned URL for a PDF opens in a tab (CSV/XLSX datasets happen to download, which is why only KB docs looked broken). `get_signed_url(..., filename=...)` adds `ResponseContentDisposition: attachment`; `_signed_url()` in `services/documents/helpers.py` passes `fname` only when `download` is set, and the flag threads through `build_document_schema(s)` / `build_job_schema(s)` from `api/routes/documents.py`, `doc_transformation_job.py` and `collections.py`. An attachment URL will not render in an `<iframe>`, so preview callers must leave `download` off. The upload response and the doc-transform callback have no request to carry the flag and always sign inline. Leave `filename` unset for URLs meant to play inline (TTS audio in `api/routes/llm.py`).
+- `signed_url` behaviour is chosen per request by the `is_downloadable` query param (default false = inline, as before). `put()` stores the upload's `Content-Type`, so a bare presigned URL for a PDF opens in a tab (CSV/XLSX datasets happen to download, which is why only KB docs looked broken). `get_signed_url(..., filename=...)` adds `ResponseContentDisposition: attachment`; `_signed_url()` in `services/documents/helpers.py` passes `fname` only when `is_downloadable` is set, and the flag threads through `build_document_schema(s)` / `build_job_schema(s)` from `api/routes/documents.py`, `doc_transformation_job.py` and `collections.py`. An attachment URL will not render in an `<iframe>`, so preview callers must leave `is_downloadable` off. The upload response and the doc-transform callback have no request to carry the flag and always sign inline. Leave `filename` unset for URLs meant to play inline (TTS audio in `api/routes/llm.py`).
 - Uploads de-duplicate by provider file ID (see deep dive §7).
 - Collections are immutable-ish: deletion semantics in deep dive §10.
 - OpenAI file-batch id: the SDK's `file_batches.poll()` / `upload_and_poll()` final return deserializes a vector-store body, so its `.id` is the `vs_` id, not the `vsfb_` batch id. `crud/rag/open_ai.py` captures the batch id from `create()` before polling and uses it for `list_files`. Any failed file is a hard failure (whole vector store rolled back); partial indexing needs an add-documents endpoint first.

From b4bcb6cd4fda8734caddc34c31473ac1be064051 Mon Sep 17 00:00:00 2001
From: Ayush8923 <80516839+Ayush8923@users.noreply.github.com>
Date: Fri, 4 Sep 2026 16:41:57 +0530
Subject: [PATCH 4/4] fix(*): update the downlaod params name

---
 backend/app/api/routes/collections.py         |  4 +--
 .../app/api/routes/doc_transformation_job.py  |  8 +++---
 backend/app/api/routes/documents.py           |  8 +++---
 backend/app/services/documents/helpers.py     | 26 ++++++++-----------
 .../documents/test_route_document_info.py     |  8 +++---
 .../tests/services/documents/test_helpers.py  | 12 ++++-----
 docs/wiki/modules/knowledge-base.md           |  2 +-
 7 files changed, 32 insertions(+), 36 deletions(-)

diff --git a/backend/app/api/routes/collections.py b/backend/app/api/routes/collections.py
index d499f4fcd..828db79e5 100644
--- a/backend/app/api/routes/collections.py
+++ b/backend/app/api/routes/collections.py
@@ -249,7 +249,7 @@ def collection_info(
     include_url: bool = Query(
         False, description="Include a signed URL to access the document"
     ),
-    is_downloadable: bool = Query(
+    download: bool = Query(
         False,
         description=(
             "When true the signed URL forces a download under the document's "
@@ -285,7 +285,7 @@ def collection_info(
             documents=documents,
             storage=storage,
             include_url=include_url,
-            is_downloadable=is_downloadable,
+            download=download,
         )
 
     return APIResponse[CollectionWithDocsPublic].success_response(collection_with_docs)
diff --git a/backend/app/api/routes/doc_transformation_job.py b/backend/app/api/routes/doc_transformation_job.py
index debf2029b..367a2745e 100644
--- a/backend/app/api/routes/doc_transformation_job.py
+++ b/backend/app/api/routes/doc_transformation_job.py
@@ -32,7 +32,7 @@ def get_transformation_job(
     include_url: bool = Query(
         False, description="Include a signed URL for the transformed document"
     ),
-    is_downloadable: bool = Query(
+    download: bool = Query(
         False,
         description=(
             "When true the signed URL forces a download under the document's "
@@ -55,7 +55,7 @@ def get_transformation_job(
         doc_crud=doc_crud,
         include_url=include_url,
         storage=storage,
-        is_downloadable=is_downloadable,
+        download=download,
     )
     return APIResponse.success_response(job_schema)
 
@@ -78,7 +78,7 @@ def get_multiple_transformation_jobs(
     include_url: bool = Query(
         False, description="Include a signed URL for each transformed document"
     ),
-    is_downloadable: bool = Query(
+    download: bool = Query(
         False,
         description=(
             "When true the signed URL forces a download under the document's "
@@ -104,7 +104,7 @@ def get_multiple_transformation_jobs(
         doc_crud=doc_crud,
         include_url=include_url,
         storage=storage,
-        is_downloadable=is_downloadable,
+        download=download,
     )
 
     return APIResponse.success_response(
diff --git a/backend/app/api/routes/documents.py b/backend/app/api/routes/documents.py
index 91257e00f..43e5e378c 100644
--- a/backend/app/api/routes/documents.py
+++ b/backend/app/api/routes/documents.py
@@ -82,7 +82,7 @@ def list_docs(
     include_url: bool = Query(
         False, description="Include a signed URL to access each document"
     ),
-    is_downloadable: bool = Query(
+    download: bool = Query(
         False,
         description=(
             "When true the signed URL forces a download under the document's "
@@ -103,7 +103,7 @@ def list_docs(
         documents=documents,
         include_url=include_url,
         storage=storage,
-        is_downloadable=is_downloadable,
+        download=download,
     )
     return APIResponse[
         list[Union[DocumentPublic, TransformedDocumentPublic]]
@@ -276,7 +276,7 @@ def doc_info(
     include_url: bool = Query(
         False, description="Include a signed URL to access the document"
     ),
-    is_downloadable: bool = Query(
+    download: bool = Query(
         False,
         description=(
             "When true the signed URL forces a download under the document's "
@@ -297,7 +297,7 @@ def doc_info(
         document=document,
         include_url=include_url,
         storage=storage,
-        is_downloadable=is_downloadable,
+        download=download,
     )
 
     return APIResponse[
diff --git a/backend/app/services/documents/helpers.py b/backend/app/services/documents/helpers.py
index 761d9c98d..6b18f1af4 100644
--- a/backend/app/services/documents/helpers.py
+++ b/backend/app/services/documents/helpers.py
@@ -179,15 +179,13 @@ def _to_public_schema(doc: Document) -> PublicDoc:
     return TransformedDocumentPublic.model_validate(doc, from_attributes=True)
 
 
-def _signed_url(
-    document: Document, storage: CloudStorage, is_downloadable: bool
-) -> str:
+def _signed_url(document: Document, storage: CloudStorage, download: bool) -> str:
     """
-    One URL, two behaviours: with ``is_downloadable`` the link carries a
+    One URL, two behaviours: with ``download`` the link carries a
     Content-Disposition that forces a save under the original filename, without
     it the link is bare so browsers render it inline (iframe previews).
     """
-    filename = document.fname if is_downloadable else None
+    filename = document.fname if download else None
     return storage.get_signed_url(document.object_store_url, filename=filename)
 
 
@@ -196,11 +194,11 @@ def build_document_schema(
     document: Document,
     include_url: bool,
     storage: CloudStorage | None,
-    is_downloadable: bool = False,
+    download: bool = False,
 ) -> PublicDoc:
     schema = _to_public_schema(document)
     if include_url and storage:
-        schema.signed_url = _signed_url(document, storage, is_downloadable)
+        schema.signed_url = _signed_url(document, storage, download)
     return schema
 
 
@@ -209,13 +207,13 @@ def build_document_schemas(
     documents: Iterable[Document],
     include_url: bool,
     storage: CloudStorage | None,
-    is_downloadable: bool = False,
+    download: bool = False,
 ) -> list[PublicDoc]:
     out: list[PublicDoc] = []
     for doc in documents:
         schema = _to_public_schema(doc)
         if include_url and storage:
-            schema.signed_url = _signed_url(doc, storage, is_downloadable)
+            schema.signed_url = _signed_url(doc, storage, download)
         out.append(schema)
     return out
 
@@ -226,7 +224,7 @@ def build_job_schema(
     doc_crud: DocumentCrud,
     include_url: bool,
     storage: CloudStorage | None,
-    is_downloadable: bool = False,
+    download: bool = False,
 ) -> DocTransformationJobPublic:
     """Build a single job schema, optionally attaching a signed URL."""
     transformed_doc_schema: TransformedDocumentPublic | None = None
@@ -240,9 +238,7 @@ def build_job_schema(
         object_url = doc.object_store_url
 
         if include_url and storage and object_url:
-            transformed_doc_schema.signed_url = _signed_url(
-                doc, storage, is_downloadable
-            )
+            transformed_doc_schema.signed_url = _signed_url(doc, storage, download)
 
     job_schema = DocTransformationJobPublic.model_validate(job, from_attributes=True)
     return job_schema.model_copy(
@@ -256,7 +252,7 @@ def build_job_schemas(
     doc_crud: DocumentCrud,
     include_url: bool,
     storage: CloudStorage | None,
-    is_downloadable: bool = False,
+    download: bool = False,
 ) -> list[DocTransformationJobPublic]:
     """Build many job schemas efficiently."""
     out: list[DocTransformationJobPublic] = []
@@ -267,7 +263,7 @@ def build_job_schemas(
                 doc_crud=doc_crud,
                 include_url=include_url,
                 storage=storage,
-                is_downloadable=is_downloadable,
+                download=download,
             )
         )
     return out
diff --git a/backend/app/tests/api/routes/documents/test_route_document_info.py b/backend/app/tests/api/routes/documents/test_route_document_info.py
index 75d73fb28..e8a1d5a45 100644
--- a/backend/app/tests/api/routes/documents/test_route_document_info.py
+++ b/backend/app/tests/api/routes/documents/test_route_document_info.py
@@ -56,7 +56,7 @@ def test_cannot_info_unknown_document(
 
 
 class TestDocumentRouteInfoSignedUrl:
-    """The `is_downloadable` flag decides whether the signed URL forces a save."""
+    """The `download` flag decides whether the signed URL forces a save."""
 
     @staticmethod
     def _sign_and_capture(
@@ -74,16 +74,16 @@ def _sign_and_capture(
             ]
         return document, filenames
 
-    def test_is_downloadable_true_signs_with_filename(
+    def test_download_true_signs_with_filename(
         self, db: Session, crawler: WebCrawler
     ) -> None:
-        route = Route("", include_url="true", is_downloadable="true")
+        route = Route("", include_url="true", download="true")
 
         document, filenames = self._sign_and_capture(db, route, crawler)
 
         assert filenames == [document.fname]
 
-    def test_is_downloadable_omitted_signs_without_filename(
+    def test_download_omitted_signs_without_filename(
         self, db: Session, crawler: WebCrawler
     ) -> None:
         route = Route("", include_url="true")
diff --git a/backend/app/tests/services/documents/test_helpers.py b/backend/app/tests/services/documents/test_helpers.py
index caa7e6bcc..0e5f9d766 100644
--- a/backend/app/tests/services/documents/test_helpers.py
+++ b/backend/app/tests/services/documents/test_helpers.py
@@ -367,20 +367,20 @@ def get_signed_url(
 
 
 class TestDocumentUrls:
-    def test_is_downloadable_true_signs_with_filename(self) -> None:
+    def test_download_true_signs_with_filename(self) -> None:
         storage = FakeStorage()
 
         schema = build_document_schema(
             document=make_document(),
             include_url=True,
             storage=storage,
-            is_downloadable=True,
+            download=True,
         )
 
         assert schema.signed_url == "https://signed/download"
         assert [c["filename"] for c in storage.calls] == ["policy.pdf"]
 
-    def test_is_downloadable_defaults_to_false_and_signs_without_filename(self) -> None:
+    def test_download_defaults_to_false_and_signs_without_filename(self) -> None:
         storage = FakeStorage()
 
         schema = build_document_schema(
@@ -397,13 +397,13 @@ def test_no_url_when_include_url_is_false(self) -> None:
             document=make_document(),
             include_url=False,
             storage=storage,
-            is_downloadable=True,
+            download=True,
         )
 
         assert schema.signed_url is None
         assert storage.calls == []
 
-    def test_list_applies_is_downloadable_to_every_document(self) -> None:
+    def test_list_applies_download_flag_to_every_document(self) -> None:
         storage = FakeStorage()
         documents = [make_document("a.pdf"), make_document("b.pdf")]
 
@@ -411,7 +411,7 @@ def test_list_applies_is_downloadable_to_every_document(self) -> None:
             documents=documents,
             include_url=True,
             storage=storage,
-            is_downloadable=True,
+            download=True,
         )
 
         assert all(s.signed_url == "https://signed/download" for s in schemas)
diff --git a/docs/wiki/modules/knowledge-base.md b/docs/wiki/modules/knowledge-base.md
index 1d7e3493c..4cefd5719 100644
--- a/docs/wiki/modules/knowledge-base.md
+++ b/docs/wiki/modules/knowledge-base.md
@@ -33,7 +33,7 @@ All paths relative to `backend/app/`.
 - OpenAI vector stores / file uploads, object storage (`core/cloud/storage.py`), Zerox/OCR for transforms.
 
 ## Gotchas
-- `signed_url` behaviour is chosen per request by the `is_downloadable` query param (default false = inline, as before). `put()` stores the upload's `Content-Type`, so a bare presigned URL for a PDF opens in a tab (CSV/XLSX datasets happen to download, which is why only KB docs looked broken). `get_signed_url(..., filename=...)` adds `ResponseContentDisposition: attachment`; `_signed_url()` in `services/documents/helpers.py` passes `fname` only when `is_downloadable` is set, and the flag threads through `build_document_schema(s)` / `build_job_schema(s)` from `api/routes/documents.py`, `doc_transformation_job.py` and `collections.py`. An attachment URL will not render in an `<iframe>`, so preview callers must leave `is_downloadable` off. The upload response and the doc-transform callback have no request to carry the flag and always sign inline. Leave `filename` unset for URLs meant to play inline (TTS audio in `api/routes/llm.py`).
+- `signed_url` behaviour is chosen per request by the `download` query param (default false = inline, as before). `put()` stores the upload's `Content-Type`, so a bare presigned URL for a PDF opens in a tab (CSV/XLSX datasets happen to download, which is why only KB docs looked broken). `get_signed_url(..., filename=...)` adds `ResponseContentDisposition: attachment`; `_signed_url()` in `services/documents/helpers.py` passes `fname` only when `download` is set, and the flag threads through `build_document_schema(s)` / `build_job_schema(s)` from `api/routes/documents.py`, `doc_transformation_job.py` and `collections.py`. An attachment URL will not render in an `<iframe>`, so preview callers must leave `download` off. The upload response and the doc-transform callback have no request to carry the flag and always sign inline. Leave `filename` unset for URLs meant to play inline (TTS audio in `api/routes/llm.py`).
 - Uploads de-duplicate by provider file ID (see deep dive §7).
 - Collections are immutable-ish: deletion semantics in deep dive §10.
 - OpenAI file-batch id: the SDK's `file_batches.poll()` / `upload_and_poll()` final return deserializes a vector-store body, so its `.id` is the `vs_` id, not the `vsfb_` batch id. `crud/rag/open_ai.py` captures the batch id from `create()` before polling and uses it for `list_files`. Any failed file is a hard failure (whole vector store rolled back); partial indexing needs an add-documents endpoint first.