Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(api): 400 for unknown analyze_documents params + document allow_default_settings (#4527)

LearningCircuitff3725636760
diff --git a/changelog.d/+analyze-documents-param-validation.bugfix.md b/changelog.d/+analyze-documents-param-validation.bugfix.md
new file mode 100644
index 0000000000..afba54d97e
--- /dev/null
+++ b/changelog.d/+analyze-documents-param-validation.bugfix.md
@@ -0,0 +1 @@
+REST `/api/v1/analyze_documents` now rejects unknown body parameters with a clear 400 listing the allowed ones (previously a typo like `max_result` surfaced as an opaque 500), and the `/api/v1/` docs endpoint documents the `allow_default_settings` flag for all three research endpoints.
diff --git a/src/local_deep_research/web/api.py b/src/local_deep_research/web/api.py
index 59fec3bf56..0b45bf916b 100644
--- a/src/local_deep_research/web/api.py
+++ b/src/local_deep_research/web/api.py
@@ -3,6 +3,7 @@ REST API for Local Deep Research.
Provides HTTP access to programmatic search and research capabilities.
"""
+import inspect
import time
from functools import wraps
from typing import Dict, Any, Optional, Tuple
@@ -23,6 +24,19 @@ from ..security.rate_limiter import (
# Create a blueprint for the API
api_blueprint = Blueprint("api_v1", __name__, url_prefix="/api/v1")
+# Body params /analyze_documents accepts beyond the positional
+# query/collection_name. Derived from the real signature so the two can't
+# drift: analyze_documents (unlike quick_summary/generate_report) has no
+# **kwargs, so an unknown key would TypeError at call time — surfacing as
+# an opaque 500. Validating up front turns that into a clear 400.
+# username/settings_snapshot are excluded because they are server-set by
+# _load_user_context_into_params (and overwritten if a body supplied
+# them); programmatic_mode stays accepted as the documented body
+# override.
+_ANALYZE_DOCUMENTS_PARAMS = frozenset(
+ inspect.signature(analyze_documents).parameters
+) - {"query", "collection_name", "username", "settings_snapshot"}
+
# Contract enforced by the test_user_context_loaded /
# test_settings_snapshot_loaded tests in tests/web/test_api_coverage.py.
@@ -189,6 +203,7 @@ def api_documentation():
"search_tool": "Search engine to use (optional)",
"iterations": "Number of search iterations (optional)",
"temperature": "LLM temperature (optional)",
+ "allow_default_settings": "Set to true to proceed with default settings (and NO egress policy) when your stored settings cannot be loaded; default is to refuse with 503 (optional)",
},
},
{
@@ -201,6 +216,7 @@ def api_documentation():
"searches_per_section": "Searches per report section (optional)",
"model_name": "LLM model to use (optional)",
"temperature": "LLM temperature (optional)",
+ "allow_default_settings": "Set to true to proceed with default settings (and NO egress policy) when your stored settings cannot be loaded; default is to refuse with 503 (optional)",
},
},
{
@@ -213,6 +229,7 @@ def api_documentation():
"max_results": "Maximum results to return (optional)",
"temperature": "LLM temperature (optional)",
"force_reindex": "Force collection reindexing (optional)",
+ "allow_default_settings": "Set to true to proceed with default settings (and NO egress policy) when your stored settings cannot be loaded; default is to refuse with 503 (optional)",
},
},
],
@@ -481,6 +498,21 @@ def api_analyze_documents():
if k not in ("query", "collection_name", "allow_default_settings")
}
+ unknown_params = sorted(set(params) - _ANALYZE_DOCUMENTS_PARAMS)
+ if unknown_params:
+ return (
+ jsonify(
+ {
+ "error": (
+ f"Unknown parameter(s) for analyze_documents: "
+ f"{', '.join(unknown_params)}"
+ ),
+ "allowed_parameters": sorted(_ANALYZE_DOCUMENTS_PARAMS),
+ }
+ ),
+ 400,
+ )
+
username = get_current_username()
try:
diff --git a/tests/web/test_api_coverage.py b/tests/web/test_api_coverage.py
index c05b8a533d..8112b68ba9 100644
--- a/tests/web/test_api_coverage.py
+++ b/tests/web/test_api_coverage.py
@@ -178,6 +178,16 @@ class TestApiDocumentation:
assert "description" in ep
assert "parameters" in ep
+ def test_all_endpoints_document_allow_default_settings(self, authed_client):
+ """allow_default_settings is accepted by every research endpoint
+ (fail-closed opt-out) — the docs endpoint must advertise it."""
+ with _mock_access_control():
+ resp = authed_client.get("/api/v1/")
+ for ep in resp.get_json()["endpoints"]:
+ assert "allow_default_settings" in ep["parameters"], (
+ f"{ep['path']} does not document allow_default_settings"
+ )
+
# ===================================================================
# api_access_control decorator
@@ -971,6 +981,46 @@ class TestAnalyzeDocuments:
assert kw["temperature"] == 0.3
assert kw["force_reindex"] is True
+ def test_unknown_param_returns_400(self, authed_client):
+ """analyze_documents has no **kwargs, so an unknown body key would
+ TypeError at call time and surface as an opaque 500. The endpoint
+ must reject it up front with a 400 naming the parameter."""
+ with _mock_access_control():
+ with patch(
+ "local_deep_research.web.api.analyze_documents",
+ return_value={},
+ ) as mock_ad:
+ resp = authed_client.post(
+ "/api/v1/analyze_documents",
+ json={
+ "query": "q",
+ "collection_name": "c",
+ "max_result": 5, # typo: should be max_results
+ },
+ )
+ assert resp.status_code == 400
+ mock_ad.assert_not_called()
+ body = resp.get_json()
+ assert "max_result" in body["error"]
+ assert "max_results" in body["allowed_parameters"]
+
+ @pytest.mark.parametrize("key", ["username", "settings_snapshot"])
+ def test_server_set_params_rejected_in_body(self, authed_client, key):
+ """username/settings_snapshot are set server-side by
+ _load_user_context_into_params; a body that supplies them is
+ rejected rather than silently overwritten."""
+ with _mock_access_control():
+ with patch(
+ "local_deep_research.web.api.analyze_documents",
+ return_value={},
+ ) as mock_ad:
+ resp = authed_client.post(
+ "/api/v1/analyze_documents",
+ json={"query": "q", "collection_name": "c", key: "x"},
+ )
+ assert resp.status_code == 400
+ mock_ad.assert_not_called()
+
def test_error_returns_500(self, authed_client):
with _mock_access_control():
with patch(