This is the multi-page printable view of this section. .
Guides
- 1: Upload documents
- 2: Query and rerank
- 3: Work with memory
- 4: Watch a directory
- 5: Import from a database
Each guide covers one task, with commands you can copy and the output to expect.
1 - Upload documents
On this page you’ll create a namespace, upload documents in two different ways, confirm they’ve been processed, and learn how to delete one.
The output on this page is real output from v1.0.0-rc.2. It differs from the OpenAPI spec in several places: upload results use the statuses pending and skipped where the spec lists queued, updating, and unchanged; a finished task reports completed where the spec says ready; source_type can be file, which isn’t in the spec’s list; timestamps are epoch milliseconds; and the validation error shown at the end has a code, request_id, and timestamp that don’t match the spec’s patterns. Write client code against what the server returns, and recheck after an upgrade.
Prerequisites
- A running Cortrix service. See the Quickstart.
curl.
The examples target the service the quickstart starts, which has no authentication. When you connect to a service with authentication turned on, send the X-API-Key header with each request.
Two ways to upload
| File upload | Inline upload | |
|---|---|---|
| Endpoint | POST /api/v1/namespaces/{ns}/documents | POST /api/v1/documents |
| Request body | multipart/form-data | JSON |
| Best for | Uploading a file, including binary files | Text your program already has in memory |
| Returns | A doc_id right away | A task_id; processing is asynchronous |
| If the namespace doesn’t exist | 404 right away | The request is accepted and the task fails later |
Either way, the content goes through the same pipeline: parsing, chunking, embedding, and indexing.
Steps
Create a namespace
Upload a file
First create a text file:
Upload it as multipart. file is required. title and metadata (a JSON string) are optional:
Uploading a file with the same content again doesn’t reprocess it. Cortrix detects the duplicate by content hash and returns HTTP 200 with the same doc_id:
Upload inline content
namespace and content are required. filename and metadata are optional:
The service returns HTTP 202 and a task:
Check task progress
Look up the task with the task_id from the previous step:
A status of completed with error_code set to null means processing succeeded. meta.agent_decision_hint tells an agent what to do next.
An inline upload returns 202 even when the namespace doesn’t exist. The error shows up only in the task progress: error_code is CX_ERR_SPC_PROCESS_FAILED and meta.agent_decision_hint is inspect_error_code. So always check task progress after an inline upload. Don’t rely on the upload request succeeding.
Confirm the documents are ready
Queries can find a document once its status is ready. The list supports paging with limit (default 50, maximum 200) and offset.
Get a single document
Documents are stored per namespace, so pass namespace when you fetch one:
Delete a document
A successful delete returns HTTP 204 with no body. The document and all of its blocks disappear from the list and from query results.
This is a soft delete: the document can still be restored during a retention period set by gc.soft_delete_retention_days. The default is 30 days, and 0 means delete immediately. After the retention period, garbage collection removes it permanently.
Batch submit
POST /api/v1/documents/batch submits 1 to 100 documents to one namespace in a single request. Each accepted document becomes an asynchronous task.
This endpoint uses partial-success semantics: it returns HTTP 200 even if some documents fail. Accepted documents are in results[], failures are in meta.failed[], and every failure carries structured error fields.
For the full request and response shapes, see the HTTP API reference.
When something goes wrong
Error responses share one structure, so you can decide whether to retry from retryable and category. For example, creating a namespace without name:
Next steps
- Query and rerank: query the documents you just uploaded.
- Python SDK: do the same thing with
client.documents.upload(). - HTTP API reference
2 - Query and rerank
On this page you’ll query one namespace and then several, learn to read the scores and metadata in a response, and see what to do when part of a query fails.
Prerequisites
- A running Cortrix service. See the Quickstart.
- A namespace with processed documents. This page reuses the
guidenamespace from Upload documents.
Run a query
Every query goes through one endpoint, POST /api/v1/query. query and namespaces are required:
The response has two parts, meta and results. Only the key fields of results are shown here:
The refund policy, which is relevant to the question, comes first with a rerank score of 0.824. The unrelated shipping policy gets a rerank score of 0.
Request parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
query | string | Required | The query text |
namespaces | string array | Required | The namespaces to search |
top_k | integer | 10 | How many results to return. The minimum is 1 |
rerank | boolean | true | Whether to reorder candidates with the reranker model |
include_sources | boolean | — | When true, results include source information |
filter | object | — | Filter conditions |
For the full request shape, see the HTTP API reference.
Use the plural namespaces array. A singular namespace is rejected:
Read the results
Each result is a block:
| Field | Meaning |
|---|---|
content | The block’s text |
namespace | The namespace the block belongs to |
metadata.source_path | The original filename of the source document |
rerank_score | The relevance score from the reranker model |
score | The score after fusing the retrieval paths |
Use rerank_score to judge whether a result is relevant to the question. score is the fused score used for ordering. Its values are small and aren’t a good absolute measure of relevance.
Query across namespaces
List several namespaces in namespaces, and the results are merged into one ranked list:
Each result’s namespace field tells you where it came from. Use ["*"] to query every namespace you have access to, up to 100.
Handle partial failure
When you query across namespaces, the request still returns HTTP 200 even if some namespaces fail. Check meta to see whether the result is complete:
Here nope doesn’t exist, and the response meta looks like this. Note that a missing or misspelled namespace is reported as CX_ERR_INDEX_CORRUPT, not as a not-found error:
Don’t judge completeness from the HTTP status code alone. A coverage_ratio below 1 means the results cover only some of the namespaces. Every entry in namespaces_failed carries retryable and category, which you can use to decide whether to retry.
Turn off reranking
Set rerank to false to skip reranking:
In testing, the response still carried a rerank_score field with reranking off, but with completely different values. In the example above, the first result went from 0.824 to 0.033. Don’t compare scores across the two modes.
The response also carries a CX_WARN_RERANK_DISABLED warning.
For when reranking helps and when it doesn’t, see When to rerank.
Check for degraded results
meta.warnings is an array of JSON objects with string fields code, reason, and category; some entries also include an integer retry_after_ms in milliseconds. These warnings don’t change the HTTP status: the response still returns HTTP 200 with results.
For example, a request with "rerank": false adds this entry to meta.warnings:
| Code | When it appears | reason | category | retry_after_ms | What to do |
|---|---|---|---|---|---|
CX_WARN_RERANK_DISABLED | The request sets "rerank": false. Ordering uses the fused retrieval score instead of the reranker model. | rerank_disabled | permanent | — | Expected when you asked for it. Don’t retry. Set rerank to true or omit it if you want reranked order. |
CX_WARN_LLM_RERANK_DEGRADED | The request sets "llm_rerank": true, a query-time LLM is configured, and there are at least two results. LLM calls fail, time out, or return unusable rankings, leaving a window without any usable vote. | llm_rerank_degraded | transient | 1000 | Results are usable and keep their order from before LLM reranking, never a partial LLM order. If LLM ordering matters, wait retry_after_ms and send the same request again. |
CX_WARN_RAG_FUSION_DEGRADED | The request sets "rag_fusion": true, a query-time LLM is configured, the query takes the multi-query path, and the LLM call that generates query variants fails. | rag_fusion_degraded | transient | 5000 | Results are usable but come from the original query alone, without variants. To get fused results, wait retry_after_ms and retry. |
The two LLM warnings report a failure of a step that ran. A missing warning doesn’t prove the step ran. To confirm, use ?explain=true and look for llm_rerank or rag_fusion under explain.llm_dependent_features; each key is present only when that step ran.
See how a query ran
Add ?explain=true and the response gains an explain section describing the path the query took:
The output is shortened. The full object has more fields, including ns_id, routing_decision_source, crag_verdict, crag_score, and llm_dependent_features.
rrf_path_counts shows that this query used both vector search (dense) and full-text search (fts5), and that the two result sets were then fused and ranked.
Next steps
- Work with memory
- Python SDK: run the same query with
client.search(). - HTTP API reference
3 - Work with memory
On this page you’ll write memories explicitly through the API, then list, edit, and delete them.
The output on this page is real output from v1.0.0-rc.2. It differs from the OpenAPI spec in several places: a memory’s status is active where the spec lists valid and invalidated; the default page_size is 50 where the spec says 20; and the responses to editing and deleting a memory have a different shape, and need an ns parameter the spec doesn’t declare.
Prerequisites
- A running Cortrix service. See the Quickstart.
- A namespace to hold the memories. This page uses
assistant:
Memory types
| Type | Meaning |
|---|---|
fact | A fact |
preference | A preference |
event | An event. Event memories decay over time, while facts and preferences don’t |
Write a memory
namespace, content, and memory_type are required. metadata is optional:
A memory written this way is an explicit memory. It isn’t validated by an LLM.
List memories
Query parameters:
| Parameter | Description |
|---|---|
namespace | Required |
memory_type | List only one type: fact, preference, or event |
include_invalidated | When true, also return invalidated memories. The default is false |
limit, offset | Paging |
Edit a memory
An edit doesn’t overwrite the original. Cortrix creates a new memory and marks the old one invalidated:
The edit request body must include both ns and content, or the request returns 400 ns + content are required. The OpenAPI spec doesn’t list ns in this endpoint’s request body, so this page follows the tested behavior.
Delete a memory
Deleting a memory is a soft delete. The memory is marked invalidated, but it’s always kept and never physically removed. Pass the namespace as the ns query parameter:
Invalidated memories don’t appear in the list by default. Add include_invalidated=true to see them:
Sessions
A memory session groups a set of conversation turns. namespace is required when you create one:
To write a turn to a session, use POST /api/v1/memory/sessions/{session_id}/interactions. namespace, query_text, and response_text are required.
In development
| Capability | Status |
|---|---|
| Automatic memory extraction from conversations | In development. Not supported yet |
| Automatic handling of contradicting memories | In development. Not supported yet |
Known limitation
POST /api/v1/memory/search requires query, namespace, and user_id. In testing, it didn’t return memories written explicitly through POST /api/v1/memory, and a regular query against the same namespace didn’t return them either. To read explicit memories, use the list endpoint above.
Next steps
4 - Watch a directory
On this page you’ll have Cortrix watch a directory: files already in it are imported into a namespace you choose, and files you add later are imported automatically.
Prerequisites
- A running Cortrix service. See the Quickstart.
- The directory must be on a filesystem the Cortrix server process can reach. When Cortrix runs in Docker, that means a path inside the container, not a path on the host.
The examples use a directory under the /data volume inside the container. To watch a directory on the host, mount it into the container first.
Steps
Prepare a directory and a namespace
Create a directory in the container and put a file in it. You can find the container name with docker ps:
Create the namespace that receives the files:
Add a watcher
path and target_namespaces are required. recursive defaults to true, which includes subdirectories:
target_namespaces can list several namespaces. Cortrix creates only one system-level watcher per directory and fans file changes out to every namespace subscribed to it.
Confirm existing files were imported
After a few seconds, list the documents in the namespace:
Documents that come from a watcher have a source_type of watch_dir, and filename is the file’s full path.
Confirm new files are imported automatically
Add another file to the directory:
After a few seconds, list the documents again. total is now 2, and the new file’s status is ready.
List and remove watchers
List all watchers:
Remove a watcher, along with all of its namespace subscriptions:
A successful removal returns HTTP 204.
Removing a watcher also deletes the documents it imported from that directory. If you want to keep them, don’t remove the watcher.
Known issue
The OpenAPI spec lists GET /api/v1/watch/{id}/events for reading a watcher’s event stream. In testing, this endpoint returned 404. It isn’t available in v1.0.0-rc.2.
Next steps
5 - Import from a database
In development. Not supported yet.
What to do instead
Until this capability is available, you can read the data from your database yourself, turn each row or group of rows into text, and write it with an inline upload or a batch submit.