Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/JasonHonKL/spy-search/llms.txt

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

Spy Search supports a local Retrieval-Augmented Generation (RAG) workflow. Documents are stored in named folders on the server, and the active folder is used to augment search and chat responses with content from your own files. The endpoints below cover the full lifecycle of RAG folder and file management.

​
GET /folder_list

Returns all RAG folders and their contents. Response format: application/json

​
Response

​
files
array
An array of FolderContent objects. Each object contains:
  • foldername (string) — the name of the folder
  • contents (string[]) — list of filenames within the folder

​
Example

curl http://localhost:8000/folder_list
Example response: 
{
  "files": [
    {
      "foldername": "research_papers",
      "contents": ["transformer_survey.pdf", "llm_scaling.pdf"]
    },
    {
      "foldername": "my_notes",
      "contents": ["meeting_notes.txt"]
    }
  ]
}

​
POST /create_folder

Creates a new RAG folder on the server. Request format: application/json Response format: application/json

​
Request Body

​
filepath
string
required
The name or relative path for the new folder to create within the RAG directory.Example: "research_papers" or "2024/q1_reports"

​
Response

​
success
boolean
true if the folder was created successfully, false otherwise.

​
Example

curl -X POST http://localhost:8000/create_folder \
  -H "Content-Type: application/json" \
  -d '{"filepath": "research_papers"}'
Example response: 
{
  "success": true
}

​
GET /select_folder

Sets the active RAG folder. After calling this endpoint, subsequent search and chat requests will use documents from the selected folder for retrieval-augmented context. Response format: application/json

​
Query Parameters

​
folder_name
string
required
The name of the folder to make active. Must match an existing folder returned by GET /folder_list.

​
Response

​
success
boolean
true if the folder was selected successfully.
​
selected_folder
string
The name of the folder that was activated.

​
Example

curl 'http://localhost:8000/select_folder?folder_name=research_papers'
Example response: 
{
  "success": true,
  "selected_folder": "research_papers"
}

​
POST /upload_file

Uploads a file into an existing RAG folder. The file is stored on the server and becomes available for vector indexing and retrieval. Request format: multipart/form-data Response format: application/json

​
Form Parameters

​
file
file
required
The file to upload. Sent as a multipart file field.
​
filepath
string
required
The target folder name where the file should be stored. Must be an existing folder (create it first with POST /create_folder if needed).Example: "research_papers"

​
Response

​
success
boolean
true if the file was uploaded successfully, false if the upload failed.
​
filename
string
The original filename of the uploaded file.
​
filepath
string
The target folder path the file was uploaded to.

​
Example

curl -X POST http://localhost:8000/upload_file \
  -F "file=@/path/to/transformer_survey.pdf" \
  -F "filepath=research_papers"
Example response: 
{
  "success": true,
  "filename": "transformer_survey.pdf",
  "filepath": "research_papers"
}
Failed upload response: 
{
  "success": false,
  "error": "Upload failed"
}

​
POST /delete_file

Deletes a file from the RAG directory. The file path is passed as a query parameter. Response format: application/json

​
Query Parameters

​
filepath
string
required
The path to the file to delete, relative to the RAG root directory.Example: "research_papers/transformer_survey.pdf"

​
Response

​
success
boolean
true if the file was deleted, false if deletion failed.
​
deleted_file
string
The path of the file that was deleted (echoed from the request).

​
Example

curl -X POST \
  "http://localhost:8000/delete_file?filepath=research_papers/transformer_survey.pdf"
Example response: 
{
  "success": true,
  "deleted_file": "research_papers/transformer_survey.pdf"
}
Failed deletion response: 
{
  "success": false,
  "error": "Delete failed"
}

​
GET /download_file/{filepath:path}

Downloads a file from the RAG directory as a binary stream. The :path converter in the route pattern preserves forward slashes, so nested folder paths can be passed directly without URL-encoding the slashes. Response format: application/octet-stream

​
Path Parameters

​
filepath
string
required
The relative path to the file within the RAG directory, including the folder name and filename. Forward slashes are preserved by the :path converter.Example: research_papers/transformer_survey.pdf

​
Response

Returns the raw binary content of the file as an attachment with Content-Disposition: attachment set to the filename. An HTTP 404 is returned if the file does not exist.

​
Example

# Download and save a file
curl -O http://localhost:8000/download_file/research_papers/transformer_survey.pdf

# Or save to a specific path
curl -o ~/Downloads/survey.pdf \
  http://localhost:8000/download_file/research_papers/transformer_survey.pdf

Build docs developers (and LLMs) love

Get started for freeTalk to us