Settings

Project Settings expose a typed registry of configuration knobs (extraction defaults, copilot behavior, model selection, etc.). The registry defines each setting’s default; user overrides are stored per-project and merged at read time. Secret-typed settings are returned with a mask placeholder, and sending that placeholder back is treated as “no change”. Setting keys come from the registry as-is. Most use UPPER_SNAKE_CASE (e.g. EXTRACTION_DEFAULT_METHOD, COPILOT_TEMPERATURE), with a few historical lowercase keys (e.g. copilot_model). All values are persisted as strings, so when sending bools or numbers, stringify them ("true", "0.7"). Categories defined by the registry: copilot, agents, tools, knowledge-indexing, knowledge-retrieval, compaction, sources.

Common Patterns

Use GET to discover the full set of settings (with their defaults, current values, types, and category metadata). Use PUT for bulk updates from a settings UI. Use DELETE on a key to revert a single override; use reset-category to revert an entire group at once.

GET /api/settings

Return every setting in the registry with its default value, current override (if any), category, type, and (for secret settings) a masked representation. Category metadata accompanies the response so a UI can render labels and grouping.

response = requests.get(f"{BASE_URL}/api/settings", headers=headers)

const res = await fetch(`${BASE_URL}/api/settings`, { headers });

curl '{BASE_URL}/api/settings' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

PUT /api/settings

Bulk-update overrides. The body is { "settings": { key: value, ... } }. Each value is validated against its registry definition; on any failure the whole request is rejected with per-key errors and nothing is written. For secret settings, sending back the mask placeholder unchanged is silently skipped (so a UI can round-trip the full settings object without leaking or clobbering secrets).

{
  "settings": {
    "EXTRACTION_DEFAULT_METHOD": "mistral",
    "COPILOT_TEMPERATURE": "0.5"
  }
}

requests.put(f"{BASE_URL}/api/settings", headers=headers, json={"settings": {"EXTRACTION_DEFAULT_METHOD": "mistral"}})

await fetch(`${BASE_URL}/api/settings`, { method: "PUT", headers, body: JSON.stringify({ settings: { EXTRACTION_DEFAULT_METHOD: "mistral" } }) });

curl -X PUT '{BASE_URL}/api/settings' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"settings": {"EXTRACTION_DEFAULT_METHOD": "mistral"}}'

DELETE /api/settings/

Remove a single override, reverting that setting to its registry default. Returns the key and the default value (empty string for secret-typed settings).

string

required

A registry key. Unknown keys return 404.

requests.delete(f"{BASE_URL}/api/settings/EXTRACTION_DEFAULT_METHOD", headers=headers)

await fetch(`${BASE_URL}/api/settings/EXTRACTION_DEFAULT_METHOD`, { method: "DELETE", headers });

curl -X DELETE '{BASE_URL}/api/settings/EXTRACTION_DEFAULT_METHOD' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}"

POST /api/settings/reset-category

Remove every override in a category at once. Returns the list of keys that were reset.

string

required

One of the registry categories: copilot, agents, tools, knowledge-indexing, knowledge-retrieval, compaction, sources. Unknown categories return 400.

{ "category": "copilot" }

requests.post(f"{BASE_URL}/api/settings/reset-category", headers=headers, json={"category": "copilot"})

await fetch(`${BASE_URL}/api/settings/reset-category`, { method: "POST", headers, body: JSON.stringify({ category: "copilot" }) });

curl -X POST '{BASE_URL}/api/settings/reset-category' -H "apikey: {API_KEY}" -H "Authorization: Bearer {API_KEY}" -H "Content-Type: application/json" -d '{"category": "copilot"}'

Registry keys reference

A high-level map of what’s in the registry. The authoritative source for current defaults, types, and validation rules is GET /api/settings against your project. These tables tell you what each key controls so you can find the right knob without round-tripping.

copilot (8 keys)

Key	Controls
`copilot_model`	LLM used by the workflow copilot (one of `COPILOT_MODEL_OPTIONS`). Default `gpt-5.2`.
`COPILOT_TEMPERATURE`	Sampling temperature for the copilot ReAct loop. Default `0.7`.
`COPILOT_MAX_STEPS`	Max ReAct iterations before the copilot is forced to respond. Default `25`.
`MAX_BLOCK_NAME_LEN`	Block display names truncated to this length before injection into the prompt.
`MAX_CONFIG_VALUE_LEN`	Single config-value truncation cap (e.g., a large system prompt).
`MAX_TOTAL_STATE_LEN`	Hard cap on the total serialized workflow state passed to the copilot.
`MAX_CONFIG_DEPTH`	Recursion depth limit when truncating nested config dicts.
`SYSTEM_PROMPT_TRUNCATE`	Char limit when the copilot fetches an agent’s system prompt via `get_asset_details`.

agents (3 keys)

Key	Controls
`AGENT_DEFAULT_MODEL`	Model used when an agent row has no model set.
`DEFAULT_MAX_CONTEXT_TOKENS`	Context token budget for RAG retrievals when not overridden per request.
`DELEGATE_MAX_STEPS`	ReAct step cap for sub-agent (delegate tool) runs.

tools (12 keys)

Key	Controls
`CUSTOM_TOOL_TIMEOUT`	HTTP timeout for Custom Tool calls. Default `30`.
`MCP_TOOL_TIMEOUT`	Timeout for MCP `tools/call` requests. Default `30`.
`MAX_TOOL_OUTPUT_LENGTH`	Custom Tool response char cap. Default `10000`.
`DEFAULT_MAX_RESULT_CHARS`	Outer truncation cap applied after tool execution. Default `50000`.
`EXA_API_KEY`	Required for `web_search` builtin. Secret.
`FIRECRAWL_API_KEY`	Required for `web_scrape` builtin. Secret.
`FIRECRAWL_API_BASE`	Override the Firecrawl endpoint (self-hosted Firecrawl).
`VISION_MODEL`	Model used for `web_scrape include_images: true`. Default `gpt-4.1-mini`.
`WEB_SCRAPE_MAX_CHARS`	Per-page char cap for `web_scrape`. Default `200000`.
`WEB_SCRAPE_MAX_IMAGES`	Image-analysis count limit per scrape.
`VISION_TIMEOUT`	Per-image vision call timeout.
`VISION_MAX_WORKERS`	Concurrent vision-call worker pool.

knowledge-indexing (41 keys)

Covers chunking, embedding model selection, PageIndex tree-search params, GraphIndex enrichment, Doc2JSON extraction, full-document strategy, and BM25 indexing. Key families:

Chunk-embed strategy: CHUNK_EMBED_DEFAULT_CHUNK_SIZE, CHUNK_EMBED_DEFAULT_OVERLAP, CHUNK_EMBED_EMBEDDING_MODEL
PageIndex strategy (16 keys): PAGEINDEX_INDEXING_MODEL, PAGEINDEX_LLM_MAX_CONCURRENT, PAGEINDEX_TOC_*, PAGEINDEX_MAX_*, PAGEINDEX_MIN_*, PAGEINDEX_SUMMARY_TOKEN_THRESHOLD, PAGEINDEX_DOC_DESCRIPTION_MAX_TOKENS
GraphIndex strategy (8 keys): GRAPHINDEX_INDEXING_MODEL, GRAPHINDEX_ENRICHMENT_MODEL, GRAPHINDEX_EMBEDDING_MODEL, GRAPHINDEX_ENRICHMENT_MAX_*
Full-document strategy (4 keys): FULLDOC_SUMMARY_MODEL, FULLDOC_EMBEDDING_MODEL, FULLDOC_SUMMARY_INPUT_CHARS, FULLDOC_SUMMARY_MAX_TOKENS
Doc2JSON strategy (8 keys): DOC2JSON_* for window size, overlap, extraction model, image use, retries
Cross-cutting: EXTRACTION_DEFAULT_METHOD (mistral/paddleocr/lighton/opendataloader/fitz/pdfplumber/auto), EMBEDDING_MAX_TOKENS_PER_BATCH, BM25_AUTO_INDEXING

knowledge-retrieval (19 keys)

Key	Controls
`KB_DEFAULT_TOP_K`	Default `top_k` for KB search when not specified per request.
`KB_DEFAULT_MAX_CONTEXT_TOKENS`	Default context token budget for retrieval.
`DEFAULT_IMAGE_DELIVERY`	How images are returned in multimodal retrieval.
`HYBRID_DEFAULT_VECTOR_WEIGHT`	Vector vs. sparse weight in hybrid search.
`RERANKER_DEFAULT_MODEL`	Default reranker (Cohere/Jina/Voyage/ZeroEntropy).
`RERANKER_CANDIDATE_COUNT`	Number of candidates fetched before reranking.
`QUERY_ENRICHMENT_DEFAULT_MODEL`	Model used to rewrite/expand user queries before retrieval.
`QUERY_ENRICHMENT_TEMPERATURE`	Sampling temperature for query enrichment.
`METADATA_ENRICHMENT_*` (7 keys)	LLM model, max tokens, concurrency, batch size, retry, image, char limits for chunk metadata enrichment.
`PAGEINDEX_RETRIEVAL_MODEL`	Retrieval-time model for PageIndex tree search.
`MAX_SEARCH_WORKERS`	Concurrent retrieval worker pool.
`DROPPED_ITEM_TEXT_LIMIT`	Char limit when logging dropped retrieval items for debugging.

compaction (5 keys)

Key	Controls
`DEFAULT_COMPACTION_MODEL`	LLM used to summarize older session messages when context grows past budget.
`COMPACTION_KEEP_LAST_N`	Number of most recent messages preserved verbatim.
`CHARS_PER_TOKEN`	Heuristic char→token ratio used in budget calculations.
`COMPACTION_MAX_OUTPUT_TOKENS`	Output cap for the compaction summary.
`COMPACTION_BUFFER`	Token buffer kept free after compaction.

sources (4 keys)

Key	Controls
`URL_IMPORT_MAX_PAGES`	Hard cap on pages crawled when adding a URL source with crawl enabled.
`URL_IMPORT_MAX_IMAGES_PER_PAGE`	Per-page image-extraction cap.
`URL_IMPORT_CRAWL_MAX_DEPTH`	Max link-following depth for crawl.
`URL_IMPORT_IMAGE_MAX_SIZE_MB`	Per-image size limit before skip.

There are 92 registered keys total. GET /api/settings is the authoritative live view.

Error Responses

Settings routes return {"error": "<message>"} (PUT also includes details with per-key errors). The codes below are the documentation labels for each failure mode.

Status	Description
400	One or more setting values failed registry validation; PUT response includes a `details` map of per-key errors
400	The given category is not in the registry (`reset-category`)
400	No settings provided (PUT body has empty `settings` object)
404	The given key is not in the registry (DELETE)

Getting Started

Concepts

Guides

API Reference

Common Patterns

GET /api/settings

PUT /api/settings

DELETE /api/settings/

POST /api/settings/reset-category

Registry keys reference

copilot (8 keys)

agents (3 keys)

tools (12 keys)

knowledge-indexing (41 keys)

knowledge-retrieval (19 keys)

compaction (5 keys)

sources (4 keys)

Error Responses

​Common Patterns

​GET /api/settings

​PUT /api/settings

​DELETE /api/settings/

​POST /api/settings/reset-category

​Registry keys reference

​copilot (8 keys)

​agents (3 keys)

​tools (12 keys)

​knowledge-indexing (41 keys)

​knowledge-retrieval (19 keys)

​compaction (5 keys)

​sources (4 keys)

​Error Responses

Common Patterns

GET /api/settings

PUT /api/settings

DELETE /api/settings/

POST /api/settings/reset-category

Registry keys reference

copilot (8 keys)

agents (3 keys)

tools (12 keys)

knowledge-indexing (41 keys)

knowledge-retrieval (19 keys)

compaction (5 keys)

sources (4 keys)

Error Responses