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.
The Spy Search API is a FastAPI application served on http://localhost:8000 by default. It exposes endpoints for streaming LLM completions, web and academic search, multi-agent report generation, news retrieval, agent configuration, RAG file management, and conversation history.
Base URL
Authentication
No authentication is required in the default configuration. Spy Search is designed as a single-user, self-hosted deployment. An optional api form field exists on streaming and search endpoints to pass an API key override directly to the underlying LLM provider at request time.
Content Types
| Direction | Format |
|---|
| Request body (JSON endpoints) | application/json |
| Request body (upload/streaming endpoints) | multipart/form-data |
| Response (most endpoints) | application/json |
| Response (streaming endpoints) | text/plain (chunked transfer encoding) |
| Response (file download) | application/octet-stream |
Endpoint Overview
| Method | Path | Description |
|---|
POST | /stream_completion/{query} | Streaming search + chat completion |
POST | /stream_completion_academic/{query} | Streaming arXiv academic search |
POST | /quick/{query} | Non-streaming quick search |
POST | /report/{query} | Full multi-agent report generation |
GET | /news/{category} | Today’s news by category |
GET | /get_config | Get current agent/model config |
POST | /agents_selection | Update agent/model config |
GET | /folder_list | List RAG folders |
POST | /create_folder | Create RAG folder |
GET | /select_folder | Set active RAG folder |
POST | /upload_file | Upload file to RAG folder |
POST | /delete_file | Delete file from RAG |
GET | /download_file/{filepath:path} | Download file (:path preserves slashes) |
GET | /get_titles | List saved conversation titles |
POST | /load_message | Load conversation by title |
POST | /delete_message | Delete conversation |
POST | /append_message | Append message to conversation |
Pydantic Schemas
These schemas are defined in src/api/models/schemas.py and appear as request/response bodies across multiple endpoints.
Message
A single chat message with a role and content string.
{
"role": "user",
"content": "What is the speed of light?"
}
| Field | Type | Description |
|---|
role | string | The message role — e.g. "user", "assistant", or "system" |
content | string | The text content of the message |
AgentsRequest
Used by POST /agents_selection to update the active agent list and LLM settings.
{
"agents": ["reporter"],
"provider": "openai",
"model": "gpt-4o"
}
| Field | Type | Description |
|---|
agents | string[] | List of agent names to activate |
provider | string | LLM provider identifier (e.g. "openai", "anthropic") |
model | string | Model name to use (e.g. "gpt-4o") |
TitleRequest
Identifies a saved conversation by its title.
{
"title": "My Research Session"
}
| Field | Type | Description |
|---|
title | string | The title of the saved conversation |
AppendRequest
Appends a single message to an existing conversation.
{
"title": "My Research Session",
"message": {
"role": "assistant",
"content": "Here is the summary..."
}
}
| Field | Type | Description |
|---|
title | string | The conversation title to append to |
message | Message | The message object to append |
FolderCreateRequest
Specifies the path for a new RAG folder.
{
"filepath": "my_documents"
}
| Field | Type | Description |
|---|
filepath | string | The folder name/path to create within the RAG directory |
FolderContent
Represents a single folder and its file listing, used inside FolderListResponse.
{
"foldername": "research_papers",
"contents": ["transformer_survey.pdf", "llm_scaling.pdf"]
}
| Field | Type | Description |
|---|
foldername | string | The name of the folder |
contents | string[] | List of filenames within the folder |
FolderListResponse
Returned by GET /folder_list.
{
"files": [
{ "foldername": "research_papers", "contents": ["transformer_survey.pdf"] }
]
}
| Field | Type | Description |
|---|
files | FolderContent[] | Array of folder objects, each with a name and file list |
Interactive Documentation
FastAPI automatically generates interactive API documentation. With Spy Search running locally, visit:
- Swagger UI —
http://localhost:8000/docs
- ReDoc —
http://localhost:8000/redoc
Both UIs allow you to explore all endpoints, inspect schemas, and execute live requests directly from your browser.