Search files

Ask a question across your uploaded files, or only within chosen files and folders, and get the most relevant passages back.

POST /search returns the most relevant text chunks, each with its source file_id, score, and metadata such as page or content type when available.

Reference

Request fields

Field	Description
`query`	The question or search text.
`top_k`	Chunks to return, 1 to 100. Default `5`.
`filters`	Optional file, folder, or metadata filters; see Filters.
`rerank`	Improves result ordering. Default `true`; set `false` for a faster response when approximate ordering is enough.

Filters

Filter	Searches
`file_ids`	The listed files, e.g. the ones the user selected.
`folder_ids`	A folder and its contents. The literal `root` searches root-level files.
Metadata produced during processing, e.g. `"type": "table"`	Chunks with that metadata, e.g. table-heavy files.

If you pass both file_ids and folder_ids, a chunk matches when its file is in either: one of the listed files or inside one of the folders.
If you pass file_ids or folder_ids but every list you pass is empty, the response has no chunks.
Metadata filters apply on top of the file and folder scope.

Response

Field	Description
`query`	The query you sent.
`chunks`	The results, each with `id`, `file_id`, `text`, `score`, and `metadata`.
`latency_ms`	Time the search took, in milliseconds.

Search all files

To search, wait until your files finish processing, then send POST /search with a query and top_k.

Python

import httpx

FILES_URL = "https://alo-files-service-103105631559.europe-west8.run.app"
HEADERS = {
    "X-API-Key": "sk-your-api-key",
    "X-Space-Slug": "acme",
}

result = httpx.post(
    f"{FILES_URL}/search",
    headers=HEADERS,
    json={
        "query": "What termination rights are in the supplier contracts?",
        "top_k": 5,
    },
).json()

for chunk in result["chunks"]:
    print(chunk["file_id"], chunk["text"][:200])

To use the results, read chunks: each chunk has its id, text, its source file_id, a score, and metadata such as page or content type when available.

Search selected files or folders

To limit the search, add filters to the request: file_ids searches the listed files, and folder_ids searches a folder and its contents (root for root-level files). If you pass both, results come from either.
```
{
  "query": "Summarize the commercial terms",
  "filters": {
    "file_ids": ["4a6fbf7d-4d0f-4636-9a5d-06c80c0d8d89"]
  }
}
```

Troubleshooting

Search returns `503`

The search did not finish within its time limit (60 seconds by default). The body has code resource_busy and details.retryable true; retry the request.

On this page