~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
/**
* API Service
* Handles all communication with the server API endpoints
* Note: URLValidator is available globally via /static/js/security/url-validator.js
*/
// Base URL for API - guard against duplicate script loading (same pattern as urls.js)
// Uses window property to survive duplicate <script> loads without redeclaring.
const API_BASE_URL = (typeof window !== 'undefined' && typeof window.API_BASE_URL !== 'undefined')
? window.API_BASE_URL
: '/api';
/**
* Get CSRF token from meta tag
* @returns {string} The CSRF token
*/
function getCsrfToken() {
const metaTag = document.querySelector('meta[name="csrf-token"]');
return metaTag ? metaTag.getAttribute('content') : '';
}
/** Read the non-authenticating fingerprint of the login that rendered this page. */
function getAuthContext() {
const value = document.querySelector('meta[name="auth-context"]')?.getAttribute('content');
return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value) ? value : null;
}
/** Retry only a rejected CSRF check, once, within the page's original login. */
async function fetchWithCsrfRecovery(url, options = {}, send = fetch) {
const method = (options.method || 'GET').toUpperCase();
const repeatableBody = options.body == null || typeof options.body === 'string';
let internal = false;
if (typeof url === 'string' && url.startsWith('/') && typeof window !== 'undefined' && window.location?.href) {
const target = new URL(url, window.location.href);
internal = target.origin === new URL(window.location.href).origin
&& !target.pathname.startsWith('/auth/')
&& !window.location.pathname.startsWith('/auth/');
}
const eligible = internal && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)
&& repeatableBody && options.credentials !== 'omit';
const context = eligible ? getAuthContext() : null;
// Snapshot the headers before sending. Do not mutate a caller's Headers
// instance or let later changes replace the original request's context.
let initialOptions = options;
if (context) {
const headers = new globalThis.Headers(options.headers);
headers.set('X-LDR-Auth-Context', context);
initialOptions = { ...options, headers };
}
const response = await send(url, initialOptions);
if (!context || response.status !== 403 || response.redirected
|| response.headers?.get('X-LDR-CSRF-Rejected') !== '1') {
return response;
}
// The marker is emitted only by middleware before a handler is entered.
// Streams/uploads are never replayed, nor are ordinary application 403s.
options.signal?.throwIfAborted();
const refresh = await send('/auth/csrf-token', {
method: 'GET', credentials: 'same-origin', cache: 'no-store', redirect: 'error',
headers: { 'X-LDR-Auth-Context': context }, signal: options.signal
});
options.signal?.throwIfAborted();
if (getAuthContext() !== context) {
throw new Error('Your sign-in changed. Reload this page before trying again.');
}
// The refresh returns 401/409 if the login expired or was replaced, or
// 503 if the session cannot be checked right now (it is kept). Let the
// existing auth/error handling surface it; no original write is sent.
if (!refresh.ok) return refresh;
const fresh = await refresh.json();
options.signal?.throwIfAborted();
if (typeof fresh?.auth_context !== 'string' || typeof fresh?.csrf_token !== 'string' || !fresh.csrf_token) {
return response;
}
if (fresh.auth_context !== context || getAuthContext() !== context) {
throw new Error('Your sign-in changed. Reload this page before trying again.');
}
document.querySelector('meta[name="csrf-token"]')?.setAttribute('content', fresh.csrf_token);
const headers = new globalThis.Headers(initialOptions.headers);
headers.delete('X-CSRF-Token');
headers.set('X-CSRFToken', fresh.csrf_token);
// A direct send (not recursion) caps the entire operation at one retry.
// Reuse the original signal so refresh does not reset its timeout.
return send(url, { ...initialOptions, headers });
}
/**
* True when the server refused a request because this page's login was
* replaced (e.g. the user signed in again in another tab). CSRFMiddleware and
* /auth/csrf-token mark that 409 with X-LDR-Auth-Changed: 1; an endpoint's own
* 409 (such as "indexing already running") never carries it. The body's
* `error` holds the message to show; do not match on its prose.
*
* @param {Response} response
* @returns {boolean}
*/
function isAuthContextChanged(response) {
return response?.status === 409
&& response.headers?.get?.('X-LDR-Auth-Changed') === '1';
}
/**
* Get the full URL for an API endpoint
* @param {string} path - The API path (without leading slash)
* @returns {string} The full API URL
*/
function getApiUrl(path) {
return `${API_BASE_URL}/${path}`;
}
/**
* Decide whether a 401 from `url` should bounce the user to the login page.
*
* Only same-origin (leading-slash) API URLs qualify: a 401 from a third-party
* URL means that API rejected us, not that our own session expired. We also
* never redirect while already inside the /auth/* flow (that would loop), and
* we leave requests to /auth/* itself alone (the auth subsystem handles its
* own 401 states, e.g. failed login validation).
*
* @param {string} url - The request URL
* @returns {boolean}
*/
function shouldRedirectToLoginOn401(url) {
if (typeof window === 'undefined') return false;
if (!url.startsWith('/')) return false; // external (absolute) URL
// Reject cross-origin bypass forms: //host is protocol-relative, and a
// backslash is normalized to '/' by browsers, so both //host and /\host
// resolve cross-origin (verified via URL()). Mirrors the server's
// is_safe_redirect_url, which rejects a leading // and any backslash.
if (url.startsWith('//') || url.includes('\\')) return false;
if (window.location.pathname.startsWith('/auth/')) return false; // already in login flow
if (url.startsWith('/auth/')) return false; // auth handles its own 401s
return true;
}
/**
* Send the user to the login page, preserving the current location as `next`
* so they land back where they were after re-authenticating.
*
* `next` is a same-origin relative path (pathname + query + hash): staying
* relative means it's trivially same-origin, and keeping the hash preserves
* in-page state (e.g. #logs) so the user lands exactly where they were. The
* server re-validates it via URLValidator.get_safe_redirect_path anyway.
*/
function redirectToLogin() {
const next = encodeURIComponent(
window.location.pathname + window.location.search + window.location.hash
);
// Hardcoded /auth/login target; `next` is a same-origin relative path that
// the server re-validates (get_safe_redirect_path) before redirecting.
// bearer:disable javascript_lang_open_redirect
window.location.href = `/auth/login?next=${next}`;
}
/** Recover a stale logout form without applying it to a replacement login. */
async function submitLogout(form) {
if (form.dataset.logoutPending === 'true') return;
form.dataset.logoutPending = 'true';
form.setAttribute('aria-busy', 'true');
// The control is a link (see base.html), so mark it busy rather than
// relying on `disabled`; logoutPending above already blocks re-entry.
const control = form.querySelector('.ldr-logout-btn');
if (control) control.setAttribute('aria-disabled', 'true');
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);
const changed = 'Your sign-in changed. Reload this page before logging out.';
try {
const context = getAuthContext();
if (!context) throw new Error('Reload this page before logging out.');
const options = {
credentials: 'same-origin', cache: 'no-store', redirect: 'error',
signal: controller.signal,
headers: { 'Accept': 'application/json', 'X-LDR-Auth-Context': context }
};
const refresh = await fetch('/auth/csrf-token', { ...options, method: 'GET' });
if (getAuthContext() !== context || refresh.status === 409) throw new Error(changed);
if (refresh.status === 401) {
window.location.href = '/auth/login';
return;
}
if (!refresh.ok) throw new Error('Could not check your session. Please try logging out again.');
const fresh = await refresh.json();
if (getAuthContext() !== context || fresh.auth_context !== context) throw new Error(changed);
if (typeof fresh.csrf_token !== 'string' || !fresh.csrf_token) {
throw new Error('Could not refresh your session. Reload this page before logging out.');
}
// Not signal.throwIfAborted(): it needs Safari 15.4 / Chrome 100 /
// Firefox 97, and its absence would block logout on older browsers.
if (controller.signal.aborted) throw new window.DOMException('Aborted', 'AbortError');
const response = await fetch('/auth/logout', {
...options, method: 'POST',
headers: { ...options.headers, 'X-CSRFToken': fresh.csrf_token }
});
if (getAuthContext() !== context || response.status === 409) throw new Error(changed);
if (response.status === 401) {
window.location.href = '/auth/login';
return;
}
if (!response.ok) throw new Error('Could not log out. Reload this page and try again.');
const result = await response.json();
if (getAuthContext() !== context) throw new Error(changed);
if (result.success !== true) throw new Error('Logout was not confirmed. Please try again.');
window.location.href = '/auth/login';
} catch (error) {
// A transport failure may happen after logout succeeded. Leave a
// retry to the user; its fresh session check handles that case.
const message = error.name === 'AbortError'
? 'Logout timed out. Please try again.'
: error instanceof TypeError
? 'Could not confirm logout. Please check your connection and try again.'
: error.message;
window.ui.showMessage(message, 'error', 10000);
} finally {
clearTimeout(timeout);
delete form.dataset.logoutPending;
form.removeAttribute('aria-busy');
if (control) control.removeAttribute('aria-disabled');
}
}
/**
* Generic fetch with error handling and timeout support
* @param {string} url - The URL to fetch
* @param {Object} options - Fetch options
* @param {number} [options.timeout=30000] - Request timeout in milliseconds (default: 30s)
* @returns {Promise<any>} The parsed response data
*/
async function fetchWithErrorHandling(url, options = {}) {
const {
timeout = 30000,
signal: callerSignal,
...fetchOptions
} = options;
const controller = new AbortController();
let abortCause = null;
const abortFromCaller = () => {
if (controller.signal.aborted) return;
abortCause = 'caller';
controller.abort(callerSignal?.reason);
};
if (callerSignal) {
if (callerSignal.aborted) {
abortFromCaller();
} else {
callerSignal.addEventListener('abort', abortFromCaller, { once: true });
}
}
const timeoutId = setTimeout(() => {
if (controller.signal.aborted) return;
abortCause = 'timeout';
controller.abort();
}, timeout);
try {
const csrfToken = getCsrfToken();
// This wrapper parses JSON even for routes outside /api/. Advertise
// that response type so an expired session produces a JSON 401.
const headers = new globalThis.Headers({
'Accept': 'application/json',
'Content-Type': 'application/json',
...(csrfToken ? { 'X-CSRFToken': csrfToken } : {})
});
new globalThis.Headers(fetchOptions.headers ?? {}).forEach((value, name) => {
headers.set(name, value);
});
const response = await fetchWithCsrfRecovery(url, {
...fetchOptions,
signal: controller.signal,
headers
});
// Expired/invalid session on an internal API call: bounce the user to
// login (preserving where they were) instead of throwing an opaque
// "API Error: 401" that every caller would have to special-case. The
// returned Promise never resolves because the page is navigating away.
if (response.status === 401 && shouldRedirectToLoginOn401(url)) {
redirectToLogin();
return new Promise(() => {});
}
// Handle non-200 responses.
// FastAPI's HTTPException puts the message under `detail`, not
// `error` or `message` — without checking `detail` first, every
// 401/403/404 surfaced as the generic "API Error: 401..." and
// the UI lost session-expired / CSRF-missing messages.
if (!response.ok) {
const errorData = await response.json().catch(() => ({}));
const error = new Error(
errorData?.message ||
errorData?.error ||
errorData?.detail ||
`API Error: ${response.status} ${response.statusText}`
);
// Preserve the parsed error body so callers can surface
// structured details the single-message throw discards — e.g.
// the per-setting `errors` array the settings save routes
// return alongside the generic "Validation errors" message.
// Only a non-empty object body has anything worth forwarding:
// null bodies and unparseable payloads resolve to nothing.
if (
errorData &&
typeof errorData === 'object' &&
Object.keys(errorData).length > 0
) {
error.details = errorData;
}
throw error;
}
// Parse the response
return await response.json();
} catch (error) {
if (error.name === 'AbortError') {
if (abortCause === 'timeout') {
throw new Error('Request timed out');
}
// Caller-owned cancellation is expected control flow (for
// example, a newer request superseding an older one). Preserve
// the original AbortError without reporting it as an API failure.
if (abortCause === 'caller') {
throw error;
}
}
SafeLogger.error('API Error:', error);
throw error;
} finally {
clearTimeout(timeoutId);
callerSignal?.removeEventListener('abort', abortFromCaller);
}
}
/**
* Helper method to perform POST requests with JSON data
* @param {string} path - API path
* @param {Object} data - JSON data to send
* @returns {Promise<any>} Response data
*/
async function postJSON(path, data) {
return fetchWithErrorHandling(path, {
method: 'POST',
body: JSON.stringify(data)
});
}
/**
* Start a new research
* @param {string} query - The research query
* @param {string} mode - The research mode (quick/detailed)
* @returns {Promise<Object>} The research response with ID
*/
async function startResearch(query, mode) {
return postJSON(URLS.API.START_RESEARCH, { query, mode });
}
/**
* Get a research status by ID
* @param {number} researchId - The research ID
* @returns {Promise<Object>} The research status
*/
async function getResearchStatus(researchId) {
return fetchWithErrorHandling(URLBuilder.researchStatus(researchId));
}
/**
* Get research details
* @param {number} researchId - The research ID
* @returns {Promise<Object>} The research details
*/
async function getResearchDetails(researchId) {
return fetchWithErrorHandling(URLBuilder.researchDetails(researchId));
}
/**
* Get research logs
* @param {number} researchId - The research ID
* @returns {Promise<Object>} The research logs
*/
async function getResearchLogs(researchId) {
return fetchWithErrorHandling(URLBuilder.researchLogs(researchId));
}
/**
* Get research history
* @returns {Promise<Array>} The research history
*/
async function getResearchHistory() {
return fetchWithErrorHandling(URLS.API.HISTORY);
}
/**
* Get research report
* @param {number} researchId - The research ID
* @returns {Promise<Object>} The research report
*/
async function getReport(researchId) {
return fetchWithErrorHandling(URLBuilder.researchReport(researchId));
}
/**
* Terminate a research
* @param {number} researchId - The research ID
* @returns {Promise<Object>} The termination response
*/
async function terminateResearch(researchId) {
return postJSON(URLBuilder.terminateResearch(researchId), {});
}
/**
* Delete a research
* @param {number} researchId - The research ID
* @returns {Promise<Object>} The deletion response
*/
async function deleteResearch(researchId) {
return fetchWithErrorHandling(URLBuilder.deleteResearch(researchId), {
method: 'DELETE'
});
}
/**
* Clear all research history
* @returns {Promise<Object>} The response
*/
async function clearResearchHistory() {
return postJSON(URLS.API.CLEAR_HISTORY, {});
}
/**
* Open a file location in the system file explorer
* @param {string} path - Path to open
* @returns {Promise<Object>} The response
*/
async function openFileLocation(path) {
return postJSON('/settings/open_file_location', { path });
}
/**
* Save raw configuration
* @param {string} rawConfig - Raw configuration text
* @returns {Promise<Object>} The response
*/
async function saveRawConfig(rawConfig) {
return postJSON(URLS.API.SAVE_RAW_CONFIG, { raw_config: rawConfig });
}
/**
* Save main configuration
* @param {Object} config - Configuration object
* @returns {Promise<Object>} The response
*/
async function saveMainConfig(config) {
return postJSON(URLS.API.SAVE_MAIN_CONFIG, config);
}
/**
* Save search engines configuration
* @param {Object} config - Configuration object
* @returns {Promise<Object>} The response
*/
async function saveSearchEnginesConfig(config) {
return postJSON(URLS.API.SAVE_SEARCH_ENGINES_CONFIG, config);
}
/**
* Save collections configuration
* @param {Object} config - Configuration object
* @returns {Promise<Object>} The response
*/
async function saveCollectionsConfig(config) {
return postJSON(URLS.API.SAVE_COLLECTIONS_CONFIG, config);
}
/**
* Save API keys configuration
* @param {Object} config - Configuration object
* @returns {Promise<Object>} The response
*/
async function saveApiKeysConfig(config) {
return postJSON(URLS.API.SAVE_API_KEYS_CONFIG, config);
}
/**
* Save LLM configuration
* @param {Object} config - Configuration object
* @returns {Promise<Object>} The response
*/
async function saveLlmConfig(config) {
return postJSON(URLS.API.SAVE_LLM_CONFIG, config);
}
/**
* Get markdown export for research
* @param {number} researchId - The research ID
* @returns {Promise<Object>} The markdown content
*/
async function getMarkdownExport(researchId) {
return fetchWithErrorHandling(URLBuilder.markdownExport(researchId));
}
// Export for Node.js testing
if (typeof module !== 'undefined' && module.exports) {
module.exports = {
getCsrfToken,
fetchWithErrorHandling,
fetchWithCsrfRecovery,
shouldRedirectToLoginOn401,
redirectToLogin,
getApiUrl,
postJSON,
startResearch,
getResearchStatus,
getResearchDetails,
getResearchLogs,
getResearchHistory,
getReport,
getMarkdownExport,
terminateResearch,
deleteResearch,
clearResearchHistory,
openFileLocation,
saveRawConfig,
saveMainConfig,
saveSearchEnginesConfig,
saveCollectionsConfig,
saveApiKeysConfig,
saveLlmConfig
};
}
// Make api available globally for browser usage
if (typeof window !== 'undefined') {
document.addEventListener('submit', async event => {
if (event.target.id !== 'logout-form') return;
event.preventDefault();
await submitLogout(event.target);
});
// The top-bar logout control is a link rather than a submit button
// (base.html), so page-wide submit-button selectors never match it.
document.addEventListener('click', async event => {
const control = event.target instanceof Element
? event.target.closest('#logout-form .ldr-logout-btn')
: null;
if (!control) return;
event.preventDefault();
await submitLogout(control.closest('form'));
});
window.api = {
startResearch,
getResearchStatus,
getResearchDetails,
getResearchLogs,
getResearchHistory,
getReport,
getMarkdownExport,
terminateResearch,
deleteResearch,
clearResearchHistory,
openFileLocation,
saveRawConfig,
saveMainConfig,
saveSearchEnginesConfig,
saveCollectionsConfig,
saveApiKeysConfig,
saveLlmConfig,
postJSON,
getApiUrl,
getCsrfToken,
fetchWithErrorHandling,
fetchWithCsrfRecovery,
isAuthContextChanged,
// Exposed so the direct-safeFetch call sites (library/settings/etc.)
// can adopt the same 401->login behavior without duplicating the logic.
shouldRedirectToLoginOn401,
redirectToLogin
};
}