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 exposes five endpoints for querying the web, streaming LLM completions, generating structured reports, and fetching today’s news. All search and completion endpoints accept multipart/form-data requests; the news endpoint is a simple GET with a path parameter.

​
POST /stream_completion/{query}

Streams a chat completion response back to the client as chunked plain text. If the query string contains the prefix search:, Spy Search automatically performs a DuckDuckGo web search first and injects the results into the LLM prompt before streaming the answer. Request format: multipart/form-data Response format: text/plain (streaming)

​
Path Parameters

​
query
string
required
The search or chat query. Prefix with search: to trigger a DuckDuckGo web search before generating the completion.Examples: "What is quantum computing?" or "search: latest AI news"

​
Form Parameters

​
messages
string
required
A JSON-serialised array of Message objects representing the conversation history. The final element is treated as the current user turn.
[{"role": "user", "content": "Explain transformers in ML"}]
​
files
file
One or more file attachments (optional). Accepted as a multipart file upload.
​
api
string
Optional API key override. When provided, this key is forwarded to the underlying LLM provider instead of the key configured in the server environment.

​
Response

Returns a text/plain streaming response. Chunks are yielded as they are produced by the model. Each chunk is a raw text fragment — clients should concatenate them to reconstruct the full response. 
The transformer architecture was introduced in the 2017 paper
"Attention Is All You Need" by Vaswani et al. ...

​
Example

curl -X POST "http://localhost:8000/stream_completion/search:%20latest%20AI%20news" \
  -F 'messages=[{"role":"user","content":"Summarise the latest AI news"}]' \
  --no-buffer

​
POST /stream_completion_academic/{query}

Streams a chat completion that is automatically grounded in arXiv research papers. The endpoint prepends site:arxiv.org to the query before performing the DuckDuckGo search, so results are filtered to academic preprints and published papers indexed on arXiv. Request format: multipart/form-data Response format: text/plain (streaming)

​
Path Parameters

​
query
string
required
The academic topic or research question. The endpoint automatically constructs the search query site:arxiv.org {query} — you do not need to add the site prefix yourself.

​
Form Parameters

​
messages
string
required
A JSON-serialised array of Message objects representing the conversation history.
[{"role": "user", "content": "Summarise recent work on diffusion models"}]
​
files
file
One or more file attachments (optional).
​
api
string
Optional API key override forwarded to the LLM provider.

​
Response

Returns a text/plain streaming response grounded in arXiv search results.

​
Example

curl -X POST "http://localhost:8000/stream_completion_academic/diffusion%20models%20image%20generation" \
  -F 'messages=[{"role":"user","content":"Summarise recent arXiv papers on diffusion models"}]' \
  --no-buffer

​
POST /quick/{query}

Non-streaming search and LLM completion. Performs a DuckDuckGo search, builds a prompt from the results, calls the configured LLM, and returns the full response as a JSON object. Use this endpoint when you need the complete answer at once rather than a stream. Request format: multipart/form-data Response format: application/json

​
Path Parameters

​
query
string
required
The search and chat query.

​
Form Parameters

​
messages
string
required
A JSON-serialised array of Message objects.
[{"role": "user", "content": "Who won the 2024 Nobel Prize in Physics?"}]
​
files
file
One or more file attachments (optional).
​
api
string
Optional API key override.

​
Response

​
report
string
The full LLM-generated answer as a single string.
​
files_received
array
Details of any uploaded files. Each element contains:
  • filename (string) — the original filename
  • size (integer) — file size in bytes
​
messages_received
array
Echo of the parsed Message objects that were supplied in the request.

​
Example

curl -X POST "http://localhost:8000/quick/Nobel%20Prize%20Physics%202024" \
  -F 'messages=[{"role":"user","content":"Who won the 2024 Nobel Prize in Physics?"}]'
Example response: 
{
  "report": "The 2024 Nobel Prize in Physics was awarded to John Hopfield and Geoffrey Hinton...",
  "files_received": [],
  "messages_received": [
    {"role": "user", "content": "Who won the 2024 Nobel Prize in Physics?"}
  ]
}

​
POST /report/{query}

Triggers a full multi-agent report generation pipeline. The request passes through a Planner → Searcher → Reporter agent chain: the Planner decomposes the query into sub-tasks, the Searcher gathers evidence from the web, and the Reporter synthesises a structured report. This endpoint is significantly slower than /quick but produces a much more comprehensive result. Request format: multipart/form-data Response format: application/json
Because this endpoint orchestrates multiple LLM calls and web searches, it may take 30–120 seconds to respond depending on query complexity and your LLM provider’s latency. Consider it a background job rather than an interactive call.

​
Path Parameters

​
query
string
required
The research question or report topic.

​
Form Parameters

​
messages
string
required
A JSON-serialised array of Message objects representing the conversation context.
[{"role": "user", "content": "Write a report on renewable energy trends in 2024"}]
​
files
file
One or more file attachments (optional).

​
Response

​
report
string
The full multi-agent generated report as a single Markdown-formatted string.
​
files_received
array
Details of any uploaded files (filename + size).
​
messages_received
array
Echo of the parsed Message objects supplied in the request.

​
Example

curl -X POST "http://localhost:8000/report/renewable%20energy%20trends%202024" \
  -F 'messages=[{"role":"user","content":"Write a comprehensive report on renewable energy trends in 2024"}]'
Example response: 
{
  "report": "# Renewable Energy Trends in 2024\n\n## Executive Summary\n...",
  "files_received": [],
  "messages_received": [
    {
      "role": "user",
      "content": "Write a comprehensive report on renewable energy trends in 2024"
    }
  ]
}

​
GET /news/{category}

Returns today’s top news headlines for a given category, fetched via DuckDuckGo News. Response format: application/json

​
Path Parameters

​
category
string
required
The news category to retrieve. Examples: technology, finance, entertainment, sports, world, health.

​
Response

​
news
array
An array of news article objects returned by DuckDuckGo News for the given category. The exact fields of each item depend on the DuckDuckGo response.

​
Example

curl http://localhost:8000/news/technology
Example response: 
{
  "news": [
    {
      "title": "OpenAI Releases GPT-5",
      "snippet": "OpenAI has announced the release of its latest flagship model...",
      "link": "https://example.com/openai-gpt5"
    },
    {
      "title": "Apple Unveils New MacBook Pro",
      "snippet": "Apple today announced a new MacBook Pro with M4 Ultra...",
      "link": "https://example.com/apple-macbook"
    }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us