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