Repository navigation
API Reference
The API is served under /api/v1. The interactive OpenAPI documentation is available at /docs when the service is running.
Successful operations return a JSON object containing a signal field and operation-specific data. Validation and operational failures generally return HTTP 400 with a signal describing the failure. Exact signal values are defined in src/models/enums/ResponseEnums.py.
| Method | Path | Purpose |
|---|---|---|
GET |
/api/v1/ |
Base API response from the base router. |
GET |
/api/v1/health |
Process liveness probe. Returns {"status":"ok"} when the FastAPI process responds. |
The health endpoint does not perform a dependency readiness check.
POST /api/v1/data/upload/{project_id}
Content-Type: multipart/form-dataThe request must contain a multipart field named file. The route creates the project when necessary, validates the upload, writes the file under the project storage root, and records an asset in MongoDB.
Example:
curl --fail-with-body --request POST \
'http://localhost:5000/api/v1/data/upload/demo-project' \
--form 'file=@/absolute/path/to/document.pdf'Success response shape:
{
"signal": "file_upload_success",
"file_id": "<asset-file-id>"
}Common failure signals include an unsupported file type, an oversized file, and an upload write failure. The route removes a partially written file when the write operation raises an exception.
POST /api/v1/data/process/{project_id}
Content-Type: application/jsonRequest body:
| Field | Type | Default | Constraints |
|---|---|---|---|
file_id |
string or null | null |
When provided, process only that project asset. When omitted, process all project files. |
chunk_size |
integer | 100 |
Must be greater than zero. |
overlap_size |
integer | 20 |
Must be non-negative and strictly smaller than chunk_size. |
do_reset |
integer | 0 |
Must be 0 or 1; when 1, delete existing project chunks before processing. |
Example:
curl --fail-with-body --request POST \
'http://localhost:5000/api/v1/data/process/demo-project' \
--header 'Content-Type: application/json' \
--data '{
"file_id": "<file_id>",
"chunk_size": 100,
"overlap_size": 20,
"do_reset": 1
}'Success response shape:
{
"signal": "file_processing_success",
"inserted_chunks": 12,
"processed_files": 1
}If the requested file does not exist in the project, no files are available, a document cannot be loaded, or chunking fails, the route returns a 400 response with an appropriate processing signal.
POST /api/v1/nlp/index/push/{project_id}
Content-Type: application/jsonRequest body:
| Field | Type | Default | Constraints |
|---|---|---|---|
do_reset |
integer | 0 |
Must be 0 or 1; when 1, reset only the first indexing page. |
Example:
curl --fail-with-body --request POST \
'http://localhost:5000/api/v1/nlp/index/push/demo-project' \
--header 'Content-Type: application/json' \
--data '{"do_reset": 1}'Success response shape:
{
"signal": "insert_into_vectordb_success",
"inserted_items_count": 12
}The route reads chunks in pages and preserves vectors inserted by earlier pages. A vector insertion failure returns HTTP 400 with the vector-database error signal.
GET /api/v1/nlp/index/info/{project_id}The route returns the vector database collection metadata for the project:
{
"signal": "vectordb_collection_retrieved",
"collection_info": {}
}The exact collection_info structure is provider-dependent.
The primary search endpoint is:
POST /api/v1/nlp/index/search/{project_id}
Content-Type: application/jsonRequest body:
| Field | Type | Default | Constraints |
|---|---|---|---|
text |
string | required | Must be non-empty after trimming. |
limit |
integer | 5 |
Must be between 1 and 100. |
Example:
curl --fail-with-body --request POST \
'http://localhost:5000/api/v1/nlp/index/search/demo-project' \
--header 'Content-Type: application/json' \
--data '{
"text": "What is the main topic of the document?",
"limit": 5
}'Success response shape:
{
"signal": "vectordb_search_success",
"results": [
{
"chunk_text": "...",
"chunk_metadata": {},
"score": 0.92
}
]
}The exact result fields follow the RetrievedDocument model and vector-provider response.
A GET convenience endpoint is also available:
GET /api/v1/nlp/index/search/{project_id}?text=<url-encoded-query>&limit=5The GET route performs the same search operation but currently applies its own default limit of 10; callers should supply limit explicitly when consistent result counts matter.
POST /api/v1/nlp/index/answer/{project_id}
Content-Type: application/jsonThe request body uses the same SearchRequest schema as semantic search:
{
"text": "What is the main topic of the document?",
"limit": 5
}Success response shape:
{
"signal": "rag_answer_success",
"answer": "...",
"full_prompt": "...",
"chat_history": []
}The full_prompt may contain retrieved document content. Treat it as sensitive when documents contain private or regulated information.
Pydantic validation occurs before route logic. Invalid JSON fields, missing required search text, invalid chunk parameters, and out-of-range limits produce FastAPI validation responses. Controller-level checks repeat critical chunk and filesystem invariants so direct internal calls cannot bypass the route schema.
RAG Project Wiki • Getting Started • Architecture and Data Flow • API Reference • Testing and Contributing
Source Repository • Latest Release (v1.0.0) • Issues & Bugs • Security Policy
Developed by Bosaj (Oussama EL HADJI) • Licensed under Apache 2.0