POST /api/v1/documents/ingest

The documents endpoint exposes the ChromaDB ingestion pipeline without requiring a server restart. When you add or update source files in a data directory, call this endpoint to re-embed and re-index them into the named ChromaDB collection. The Mesa de Ayuda IA knowledge base is organized into three collections — one per specialized agent — all persisted locally under backend/data/chroma_db/. The endpoint validates that the source directory exists, enqueues the full ingestion pipeline as a FastAPI BackgroundTask, and returns an "accepted" status immediately while processing continues asynchronously.

Triggers the document ingestion pipeline for a specific directory and ChromaDB collection. The ingestion pipeline runs the following steps in sequence:

loader.py — reads all .txt and .pdf files from the specified directory using LangChain’s TextLoader
splitter.py — splits documents into chunks of ~1 000 characters with 200-character overlap using RecursiveCharacterTextSplitter
embeddings.py — generates vector embeddings for each chunk using GoogleGenerativeAIEmbeddings (model models/gemini-embedding-001)
vectorstore.py — indexes all chunks into the named ChromaDB collection, replacing any existing vectors

Request Body

collection_name

string

required

The name of the ChromaDB collection to populate. Must match one of the agent’s collection names. Standard values used by the system are col_catalogo, col_politicas, and col_proceso_ventas.

directory_path

string

default:"data/raw"

Path to the directory containing the source documents. The path is resolved relative to the backend working directory. Returns HTTP 400 if the directory does not exist at the time of the request.

Response

status

string

Acknowledgement of the request. Always "accepted" when the background task was enqueued successfully.

message

string

Human-readable confirmation including the collection name, e.g. "La ingesta para la colección 'col_catalogo' ha comenzado en background.".

Example

curl -X POST http://localhost:8000/api/v1/documents/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "directory_path": "data/raw",
    "collection_name": "col_catalogo"
  }'

Ingestion replaces all existing vectors in the target collection before re-indexing. Any chunks previously stored under collection_name in ChromaDB will be permanently deleted. Do not trigger ingestion on a live collection unless you have the source documents ready — the agents that depend on that collection will have no knowledge base until the background task completes.

To re-index all three collections in a single operation, use the dedicated ingestion script instead of calling this endpoint three times:

cd backend
python scripts/ingest.py

The script processes all three source files (01_Catalogo_Productos_Precios.txt, 02_Politicas_Comerciales_Descuentos_Credito.txt, 03_Proceso_Ventas_CRM.txt) and populates col_catalogo, col_politicas, and col_proceso_ventas sequentially. Run this after any change to the source documents in data/raw/.

Endpoints

POST /api/v1/documents/ingest — Trigger Document Ingestion