Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/StarTrail-org/PixelRAG/llms.txt

Use this file to discover all available pages before exploring further.

The /departments endpoint lists the departments available for use with the department filter in /search requests. Departments map to top-level subdirectories in the source document tree and are recorded in the index at build time by pixelrag index build. When you pass department to /search, the server pre-filters the FAISS index to only score vectors belonging to that department — this is a true pre-filter, not post-filtering, so you are guaranteed up to n_docs results when the department has enough tiles. Method: GET
Path: /departments
Request body: none

​
Response

{
  "departments": [
    {"name": "engineering", "n_documents": 1234},
    {"name": "finance", "n_documents": 567},
    {"name": "hr", "n_documents": 89}
  ]
}
Each entry in departments has:
​
name
string
Department identifier string. Pass this value as department in a /search request.
​
n_documents
integer
Number of source documents (articles) belonging to this department.
The list is sorted alphabetically by name.

​
Error Conditions

GET /departments always returns HTTP 200. When the index was built without department metadata, the response contains an empty departments list rather than an error: 
{"departments": []}
The HTTP 400 error occurs on POST /search when a department filter is specified but the loaded index has no department metadata: 
{
  "detail": "Index was built without department metadata; rebuild with `pixelrag index build` from a directory-per-department source."
}
A 404 is returned by /search when the requested department name is not found in the index.
Department metadata requires a local source with a directory-per-department layout. Web (kiwix, web) and flat local sources have no department structure. See pixelrag index build for details on the expected directory layout.
Once you have a department name from /departments, pass it to /search as the department field: 
curl -X POST http://localhost:30001/search \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [{"text": "Q3 revenue"}],
    "n_docs": 5,
    "department": "finance"
  }'
Combining the two endpoints in a workflow: 
# 1. List available departments
curl http://localhost:30001/departments

# 2. Search within a specific department
curl -X POST http://localhost:30001/search \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [{"text": "quarterly earnings chart"}],
    "n_docs": 10,
    "department": "finance"
  }'
The department filter runs inside FAISS as an IDSelector pre-filter rather than post-filtering the full result set. This means search latency scales with the department’s tile count, not the full index size.

Build docs developers (and LLMs) love

Get started for freeTalk to us