Skip to content

This is the multi-page printable view of this section. .

Return to the regular view of this page.

Reference

Exact details of the HTTP API, MCP tools, configuration keys, and error codes.

Use this section when you need to look up exact behavior.

1 - HTTP API

The HTTP API reference, generated from the OpenAPI spec.

This reference is rendered from a filtered copy of api/openapi.yaml. The copy leaves out operations that this build doesn’t serve. An endpoint that appears in the spec isn’t necessarily available yet. For the status of each capability, see Compatibility and status.

OpenAPI specification — /docs/openapi/openapi.yaml

2 - MCP tools

Every tool the MCP server provides, with its parameters.

cortrix-mcp provides 31 tools in v1.0.0-rc.2. The tool names and parameters come from the tool list returned by a running MCP server.

A * after a parameter name means it’s required. A tool that isn’t given a namespace uses the default namespace set by the CORTRIX_NAMESPACE environment variable.

For installation and setup, see MCP server.

Note

Tools marked In development have no documentation yet.

Health and namespaces

ToolWhat it doesParameters
cortrix_healthChecks that the Cortrix service is running and reachable—
cortrix_list_namespacesLists the namespaces you have access tolimit, offset
cortrix_create_namespaceCreates a namespacename*

Query

ToolWhat it doesParameters
cortrix_queryRuns a semantic query over one or more namespacesquery*, top_k, namespaces, rerank
cortrix_cross_ns_queryQueries across several namespacesquery*, namespaces*, top_k, rerank
cortrix_query_explainRuns a query and returns an explanation of the path it tookquery*, top_k, namespaces, rerank

For cortrix_query, top_k defaults to 5 and rerank defaults to true.

Documents

ToolWhat it doesParameters
cortrix_uploadUploads document content for asynchronous processing and returns a taskcontent*, namespace, filename, metadata
cortrix_async_uploadUploads a larger document asynchronously and returns a taskcontent*, namespace, filename, metadata
cortrix_batch_submitSubmits up to 100 documents to one namespace at oncenamespace*, documents*, async_, on_duplicate
cortrix_list_documentsLists the documents in a namespacenamespace, limit, offset
cortrix_document_statusShows a document’s processing status and detailsdoc_id*, namespace
cortrix_task_statusShows the progress of an asynchronous upload tasktask_id*
cortrix_cancel_taskCancels an asynchronous upload tasktask_id*

Directory watchers

ToolWhat it doesParameters
cortrix_add_watcherAdds a watcher that imports the files in a directory automaticallydata_dir*, namespace, recursive
cortrix_list_watchersLists all watchers—

Memory

ToolWhat it doesParameters
cortrix_memory_createCreates a memorynamespace*, content*, memory_type*, metadata
cortrix_memory_listLists memoriesnamespace, memory_type, include_invalidated, limit, offset
cortrix_memory_editEdits a memory’s content or metadatamemory_id*, namespace, content, metadata
cortrix_memory_invalidateSoft-deletes a memorymemory_id*, namespace, reason
cortrix_memory_searchRuns a semantic search over conversation memoryquery*, namespace, top_k
cortrix_memory_search_filterSearches memory filtered by memory typequery*, memory_type*, namespace, top_k
cortrix_memory_opt_outOpts a session out of memory, or revokes the opt-outsession_id*, opt_out, namespace, reason
cortrix_memory_get_auditQueries the memory audit recordsmemory_id, namespace, limit

These tools are In development:

ToolWhat it doesParameters
cortrix_memory_extractExtracts memories from a conversation in one callmessages*, namespace
cortrix_memory_extract_triggerTriggers memory extraction for a session manuallynamespace, session_id
cortrix_memory_revoke_factRevokes an automatically extracted factmemory_id*, namespace

Interactions and the operation log

ToolWhat it doesParameters
cortrix_log_interactionSaves a conversation turn: the user’s question and the assistant’s answersession_id*, query_text*, response_text*, namespace
cortrix_list_interactionsLists a user’s interactionsnamespace*, user_id*, filter, limit, offset
cortrix_list_operationsQueries the operation loguser_id, namespace, action, action_in, start_time, end_time, limit, offset, sort_order

Admin

Admin tools require the server to accept the caller as an admin.

ToolWhat it doesParameters
cortrix_admin_db_credential_registerRegisters a database connection credentialname, dsn, expire_days, connection_ref, description
cortrix_admin_db_import_runStarts a database importconnection_ref*, namespace*, table, filter, sql

These two tools are In development.

Responses and errors

Every tool returns two layers, data and meta. For the response schema and the adapter’s own error codes, see MCP server.

3 - Configuration reference

Every key in config.yaml, with its default.

Every key in the configuration file is listed here. Defaults come from config.yaml.example in the v1.0.0-rc.2 repository.

For how to configure Cortrix and for common scenarios, see Configuration. When a key also has an environment variable, the environment variable wins.

server

KeyDefaultDescription
host"127.0.0.1"The address to listen on. Binding to a non-loopback address requires authentication to be on
port8420The HTTP port
thread_count4Worker threads. The recommended value is your CPU core count. Environment variable: CORTRIX_SERVER_THREADS

auth

KeyDefaultDescription
enabledfalseWhether API key authentication is on. With it off, only a loopback bind is accepted
api_keys[].key_hash—The SHA-256 of the key
api_keys[].tenant_id—The tenant the key belongs to
api_keys[].permissions—Permission bits: READ=1, WRITE=2, ADMIN=4. 7 is all of them
api_keys[].expires_at0Expiry time. 0 never expires

log

KeyDefaultDescription
level"info"trace, debug, info, warn, error, critical, or off
format"text"text or json
output"stdout"stdout, stderr, or a file path

namespace

KeyDefaultDescription
data_dir"./build/data"The data root, holding databases, the vector index, and files. A relative path is resolved from the directory of the cortrix-server binary

embedding

KeyDefaultDescription
model_path"./models/bge-m3/model.onnx"The embedding model path. Leave it empty to select the stub explicitly
tokenizer_path"./models/bge-m3/tokenizer.json"The tokenizer path
dimension1024The vector dimension. Fixed at 1024 for bge-m3 and can’t be changed
max_seq_length512The maximum tokens per encode
execution_provider"auto"auto, cpu, coreml, or cuda. Environment variable: CORTRIX_EMBEDDING_EXECUTION_PROVIDER

reranker

KeyDefaultDescription
model_dir"./models/bge-reranker-v2-m3"The reranker model directory. Leave it empty to select the stub explicitly. Environment variable: CORTRIX_RERANKER_MODEL_DIR
execution_provider"auto"auto, cpu, coreml, or cuda. Environment variable: CORTRIX_RERANKER_EXECUTION_PROVIDER

query_complexity

KeyDefaultDescription
model_dir"./models/query-complexity"The directory of the query-complexity classifier. If the model is absent, a heuristic is used instead. Environment variable: CORTRIX_QUERY_COMPLEXITY_MODEL_DIR

retrieval

KeyDefaultDescription
candidate_multiplier3How many times top_k the candidate pool is, at least 1. Environment variable: CORTRIX_RETRIEVAL_CANDIDATE_MULTIPLIER
max_candidates50The hard ceiling on the candidate pool, at least 1. Environment variable: CORTRIX_RETRIEVAL_MAX_CANDIDATES

See Performance tuning.

spc

The Semantic Processing Chain (SPC), the document processing pipeline. It supports PDF, DOCX, TXT, MD, CSV, JSON, and images (through OCR).

KeyDefaultDescription
worker_count2Threads processing in parallel. 2 to 4 is recommended
chunk_size512The target number of tokens per text block
chunk_overlap50Tokens shared between neighboring blocks
embedding_batch_size1Blocks embedded per batch
onnx_intra_threads4Intra-op threads for ONNX inference
onnx_inter_threads1Parallel ONNX inferences
python_bin"./scripts/ocr_venv/bin/python3.12"The Python used by the parsing scripts
parse_pdf_script"./scripts/parse_pdf.py"The PDF parsing script
parse_word_script"./scripts/parse_word.py"The Word parsing script
ocr_script"./scripts/run_ocr.py"The OCR script
parser_timeout_s120Document parsing timeout, in seconds
ocr_timeout_s3600OCR timeout, in seconds

LLM roles

The five roles semantic_llm, vision_llm, agent_llm, doc_summary_llm, and enricher_llm each have their own section with the same fields:

KeyDescription
provideropenai, glm, claude, ollama, deepseek, or mock
api_keyThe provider’s API key
modelThe provider’s model identifier
base_urlThe API address

A role counts as configured only when provider, api_key, and model are all set. See Configuration.

watch_dir

KeyDefaultDescription
data_dir""The absolute path of a local directory to watch. Empty turns it off
namespace_name"local"The namespace files are imported into. It’s created if it doesn’t exist
watch_enabledtrueWhen false, existing files are imported but later changes aren’t watched

To manage watchers through the API, see Watch a directory.

memory

KeyDefaultDescription
default_ttl_seconds0How long memory is kept. 0 keeps it forever
inject_recent_turns5How many recent turns to include when injecting context
inject_max_tokens2000The token ceiling for injected context

rag_fusion

KeyDefaultDescription
default_enabledfalseThe global default for whether it’s on
default_variant_count3How many query variants to generate
default_rrf_k60The rank-fusion constant
default_timeout_ms5000The timeout for the LLM to generate variants
llm_prompt_template_zh"default-zh"The Chinese prompt template
llm_prompt_template_en"default-en"The English prompt template

RAG-Fusion is off by default and runs only when an LLM role is configured. The configuration template notes that the server doesn’t read the keys in this section yet, so the built-in defaults are what’s actually used.

gc

Garbage collection runs in three stages: soft delete, hard delete, and file cleanup.

KeyDefaultDescription
enabledtrueWhether the background garbage collection thread runs
soft_delete_retention_days30Days a soft-deleted item is kept, during which it can be restored
blob_gc_retention_days90Days a file is kept after hard delete before it’s physically removed
scan_interval_hours24The interval between background scans
max_purge_per_run10000The most files cleaned up in one run
max_run_duration_minutes5The longest a single run can take
dry_runfalseScan without deleting, for testing and inspection
immediate_purge_enabledfalseTurns on the immediate-purge API. Leave it false

Environment variables for Docker

See Configuration.

4 - Error codes

The structure of an error response, the error categories, and common error codes.

Cortrix error responses are designed for programs and agents. Whether to retry, how long to wait, and what kind of error it is each have a dedicated field, so you never need to parse the message text.

Error response structure

{
  "error": {
    "code": "CX_ERR_DEPRECATED_FIELD",
    "message": "Field 'namespace' is deprecated, use 'namespaces' array instead",
    "retryable": false,
    "category": "permanent",
    "retry_after_ms": null,
    "structured_data": {
      "deprecated_field": "namespace",
      "use_instead": "namespaces"
    }
  }
}
FieldTypeDescription
codestringThe error code
messagestringA description for people. Don’t parse it in code. The structured details are in structured_data
retryablebooleanWhether a retry is worthwhile
categorystringThe error category. See the next table
retry_after_msinteger or nullThe suggested wait before a retry, in milliseconds
structured_dataobjectStructured data about this error, for programs to use
request_idstringA server-generated request identifier for finding the request in logs. Some error responses include it

Error categories

categoryMeaningWhat to do
authAn authentication or permission problemDon’t retry. Check your credentials or permissions
quotaA quota was exceededSlow down, or wait and try again
transientA temporary failureWait for retry_after_ms, then retry
timeoutA timeoutWait for retry_after_ms, then retry
permanentSomething is wrong with the request itselfDon’t retry it unchanged. Fix the request

Decide whether to retry

  1. Look at retryable first. If it’s false, don’t retry.
  2. For the wait time, use retry_after_ms, then the Retry-After header (in seconds), then exponential backoff.

The Python SDK has this logic built in. See Python SDK.

Partial success

Some operations return HTTP 200 even when part of the work failed. The details are in the response’s meta, and every failure carries the same structured fields:

OperationWhere the failures are
Cross-namespace querymeta.namespaces_failed[]
Batch document submitmeta.failed[]

A query can also succeed with degraded results, reported in meta.warnings with the same code and category fields and, when applicable, retry_after_ms. See Check for degraded results for the warning codes and what to do.

When an asynchronous task fails, the failure appears in the task progress as error_code and error_msg, not in the response to the request that submitted it.

So don’t judge whether an operation fully succeeded from the HTTP status code alone.

How error codes are named

The spec requires every error code to use the CX_ERR_ prefix, which lets you filter Cortrix errors in logs and monitoring.

Note

In testing, some errors in v1.0.0-rc.2 used generic codes without the prefix, such as INVALID_ARGUMENT and NOT_FOUND. When you handle errors, go by retryable and category, and don’t assume every code starts with CX_ERR_.

Common error codes

These are the high-frequency codes registered in the spec, with the suggested way to handle each:

Error codeRetryableCategoryTypical causeWhat to do
CX_ERR_NAMESPACE_NOT_FOUNDNopermanentThe namespace name is misspelled, or the namespace was deletedConfirm the name with GET /namespaces, or create the namespace
CX_ERR_NS_UNAUTHORIZEDNoauthThe API key has no access to this namespaceRead the namespaces you can’t access from structured_data.unauthorized_namespaces and query only the ones you can
CX_ERR_NS_TIMEOUTYestimeoutA query on one namespace timed outUse the partial results you got, and optionally retry just that namespace
CX_ERR_RATE_LIMITYestransientThe rate limit was exceeded. The v1.0.0-rc.2 server doesn’t emit this codeWait for retry_after_ms and retry, or lower your request rate
CX_ERR_AUTH_INVALID_API_KEYNoauthThe API key is invalid or revokedUse a different API key
CX_ERR_INDEX_CORRUPTNopermanentThe vector index is unavailableUse the partial results and notify whoever operates the service

These are the error codes that came up in testing for this documentation:

Error codeHTTP statusWhen it appears
CX_ERR_DEPRECATED_FIELD400A query request used the singular namespace
CX_ERR_NS_NOT_FOUND404A file was uploaded to a namespace that doesn’t exist
CX_ERR_ADMIN_LOOPBACK_REQUIRED403An admin endpoint was called from a non-loopback address
CX_ERR_DISK_FULL507A file was uploaded while the data disk was at least 90% full. See Troubleshooting
CX_ERR_SPC_PROCESS_FAILED—An asynchronous processing task failed. It appears in the task progress

For the MCP adapter’s own error codes, see MCP server.

Agent hints in the OpenAPI spec

The OpenAPI spec annotates every endpoint with a set of x-cortrix-* extension fields, so an agent knows what kind of endpoint it’s dealing with before it calls it:

FieldMeaning
x-cortrix-retryableWhether this endpoint can usually be retried
x-cortrix-retry-strategyThe suggested way to retry: exponential_backoff, linear, no_retry, or immediate
x-cortrix-side-effectsThe side-effect category: none, read_only, write, or destructive
x-cortrix-auth-requiredWhether authentication is required
x-cortrix-auth-scopeThe required scope: ns:read, ns:write, tenant:admin, or ops:admin
x-cortrix-rate-limitThe rate limit, as count/period/scope
x-cortrix-typical-latencyEstimated P50 and P99 latency

These fields are design annotations in the spec, not measured results.

Next steps

5 - Glossary

The terms used in the Cortrix documentation.

These are the terms the Cortrix documentation uses. Each concept has exactly one name.

Product and positioning

TermDefinition
access pathA way for an agent or application to use Cortrix: the HTTP API, MCP, the Python SDK, framework adapters, or the built-in Agent
Agent-nativeDesigned around agent data workflows: semantic processing, memory, and traceability are concerns of the shared storage layer
built-in AgentThe fixed-flow chat service that ships in the repository
framework adapterThe cortrix-skills package, which turns Cortrix tools into each agent framework’s native format
Quick StartThe path that starts Cortrix locally with Docker and runs a first query
semantic storageA storage layer that connects information with the context an application needs to use it

Data model

TermDefinition
blockThe smallest searchable unit, derived from a document or a memory record
documentSource material uploaded to Cortrix
eventA memory type. It decays over time
factA memory type. It doesn’t decay over time
interactionOne conversation turn: the user’s question and the assistant’s answer
memoryStructured long-term information. Its type is fact, preference, or event
metadataKey-value information attached to a document, block, or memory
namespaceA logical collection boundary for documents, blocks, memory, and queries. It isn’t an authentication or tenant-security boundary
preferenceA memory type. It doesn’t decay over time
sessionA set of conversation turns grouped together
sourceThe original document a block belongs to

Ingestion

TermDefinition
batch submitSubmitting several documents in one request
chunkingSplitting text into blocks
database importImporting the rows of a database table or query into a namespace
embeddingTurning text into a vector
enrichmentUsing an LLM to add entities and summaries to ingested content
file uploadUploading one file as multipart. It returns the document identifier right away
ingestionEverything that happens to a document between upload and being searchable
inline uploadSubmitting text content directly in a JSON request body. Processing is asynchronous
parsingTurning a file into text
Semantic Processing Chain (SPC)The ingestion pipeline: parsing, chunking, enrichment, embedding, and indexing
taskOne asynchronous processing job. You can check its progress and cancel it
watcherTracks a directory and imports new files in it automatically

Retrieval

TermDefinition
candidate poolThe set of candidates fetched before reranking and truncation. It’s larger than top_k
coverage ratioThe share of requested namespaces that were queried successfully
cross-namespace queryQuerying several namespaces at once and merging the results
dense retrievalLooking up semantically similar content in the vector index
full-text searchLooking up content by keyword
fusionMerging the results of several retrieval paths into one list by rank
hybrid searchUsing several retrieval paths together and fusing their results
partial successReturning the parts that succeeded when some sub-operations fail, with the failures described in meta
queryA retrieval request over one or more namespaces
rerank scoreThe relevance score given by the reranker model
rerankingScoring each candidate with a cross-encoder model and reordering them
sparse retrievalLooking up content with sparse vectors

Memory operations

TermDefinition
invalidationMarking a memory as no longer valid while keeping the record
memory extractionExtracting memories from conversations automatically
soft deleteMarking something deleted while keeping it restorable or traceable, without physically removing it

Deployment and runtime

TermDefinition
admin endpointA management interface that accepts loopback requests only
execution providerThe backend that runs a model: CPU, CoreML, or CUDA
garbage collectionThe background process that removes deleted data in stages
LLM roleOne use of an LLM, configured separately. There are five: semantic_llm, vision_llm, agent_llm, doc_summary_llm, and enricher_llm
local modelThe embedding and reranking models that run on your machine and need no external service
loopback addressA network address reachable only from the same machine
model manifestThe file that records each model file’s source, size, and checksum
readiness checkThe health check that confirms the API, the models, and the data are all available
volumeThe Docker storage that holds persistent data

Interfaces

TermDefinition
authenticationConfirming who the caller is
error categoryThe classification of an error: auth, quota, transient, timeout, or permanent
structured errorAn error response that carries code, retryable, category, and retry_after_ms
tenantOne unit of isolation in the multi-tenant model
toolA callable operation that the MCP server or the framework adapters offer to an agent
traceThe record a call leaves on the server, which can be queried by session

Status labels

TermDefinition
In developmentPresent in part or being built. Not supported yet
PreviewAvailable and documented. Cortrix is in pre-release, so verify it in your own environment before production use