Indexing API: Upload and Track Document Indexing Jobs

The indexing API lets you upload a folder’s worth of files from the browser and track the resulting background job. Files are copied to local_sources/collections/<collection_id>/<label>-<timestamp>/, then index.py is spawned as a subprocess to chunk and embed them. The in-memory retriever reloads automatically when the job completes. All endpoints on this page require authorization.

All indexing and watcher endpoints require authorization via localhost/LAN access or an X-Admin-Token header.

POST /system/index-upload

Upload a folder for indexing via a multipart form. The browser’s native folder picker provides the files — TrinaxAI copies them into a local staging directory and launches a background indexing job.

Maximum upload size is 512 MB (configurable via TRINAXAI_UPLOAD_MAX_BYTES). Maximum number of files is 2,500 (configurable via TRINAXAI_UPLOAD_MAX_FILES). Individual files larger than 3 MB are skipped (configurable via TRINAXAI_MAX_FILE_BYTES).

Request

multipart/form-data with the following fields:

files

file[]

required

One or more files to index. File paths are sanitized to prevent path traversal. Unsupported or oversized files are skipped automatically.

label

string

default:"import"

Human-readable label for the import batch (e.g. "InsiderApp" or "Q2Docs"). Used in the target directory name and job metadata. Sanitized to alphanumeric + dots, spaces, and hyphens.

collection_id

string

default:"default"

ID of the collection to index files into. If the collection does not yet exist it is created automatically.

Response

boolean

Always true when the job is successfully started.

job_id

string

Unique hex ID for the background indexing job. Use this with GET /system/index-jobs/{job_id} to poll progress.

indexed

boolean

Always false at job start — indexing runs in the background.

path

string

Absolute path of the staging directory where files were saved.

saved

integer

Number of files successfully saved to the staging directory.

skipped

integer

Number of files skipped (oversized, unsafe paths, or write errors).

bytes

integer

Total bytes saved to disk.

projects

array

List of project names already known to the in-memory index at upload time. Usually [] at job start since indexing runs in the background.

collection_id

string

Resolved collection ID for this job.

collection_name

string

Display name of the resolved collection.

Example

curl -X POST http://localhost:3333/system/index-upload \
  -H "X-Admin-Token: your-token" \
  -F "label=InsiderApp" \
  -F "collection_id=my-project" \
  -F "files=@src/auth.py" \
  -F "files=@src/models.py" \
  -F "files=@docs/architecture.md"

Response

{
  "ok": true,
  "job_id": "f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c6",
  "indexed": false,
  "path": "/home/user/TrinaxAI/local_sources/collections/my-project/InsiderApp-20240611-143000",
  "saved": 3,
  "skipped": 0,
  "bytes": 18432,
  "projects": [],
  "collection_id": "my-project",
  "collection_name": "My Project"
}

GET /system/index-jobs/{job_id}

Poll the status and progress of a running or completed indexing job.

Path parameters

job_id

string

required

The job ID returned by POST /system/index-upload.

Response

string

The job ID.

label

string

Human-readable batch label.

status

string

Current job state. One of: "saving", "indexing", "completed", "failed", "cancelled".

phase

string

Granular phase within the current status. Examples: "starting", "chunking", "embedding", "saving_index", "finishing", "completed", "failed", "cancelled".

progress

integer

Estimated completion percentage [0, 100].

eta_seconds

integer | null

Estimated seconds remaining, or null if not calculable yet.

elapsed_seconds

integer

Seconds elapsed since the job started.

saved

integer

Files saved to the staging directory.

skipped

integer

Files that were skipped.

bytes

integer

Total bytes processed.

indexed

boolean

true once the in-memory retriever has been successfully reloaded with the new content.

projects

array

List of project names detected in the indexed content (populated after completion).

collection_id

string

Collection ID for this job.

collection_name

string

Collection display name.

output

string

Last 8,000 characters of stdout from index.py. Useful for diagnosing failures.

error

string

Error message if the job failed, otherwise empty string.

cancel_requested

boolean

Whether cancellation was requested.

created_at

number

Unix timestamp when the job was created.

finished_at

number | null

Unix timestamp when the job finished, or null if still running.

Example

curl http://localhost:3333/system/index-jobs/f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c6 \
  -H "X-Admin-Token: your-token"

Response

{
  "id": "f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c6",
  "label": "InsiderApp",
  "status": "indexing",
  "phase": "embedding",
  "progress": 65,
  "eta_seconds": 42,
  "elapsed_seconds": 78,
  "saved": 3,
  "skipped": 0,
  "bytes": 18432,
  "indexed": false,
  "projects": [],
  "collection_id": "my-project",
  "collection_name": "My Project",
  "output": "Troceando archivos... 3/3\nEmbedding chunks...\n",
  "error": "",
  "cancel_requested": false,
  "created_at": 1718200000.0,
  "finished_at": null
}

POST /system/index-jobs/{job_id}/cancel

Request cancellation of a running index job. The subprocess is sent SIGTERM and the job transitions to "cancelled" status. Already-saved files in the staging directory are not removed.

Path parameters

job_id

string

required

The job ID to cancel.

Response

boolean

Always true when the cancellation request is accepted.

job

object

The final job state object (same shape as GET /system/index-jobs/{job_id}).

Example

curl -X POST \
  http://localhost:3333/system/index-jobs/f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c6/cancel \
  -H "X-Admin-Token: your-token"

Response

{
  "ok": true,
  "job": {
    "id": "f3a2b1c4d5e6f7a8b9c0d1e2f3a4b5c6",
    "status": "cancelled",
    "phase": "cancelled",
    "progress": 100,
    "indexed": false,
    "finished_at": 1718200180.0
  }
}

POST /system/reload

Hot-reload the RAG index from the storage/ directory without restarting the API server. Call this after running python index.py manually on the host or after making changes to local_sources/.

Response

boolean

true if the index was loaded successfully. false if storage/ has no valid index yet.

indexed

boolean

true if the in-memory retriever is now active.

projects

array

List of project names detected in the freshly loaded index.

Example

curl -X POST http://localhost:3333/system/reload \
  -H "X-Admin-Token: your-token"

Response

{
  "ok": true,
  "indexed": true,
  "projects": ["Insider", "MyApp", "AdminPanel"]
}

POST /v1/watch/start

Start a filesystem watcher (backed by watchdog) that automatically triggers a re-index whenever files in the watched directories are created, modified, moved, or deleted. Requires the watchdog Python package to be installed.

Returns HTTP 501 if watchdog is not installed. Install it with pip install watchdog.

Request body

paths

array

List of absolute directory paths to watch recursively. If omitted, TrinaxAI auto-discovers sensible defaults based on local_sources/ and the active collection’s subdirectory.

collection

string

Collection ID used to narrow the default path discovery when paths is not provided.

Response

status

string

"started" if the watcher was launched. "already_running" if a watcher is already active.

watching

array

List of absolute directory paths now being watched.

pid

integer

Process ID of the RAG API server hosting the watcher thread.

Example

curl -X POST http://localhost:3333/v1/watch/start \
  -H "Content-Type: application/json" \
  -H "X-Admin-Token: your-token" \
  -d '{"paths": ["/home/user/projects/Insider"], "collection": "my-project"}'

Response

{
  "status": "started",
  "watching": ["/home/user/projects/Insider"],
  "pid": 12345
}

POST /v1/watch/stop

Stop the running filesystem watcher. If no watcher is active, returns "not_running".

Response

status

string

"stopped" if a watcher was running and has been stopped. "not_running" if there was nothing to stop.

Example

curl -X POST http://localhost:3333/v1/watch/stop \
  -H "X-Admin-Token: your-token"

Response

{
  "status": "stopped"
}

GET /v1/watch/status

Report the current state of the filesystem watcher.

Response

running

boolean

true if the watcher observer thread is alive.

watching

array

List of absolute directory paths currently being watched. Empty if not running.

events_seen

integer

Total number of filesystem events processed since the watcher was started.

started_at

number | null

Unix timestamp when the watcher was started, or null if not running.

Example

curl http://localhost:3333/v1/watch/status \
  -H "X-Admin-Token: your-token"

Response

{
  "running": true,
  "watching": ["/home/user/projects/Insider"],
  "events_seen": 14,
  "started_at": 1718200000.0
}

POST /v1/usage

Record a usage event from frontend-only flows (e.g. direct Ollama chat that bypasses the RAG API). These events are appended to storage/usage.jsonl and rolled into the usage summary.

Request body

engine

string

default:"ollama"

Usage engine identifier (e.g. "ollama", "rag", "direct"). Max 40 characters.

model

string

default:"unknown"

Model name used for the request. Max 120 characters.

project

string

Optional project name associated with the request.

collections

array

Optional list of collection IDs involved in the request.

est_tokens

integer

default:"0"

Estimated token count for the request. Used for the aggregated token counter in /v1/stats.

Response

boolean

Always true.

Example

curl -X POST http://localhost:3333/v1/usage \
  -H "Content-Type: application/json" \
  -H "X-Admin-Token: your-token" \
  -d '{
    "engine": "ollama",
    "model": "qwen2.5-coder:3b",
    "project": "Insider",
    "collections": ["my-project"],
    "est_tokens": 1200
  }'

Response

{"ok": true}

GET /v1/stats

Retrieve aggregated local usage statistics built from storage/usage.jsonl. The summary is incrementally maintained on every usage record write and served from storage/usage_summary.json for fast reads.

Response

messages_total

integer

Total number of recorded usage events.

messages_by_engine

object

Map of engine name → count, sorted by descending count.

tokens_estimated

integer

Sum of all est_tokens values across all recorded events.

top_collections

array

Top 10 collections by usage count, each as {"id": string, "count": integer}.

top_models

array

Top 10 models by usage count, each as {"model": string, "count": integer}.

index_runs

integer

Number of indexing runs recorded.

first_seen

number

Unix timestamp of the earliest recorded event. 0.0 if no events yet.

last_seen

number

Unix timestamp of the most recent recorded event.

Example

curl http://localhost:3333/v1/stats \
  -H "X-Admin-Token: your-token"

Response

{
  "messages_total": 1523,
  "messages_by_engine": {
    "rag": 1200,
    "ollama": 323
  },
  "tokens_estimated": 450000,
  "top_collections": [
    {"id": "default", "count": 900},
    {"id": "my-project", "count": 623}
  ],
  "top_models": [
    {"model": "qwen2.5-coder:3b", "count": 800},
    {"model": "llama3.2:3b", "count": 400},
    {"model": "qwen2.5-coder:7b", "count": 323}
  ],
  "index_runs": 12,
  "first_seen": 1717000000.0,
  "last_seen": 1718300000.0
}

Overview

Endpoints

Indexing API: Upload and Track Document Indexing Jobs

POST /system/index-upload

Request

Response

Example

GET /system/index-jobs/{job_id}

Path parameters

Response

Example

POST /system/index-jobs/{job_id}/cancel

Path parameters

Response

Example

POST /system/reload

Response

Example

POST /v1/watch/start

Request body

Response

Example

POST /v1/watch/stop

Response

Example

GET /v1/watch/status

Response

Example

POST /v1/usage

Request body

Response

Example

GET /v1/stats

Response

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​POST /system/index-upload

​Request

​Response

​Example

​GET /system/index-jobs/{job_id}

​Path parameters

​Response

​Example

​POST /system/index-jobs/{job_id}/cancel

​Path parameters

​Response

​Example

​POST /system/reload

​Response

​Example

​POST /v1/watch/start

​Request body

​Response

​Example

​POST /v1/watch/stop

​Response

​Example

​GET /v1/watch/status

​Response

​Example

​POST /v1/usage

​Request body

​Response

​Example

​GET /v1/stats

​Response

​Example

Build docs developers (and LLMs) love

POST /system/index-upload

Request

Response

Example

GET /system/index-jobs/{job_id}

Path parameters

Response

Example

POST /system/index-jobs/{job_id}/cancel

Path parameters

Response

Example

POST /system/reload

Response

Example

POST /v1/watch/start

Request body

Response

Example

POST /v1/watch/stop

Response

Example

GET /v1/watch/status

Response

Example

POST /v1/usage

Request body

Response

Example

GET /v1/stats

Response

Example