This is the multi-page printable view of this section. .
Reference
- 1: HTTP API
- 2: MCP tools
- 3: Configuration reference
- 4: Error codes
- 5: Glossary
Use this section when you need to look up exact behavior.
1 - HTTP API
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
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.
Tools marked In development have no documentation yet.
Health and namespaces
| Tool | What it does | Parameters |
|---|---|---|
cortrix_health | Checks that the Cortrix service is running and reachable | — |
cortrix_list_namespaces | Lists the namespaces you have access to | limit, offset |
cortrix_create_namespace | Creates a namespace | name* |
Query
| Tool | What it does | Parameters |
|---|---|---|
cortrix_query | Runs a semantic query over one or more namespaces | query*, top_k, namespaces, rerank |
cortrix_cross_ns_query | Queries across several namespaces | query*, namespaces*, top_k, rerank |
cortrix_query_explain | Runs a query and returns an explanation of the path it took | query*, top_k, namespaces, rerank |
For cortrix_query, top_k defaults to 5 and rerank defaults to true.
Documents
| Tool | What it does | Parameters |
|---|---|---|
cortrix_upload | Uploads document content for asynchronous processing and returns a task | content*, namespace, filename, metadata |
cortrix_async_upload | Uploads a larger document asynchronously and returns a task | content*, namespace, filename, metadata |
cortrix_batch_submit | Submits up to 100 documents to one namespace at once | namespace*, documents*, async_, on_duplicate |
cortrix_list_documents | Lists the documents in a namespace | namespace, limit, offset |
cortrix_document_status | Shows a document’s processing status and details | doc_id*, namespace |
cortrix_task_status | Shows the progress of an asynchronous upload task | task_id* |
cortrix_cancel_task | Cancels an asynchronous upload task | task_id* |
Directory watchers
| Tool | What it does | Parameters |
|---|---|---|
cortrix_add_watcher | Adds a watcher that imports the files in a directory automatically | data_dir*, namespace, recursive |
cortrix_list_watchers | Lists all watchers | — |
Memory
| Tool | What it does | Parameters |
|---|---|---|
cortrix_memory_create | Creates a memory | namespace*, content*, memory_type*, metadata |
cortrix_memory_list | Lists memories | namespace, memory_type, include_invalidated, limit, offset |
cortrix_memory_edit | Edits a memory’s content or metadata | memory_id*, namespace, content, metadata |
cortrix_memory_invalidate | Soft-deletes a memory | memory_id*, namespace, reason |
cortrix_memory_search | Runs a semantic search over conversation memory | query*, namespace, top_k |
cortrix_memory_search_filter | Searches memory filtered by memory type | query*, memory_type*, namespace, top_k |
cortrix_memory_opt_out | Opts a session out of memory, or revokes the opt-out | session_id*, opt_out, namespace, reason |
cortrix_memory_get_audit | Queries the memory audit records | memory_id, namespace, limit |
These tools are In development:
| Tool | What it does | Parameters |
|---|---|---|
cortrix_memory_extract | Extracts memories from a conversation in one call | messages*, namespace |
cortrix_memory_extract_trigger | Triggers memory extraction for a session manually | namespace, session_id |
cortrix_memory_revoke_fact | Revokes an automatically extracted fact | memory_id*, namespace |
Interactions and the operation log
| Tool | What it does | Parameters |
|---|---|---|
cortrix_log_interaction | Saves a conversation turn: the user’s question and the assistant’s answer | session_id*, query_text*, response_text*, namespace |
cortrix_list_interactions | Lists a user’s interactions | namespace*, user_id*, filter, limit, offset |
cortrix_list_operations | Queries the operation log | user_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.
| Tool | What it does | Parameters |
|---|---|---|
cortrix_admin_db_credential_register | Registers a database connection credential | name, dsn, expire_days, connection_ref, description |
cortrix_admin_db_import_run | Starts a database import | connection_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 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
| Key | Default | Description |
|---|---|---|
host | "127.0.0.1" | The address to listen on. Binding to a non-loopback address requires authentication to be on |
port | 8420 | The HTTP port |
thread_count | 4 | Worker threads. The recommended value is your CPU core count. Environment variable: CORTRIX_SERVER_THREADS |
auth
| Key | Default | Description |
|---|---|---|
enabled | false | Whether 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_at | 0 | Expiry time. 0 never expires |
log
| Key | Default | Description |
|---|---|---|
level | "info" | trace, debug, info, warn, error, critical, or off |
format | "text" | text or json |
output | "stdout" | stdout, stderr, or a file path |
namespace
| Key | Default | Description |
|---|---|---|
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
| Key | Default | Description |
|---|---|---|
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 |
dimension | 1024 | The vector dimension. Fixed at 1024 for bge-m3 and can’t be changed |
max_seq_length | 512 | The maximum tokens per encode |
execution_provider | "auto" | auto, cpu, coreml, or cuda. Environment variable: CORTRIX_EMBEDDING_EXECUTION_PROVIDER |
reranker
| Key | Default | Description |
|---|---|---|
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
| Key | Default | Description |
|---|---|---|
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
| Key | Default | Description |
|---|---|---|
candidate_multiplier | 3 | How many times top_k the candidate pool is, at least 1. Environment variable: CORTRIX_RETRIEVAL_CANDIDATE_MULTIPLIER |
max_candidates | 50 | The 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).
| Key | Default | Description |
|---|---|---|
worker_count | 2 | Threads processing in parallel. 2 to 4 is recommended |
chunk_size | 512 | The target number of tokens per text block |
chunk_overlap | 50 | Tokens shared between neighboring blocks |
embedding_batch_size | 1 | Blocks embedded per batch |
onnx_intra_threads | 4 | Intra-op threads for ONNX inference |
onnx_inter_threads | 1 | Parallel 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_s | 120 | Document parsing timeout, in seconds |
ocr_timeout_s | 3600 | OCR 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:
| Key | Description |
|---|---|
provider | openai, glm, claude, ollama, deepseek, or mock |
api_key | The provider’s API key |
model | The provider’s model identifier |
base_url | The API address |
A role counts as configured only when provider, api_key, and model are all set. See Configuration.
watch_dir
| Key | Default | Description |
|---|---|---|
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_enabled | true | When false, existing files are imported but later changes aren’t watched |
To manage watchers through the API, see Watch a directory.
memory
| Key | Default | Description |
|---|---|---|
default_ttl_seconds | 0 | How long memory is kept. 0 keeps it forever |
inject_recent_turns | 5 | How many recent turns to include when injecting context |
inject_max_tokens | 2000 | The token ceiling for injected context |
rag_fusion
| Key | Default | Description |
|---|---|---|
default_enabled | false | The global default for whether it’s on |
default_variant_count | 3 | How many query variants to generate |
default_rrf_k | 60 | The rank-fusion constant |
default_timeout_ms | 5000 | The 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.
| Key | Default | Description |
|---|---|---|
enabled | true | Whether the background garbage collection thread runs |
soft_delete_retention_days | 30 | Days a soft-deleted item is kept, during which it can be restored |
blob_gc_retention_days | 90 | Days a file is kept after hard delete before it’s physically removed |
scan_interval_hours | 24 | The interval between background scans |
max_purge_per_run | 10000 | The most files cleaned up in one run |
max_run_duration_minutes | 5 | The longest a single run can take |
dry_run | false | Scan without deleting, for testing and inspection |
immediate_purge_enabled | false | Turns on the immediate-purge API. Leave it false |
Environment variables for Docker
See Configuration.
4 - 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
| Field | Type | Description |
|---|---|---|
code | string | The error code |
message | string | A description for people. Don’t parse it in code. The structured details are in structured_data |
retryable | boolean | Whether a retry is worthwhile |
category | string | The error category. See the next table |
retry_after_ms | integer or null | The suggested wait before a retry, in milliseconds |
structured_data | object | Structured data about this error, for programs to use |
request_id | string | A server-generated request identifier for finding the request in logs. Some error responses include it |
Error categories
category | Meaning | What to do |
|---|---|---|
auth | An authentication or permission problem | Don’t retry. Check your credentials or permissions |
quota | A quota was exceeded | Slow down, or wait and try again |
transient | A temporary failure | Wait for retry_after_ms, then retry |
timeout | A timeout | Wait for retry_after_ms, then retry |
permanent | Something is wrong with the request itself | Don’t retry it unchanged. Fix the request |
Decide whether to retry
- Look at
retryablefirst. If it’sfalse, don’t retry. - For the wait time, use
retry_after_ms, then theRetry-Afterheader (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:
| Operation | Where the failures are |
|---|---|
| Cross-namespace query | meta.namespaces_failed[] |
| Batch document submit | meta.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.
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 code | Retryable | Category | Typical cause | What to do |
|---|---|---|---|---|
CX_ERR_NAMESPACE_NOT_FOUND | No | permanent | The namespace name is misspelled, or the namespace was deleted | Confirm the name with GET /namespaces, or create the namespace |
CX_ERR_NS_UNAUTHORIZED | No | auth | The API key has no access to this namespace | Read the namespaces you can’t access from structured_data.unauthorized_namespaces and query only the ones you can |
CX_ERR_NS_TIMEOUT | Yes | timeout | A query on one namespace timed out | Use the partial results you got, and optionally retry just that namespace |
CX_ERR_RATE_LIMIT | Yes | transient | The rate limit was exceeded. The v1.0.0-rc.2 server doesn’t emit this code | Wait for retry_after_ms and retry, or lower your request rate |
CX_ERR_AUTH_INVALID_API_KEY | No | auth | The API key is invalid or revoked | Use a different API key |
CX_ERR_INDEX_CORRUPT | No | permanent | The vector index is unavailable | Use the partial results and notify whoever operates the service |
These are the error codes that came up in testing for this documentation:
| Error code | HTTP status | When it appears |
|---|---|---|
CX_ERR_DEPRECATED_FIELD | 400 | A query request used the singular namespace |
CX_ERR_NS_NOT_FOUND | 404 | A file was uploaded to a namespace that doesn’t exist |
CX_ERR_ADMIN_LOOPBACK_REQUIRED | 403 | An admin endpoint was called from a non-loopback address |
CX_ERR_DISK_FULL | 507 | A 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:
| Field | Meaning |
|---|---|
x-cortrix-retryable | Whether this endpoint can usually be retried |
x-cortrix-retry-strategy | The suggested way to retry: exponential_backoff, linear, no_retry, or immediate |
x-cortrix-side-effects | The side-effect category: none, read_only, write, or destructive |
x-cortrix-auth-required | Whether authentication is required |
x-cortrix-auth-scope | The required scope: ns:read, ns:write, tenant:admin, or ops:admin |
x-cortrix-rate-limit | The rate limit, as count/period/scope |
x-cortrix-typical-latency | Estimated P50 and P99 latency |
These fields are design annotations in the spec, not measured results.
Next steps
5 - Glossary
These are the terms the Cortrix documentation uses. Each concept has exactly one name.
Product and positioning
| Term | Definition |
|---|---|
| access path | A way for an agent or application to use Cortrix: the HTTP API, MCP, the Python SDK, framework adapters, or the built-in Agent |
| Agent-native | Designed around agent data workflows: semantic processing, memory, and traceability are concerns of the shared storage layer |
| built-in Agent | The fixed-flow chat service that ships in the repository |
| framework adapter | The cortrix-skills package, which turns Cortrix tools into each agent framework’s native format |
| Quick Start | The path that starts Cortrix locally with Docker and runs a first query |
| semantic storage | A storage layer that connects information with the context an application needs to use it |
Data model
| Term | Definition |
|---|---|
| block | The smallest searchable unit, derived from a document or a memory record |
| document | Source material uploaded to Cortrix |
| event | A memory type. It decays over time |
| fact | A memory type. It doesn’t decay over time |
| interaction | One conversation turn: the user’s question and the assistant’s answer |
| memory | Structured long-term information. Its type is fact, preference, or event |
| metadata | Key-value information attached to a document, block, or memory |
| namespace | A logical collection boundary for documents, blocks, memory, and queries. It isn’t an authentication or tenant-security boundary |
| preference | A memory type. It doesn’t decay over time |
| session | A set of conversation turns grouped together |
| source | The original document a block belongs to |
Ingestion
| Term | Definition |
|---|---|
| batch submit | Submitting several documents in one request |
| chunking | Splitting text into blocks |
| database import | Importing the rows of a database table or query into a namespace |
| embedding | Turning text into a vector |
| enrichment | Using an LLM to add entities and summaries to ingested content |
| file upload | Uploading one file as multipart. It returns the document identifier right away |
| ingestion | Everything that happens to a document between upload and being searchable |
| inline upload | Submitting text content directly in a JSON request body. Processing is asynchronous |
| parsing | Turning a file into text |
| Semantic Processing Chain (SPC) | The ingestion pipeline: parsing, chunking, enrichment, embedding, and indexing |
| task | One asynchronous processing job. You can check its progress and cancel it |
| watcher | Tracks a directory and imports new files in it automatically |
Retrieval
| Term | Definition |
|---|---|
| candidate pool | The set of candidates fetched before reranking and truncation. It’s larger than top_k |
| coverage ratio | The share of requested namespaces that were queried successfully |
| cross-namespace query | Querying several namespaces at once and merging the results |
| dense retrieval | Looking up semantically similar content in the vector index |
| full-text search | Looking up content by keyword |
| fusion | Merging the results of several retrieval paths into one list by rank |
| hybrid search | Using several retrieval paths together and fusing their results |
| partial success | Returning the parts that succeeded when some sub-operations fail, with the failures described in meta |
| query | A retrieval request over one or more namespaces |
| rerank score | The relevance score given by the reranker model |
| reranking | Scoring each candidate with a cross-encoder model and reordering them |
| sparse retrieval | Looking up content with sparse vectors |
Memory operations
| Term | Definition |
|---|---|
| invalidation | Marking a memory as no longer valid while keeping the record |
| memory extraction | Extracting memories from conversations automatically |
| soft delete | Marking something deleted while keeping it restorable or traceable, without physically removing it |
Deployment and runtime
| Term | Definition |
|---|---|
| admin endpoint | A management interface that accepts loopback requests only |
| execution provider | The backend that runs a model: CPU, CoreML, or CUDA |
| garbage collection | The background process that removes deleted data in stages |
| LLM role | One use of an LLM, configured separately. There are five: semantic_llm, vision_llm, agent_llm, doc_summary_llm, and enricher_llm |
| local model | The embedding and reranking models that run on your machine and need no external service |
| loopback address | A network address reachable only from the same machine |
| model manifest | The file that records each model file’s source, size, and checksum |
| readiness check | The health check that confirms the API, the models, and the data are all available |
| volume | The Docker storage that holds persistent data |
Interfaces
| Term | Definition |
|---|---|
| authentication | Confirming who the caller is |
| error category | The classification of an error: auth, quota, transient, timeout, or permanent |
| structured error | An error response that carries code, retryable, category, and retry_after_ms |
| tenant | One unit of isolation in the multi-tenant model |
| tool | A callable operation that the MCP server or the framework adapters offer to an agent |
| trace | The record a call leaves on the server, which can be queried by session |
Status labels
| Term | Definition |
|---|---|
| In development | Present in part or being built. Not supported yet |
| Preview | Available and documented. Cortrix is in pre-release, so verify it in your own environment before production use |