Skip to content

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

Return to the regular view of this page.

Guides

Upload documents, run queries, and work with memory, task by task.

Each guide covers one task, with commands you can copy and the output to expect.

1 - Upload documents

Write documents into a namespace and track their processing.

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.

Note

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 uploadInline upload
EndpointPOST /api/v1/namespaces/{ns}/documentsPOST /api/v1/documents
Request bodymultipart/form-dataJSON
Best forUploading a file, including binary filesText your program already has in memory
ReturnsA doc_id right awayA task_id; processing is asynchronous
If the namespace doesn’t exist404 right awayThe 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

curl -fsS -H 'Content-Type: application/json' \
  -d '{"name": "guide", "display_name": "Guide"}' \
  http://127.0.0.1:8420/api/v1/namespaces
{
  "block_count": 0,
  "created_at": 1791069436679,
  "doc_count": 0,
  "name": "guide",
  "namespace": "guide",
  "status": "active",
  "updated_at": 1791069436679
}

Upload a file

First create a text file:

printf 'Refund policy\n\nCustomers can request a refund within 30 days of purchase.\nRefunds are issued to the original payment method within 5 business days.\n' \
  > refund-policy.txt

Upload it as multipart. file is required. title and metadata (a JSON string) are optional:

curl -fsS \
  -F 'file=@refund-policy.txt' \
  -F 'title=Refund policy' \
  http://127.0.0.1:8420/api/v1/namespaces/guide/documents
{
  "content_hash": "4cae8f4fef140499f28815e2372a3027b5dbb2634e14e7766bf609011f56545a",
  "doc_id": "01M420XEVFXR2YE9NZ6E49X8M7",
  "message": "Document uploaded successfully, processing queued",
  "source_path": "refund-policy.txt",
  "status": "pending"
}

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:

{
  "content_hash": "4cae8f4fef140499f28815e2372a3027b5dbb2634e14e7766bf609011f56545a",
  "doc_id": "01M420XEVFXR2YE9NZ6E49X8M7",
  "message": "Document unchanged, skipping reprocessing",
  "source_path": "refund-policy.txt",
  "status": "skipped"
}

Upload inline content

namespace and content are required. filename and metadata are optional:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespace": "guide",
    "content": "Shipping policy. Orders ship within 2 business days. Express shipping is available at checkout.",
    "filename": "shipping-policy.txt"
  }' \
  http://127.0.0.1:8420/api/v1/documents

The service returns HTTP 202 and a task:

{
  "namespace": "guide",
  "status": "queued",
  "task_id": "01M420XEVZMH2RRDH2CCZ4R8BE"
}

Check task progress

Look up the task with the task_id from the previous step:

curl -fsS http://127.0.0.1:8420/api/v1/documents/tasks/01M420XEVZMH2RRDH2CCZ4R8BE/progress
{
  "doc_id": "01M420XEVZMH2RRDH2CCZ4R8BC",
  "error_code": null,
  "error_msg": null,
  "meta": {
    "agent_decision_hint": "done_fetch_doc",
    "current_phase": "parsing",
    "retryable_if_fail": true
  },
  "processed_pages": 1,
  "progress_pct": 100.0,
  "status": "completed",
  "task_id": "01M420XEVZMH2RRDH2CCZ4R8BE",
  "total_pages": 1
}

A status of completed with error_code set to null means processing succeeded. meta.agent_decision_hint tells an agent what to do next.

Warning

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

curl -fsS 'http://127.0.0.1:8420/api/v1/documents?namespace=guide'
{
  "documents": [
    {
      "document_id": "01M420XEVZMH2RRDH2CCZ4R8BC",
      "filename": "shipping-policy.txt",
      "namespace": "guide",
      "source_type": "file",
      "status": "ready"
    },
    {
      "document_id": "01M420XEVFXR2YE9NZ6E49X8M7",
      "filename": "refund-policy.txt",
      "namespace": "guide",
      "source_type": "http_upload",
      "status": "ready"
    }
  ],
  "total": 2
}

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:

curl -fsS 'http://127.0.0.1:8420/api/v1/documents/01M420XEVFXR2YE9NZ6E49X8M7?namespace=guide'

Delete a document

curl -fsS -X DELETE \
  'http://127.0.0.1:8420/api/v1/documents/01M420XEVZMH2RRDH2CCZ4R8BC?namespace=guide'

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:

{
  "error": {
    "category": "permanent",
    "code": "INVALID_ARGUMENT",
    "message": "Missing 'name' field",
    "request_id": "571fa754f07d1413ef27cf5af3cb0367",
    "retry_after_ms": null,
    "retryable": false,
    "structured_data": {},
    "timestamp": "2026-10-03T23:17:05.349Z"
  }
}

Next steps

2 - Query and rerank

Run hybrid retrieval over one or more namespaces, with reranking.

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 guide namespace from Upload documents.

Run a query

Every query goes through one endpoint, POST /api/v1/query. query and namespaces are required:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespaces": ["guide"],
    "query": "How long do refunds take?",
    "top_k": 3,
    "rerank": true
  }' \
  http://127.0.0.1:8420/api/v1/query

The response has two parts, meta and results. Only the key fields of results are shown here:

{
  "meta": {
    "coverage_ratio": 1.0,
    "latency_ms": 222,
    "namespaces_failed": [],
    "namespaces_queried": ["guide"],
    "namespaces_succeeded": ["guide"],
    "warnings": []
  },
  "results": [
    {
      "content": "Refund policy\nCustomers can request a refund within 30 days of purchase. ...",
      "metadata": { "source_path": "refund-policy.txt" },
      "namespace": "guide",
      "rerank_score": 0.824,
      "score": 0.0167
    },
    {
      "content": "Shipping policy. Orders ship within 2 business days. ...",
      "metadata": { "source_path": "shipping-policy.txt" },
      "namespace": "guide",
      "rerank_score": 0.0,
      "score": 0.0164
    }
  ]
}

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

ParameterTypeDefaultDescription
querystringRequiredThe query text
namespacesstring arrayRequiredThe namespaces to search
top_kinteger10How many results to return. The minimum is 1
rerankbooleantrueWhether to reorder candidates with the reranker model
include_sourcesboolean—When true, results include source information
filterobject—Filter conditions

For the full request shape, see the HTTP API reference.

Warning

Use the plural namespaces array. A singular namespace is rejected:

{
  "error": {
    "category": "permanent",
    "code": "CX_ERR_DEPRECATED_FIELD",
    "message": "Field 'namespace' is deprecated, use 'namespaces' array instead",
    "retryable": false,
    "structured_data": { "deprecated_field": "namespace", "use_instead": "namespaces" }
  }
}

Read the results

Each result is a block:

FieldMeaning
contentThe block’s text
namespaceThe namespace the block belongs to
metadata.source_pathThe original filename of the source document
rerank_scoreThe relevance score from the reranker model
scoreThe 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:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespaces": ["guide", "demo"],
    "query": "How long do refunds take?",
    "top_k": 3
  }' \
  http://127.0.0.1:8420/api/v1/query

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:

curl -fsS -H 'Content-Type: application/json' \
  -d '{"namespaces": ["guide", "nope"], "query": "refunds", "top_k": 2}' \
  http://127.0.0.1:8420/api/v1/query

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:

{
  "coverage_ratio": 0.5,
  "namespaces_failed": [
    {
      "category": "permanent",
      "error_code": "CX_ERR_INDEX_CORRUPT",
      "message": "CX_ERR_INDEX_CORRUPT",
      "namespace": "nope",
      "retry_after_ms": null,
      "retryable": false,
      "structured_data": { "index_state": "unavailable", "namespace": "nope" }
    }
  ],
  "namespaces_queried": ["guide", "nope"],
  "namespaces_succeeded": ["guide"]
}
Important

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:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespaces": ["guide"],
    "query": "How long do refunds take?",
    "top_k": 3,
    "rerank": false
  }' \
  http://127.0.0.1:8420/api/v1/query

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":"CX_WARN_RERANK_DISABLED","reason":"rerank_disabled","category":"permanent"}
CodeWhen it appearsreasoncategoryretry_after_msWhat to do
CX_WARN_RERANK_DISABLEDThe request sets "rerank": false. Ordering uses the fused retrieval score instead of the reranker model.rerank_disabledpermanent—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_DEGRADEDThe 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_degradedtransient1000Results 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_DEGRADEDThe 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_degradedtransient5000Results 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:

curl -fsS -H 'Content-Type: application/json' \
  -d '{"namespaces": ["guide"], "query": "How long do refunds take?", "top_k": 1}' \
  'http://127.0.0.1:8420/api/v1/query?explain=true'
{
  "complexity_score": 0.8999999761581421,
  "granularity": "auto",
  "query": "How long do refunds take?",
  "routing_path": "simple",
  "rrf_path_counts": { "dense": 1, "fts5": 1 },
  "via_path_counts": { "chunk": 1 }
}

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

3 - Work with memory

Write, list, edit, and delete memories.

On this page you’ll write memories explicitly through the API, then list, edit, and delete them.

Note

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:
curl -fsS -H 'Content-Type: application/json' \
  -d '{"name": "assistant", "display_name": "Assistant memory"}' \
  http://127.0.0.1:8420/api/v1/namespaces

Memory types

TypeMeaning
factA fact
preferenceA preference
eventAn 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:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "namespace": "assistant",
    "content": "User preference: use Markdown for report format",
    "memory_type": "preference"
  }' \
  http://127.0.0.1:8420/api/v1/memory
{ "memory_id": "01M421CJRVM3KE0VYK5V8Y0753", "status": "active" }

A memory written this way is an explicit memory. It isn’t validated by an LLM.

List memories

curl -fsS 'http://127.0.0.1:8420/api/v1/memory?namespace=assistant'
{
  "memories": [
    {
      "content": "User preference: use Markdown for report format",
      "extracted_at": 1791069932315,
      "memory_id": "01M421CJRVM3KE0VYK5V8Y0753",
      "memory_type": "preference",
      "status": "active"
    }
  ],
  "page": 0,
  "page_size": 50,
  "total": 1
}

Query parameters:

ParameterDescription
namespaceRequired
memory_typeList only one type: fact, preference, or event
include_invalidatedWhen true, also return invalidated memories. The default is false
limit, offsetPaging

Edit a memory

An edit doesn’t overwrite the original. Cortrix creates a new memory and marks the old one invalidated:

curl -fsS -X PATCH -H 'Content-Type: application/json' \
  -d '{
    "ns": "assistant",
    "content": "User preference: use Markdown for reports and include a summary table"
  }' \
  http://127.0.0.1:8420/api/v1/memory/01M421CJRVM3KE0VYK5V8Y0753
{
  "invalidated_memory_id": "01M421CJRVM3KE0VYK5V8Y0753",
  "new_memory_id": "01M421CWYEK961J68WZ9KTNVS6"
}
Warning

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:

curl -fsS -X DELETE \
  'http://127.0.0.1:8420/api/v1/memory/01M421CJTK0AQ19B9W4ZMWB3S4?ns=assistant'
{ "block_id": "01M421CJTK0AQ19B9W4ZMWB3S4", "status": "invalidated" }

Invalidated memories don’t appear in the list by default. Add include_invalidated=true to see them:

curl -fsS 'http://127.0.0.1:8420/api/v1/memory?namespace=assistant&include_invalidated=true'

Sessions

A memory session groups a set of conversation turns. namespace is required when you create one:

curl -fsS -H 'Content-Type: application/json' \
  -d '{"namespace": "assistant", "user_id": "user_001"}' \
  http://127.0.0.1:8420/api/v1/memory/sessions
{
  "created_at": "2026-10-03T23:25:59.267Z",
  "namespace": "assistant",
  "session_id": "90fbdf71-f7dd-4a7a-a46b-5eac344871f2",
  "title": "",
  "user_id": "user_001"
}

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

CapabilityStatus
Automatic memory extraction from conversationsIn development. Not supported yet
Automatic handling of contradicting memoriesIn 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

Have Cortrix track file changes in a directory on the server.

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:

docker exec deploy-cortrix-1 sh -c \
  'mkdir -p /data/watch-demo && echo "Onboarding checklist. New hires receive a laptop on day one and complete security training in week one." > /data/watch-demo/onboarding.txt'

Create the namespace that receives the files:

curl -fsS -H 'Content-Type: application/json' \
  -d '{"name": "watched", "display_name": "Watched folder"}' \
  http://127.0.0.1:8420/api/v1/namespaces

Add a watcher

path and target_namespaces are required. recursive defaults to true, which includes subdirectories:

curl -fsS -H 'Content-Type: application/json' \
  -d '{
    "path": "/data/watch-demo",
    "target_namespaces": ["watched"],
    "recursive": true
  }' \
  http://127.0.0.1:8420/api/v1/watch
{
  "id": "9a97d854",
  "path": "/data/watch-demo",
  "recursive": true,
  "status": "active",
  "target_namespaces": ["watched"]
}

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:

curl -fsS 'http://127.0.0.1:8420/api/v1/documents?namespace=watched'
{
  "documents": [
    {
      "document_id": "01M421DDBRNPRZKD50DNRYJR9V",
      "filename": "/data/watch-demo/onboarding.txt",
      "namespace": "watched",
      "source_ref": "/data/watch-demo",
      "source_type": "watch_dir",
      "status": "ready"
    }
  ],
  "total": 1
}

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:

docker exec deploy-cortrix-1 sh -c \
  'echo "Expense policy. Submit receipts within 14 days." > /data/watch-demo/expenses.txt'

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:

curl -fsS http://127.0.0.1:8420/api/v1/watch

Remove a watcher, along with all of its namespace subscriptions:

curl -fsS -X DELETE http://127.0.0.1:8420/api/v1/watch/9a97d854

A successful removal returns HTTP 204.

Warning

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

Import data from a database into a namespace.
In development

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.

Next steps