> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.tropicalia.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tropicalia.dev/_mcp/server. # Search POST https://api.tropicalia.dev/v1/projects/{projectId}/search Content-Type: application/json Perform a semantic search across project documents Reference: https://docs.tropicalia.dev/api-reference/search ## Authentication - `Authorization` header (bearer token, required) — API key with `tr_` prefix (e.g., `tr_abc123`) ## Request ### Path parameters - `projectId` (string, required) — Project ID to search within ### Body (application/json) This endpoint expects a SearchRequest. - `query` (string, required) — Search query text (max 2048 tokens) - `retrieval_strategy` (enum, optional) - Allowed values: `hybrid`, `neural`, `keyword` - `expand_query` (boolean, optional, default: false) — Generate query variations to improve recall - `rerank` (boolean, optional, default: false) — Rerank results using Cohere for improved relevance - `generate_answer` (boolean, optional, default: true) — Generate a natural-language answer - `include_sources` (boolean, optional, default: true) — Include source documents in response. Set false to reduce payload when only the answer is needed. - `limit` (integer, optional, default: 50) — Maximum results to return ## Response ### 200 Search results - `retrieval_contents` (list of RetrievalContent, required) - `completion` (string, optional, nullable) — AI-generated answer (when generate_answer is true) ## Types ### RetrievalContent - `number` (integer, required) — Citation position [[N]] - `id` (string, required) — Chroma vector ID - `document` (string, required) — Text content of the chunk - `score` (double, required) — Relevance score - `metadata` (RetrievalMetadata, required) - `rerank_score` (double, optional, nullable) — Rerank relevance score (only present when rerank is enabled) ### RetrievalMetadata - `document_id` (string, required) — Source document UUID - `file_name` (string, required) — Original filename - `type` (enum, required) — Content type - Allowed values: `chunk` - `chunk_index` (integer, required) — Position of chunk within document - `date_created` (datetime, required) — When the chunk was indexed - `document_title` (string, optional) — Extracted title from document - `chunk_size` (integer, optional) — Token count of the chunk - `page` (string, optional) — JSON array of page numbers (e.g. "[1, 2]") ## Examples **Request** ```json { "query": "Best practices for sustainable tropical agriculture", "retrieval_strategy": "hybrid", "expand_query": false, "rerank": true, "generate_answer": true, "include_sources": true, "limit": 50 } ``` **Response** ```json { "retrieval_contents": [ { "number": 1, "id": "a3f1c9d2-4b7e-4f8a-9c3d-2e5b7f6a1d9e", "document": "Sustainable tropical agriculture focuses on methods that preserve soil fertility and biodiversity while maximizing crop yields.", "score": 0.92, "metadata": { "document_id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f7a", "file_name": "sustainable_farming_tropics.pdf", "type": "chunk", "chunk_index": 3, "date_created": "2024-01-15T09:30:00Z", "document_title": "Sustainable Farming Techniques in Tropical Regions", "chunk_size": 512, "page": "[12, 13]" }, "rerank_score": 0.95 } ], "completion": "Sustainable tropical agriculture involves crop diversification, soil conservation, and integrated pest management to maintain ecosystem health and productivity." } ``` **SDK Code** ```python import requests url = "https://api.tropicalia.dev/v1/projects/proj_9f8b7c6d/search" payload = { "query": "Best practices for sustainable tropical agriculture", "retrieval_strategy": "hybrid", "expand_query": False, "rerank": True, "generate_answer": True, "include_sources": True, "limit": 50 } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.tropicalia.dev/v1/projects/proj_9f8b7c6d/search'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"query":"Best practices for sustainable tropical agriculture","retrieval_strategy":"hybrid","expand_query":false,"rerank":true,"generate_answer":true,"include_sources":true,"limit":50}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.tropicalia.dev/v1/projects/proj_9f8b7c6d/search" payload := strings.NewReader("{\n \"query\": \"Best practices for sustainable tropical agriculture\",\n \"retrieval_strategy\": \"hybrid\",\n \"expand_query\": false,\n \"rerank\": true,\n \"generate_answer\": true,\n \"include_sources\": true,\n \"limit\": 50\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.tropicalia.dev/v1/projects/proj_9f8b7c6d/search") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"query\": \"Best practices for sustainable tropical agriculture\",\n \"retrieval_strategy\": \"hybrid\",\n \"expand_query\": false,\n \"rerank\": true,\n \"generate_answer\": true,\n \"include_sources\": true,\n \"limit\": 50\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.tropicalia.dev/v1/projects/proj_9f8b7c6d/search") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"query\": \"Best practices for sustainable tropical agriculture\",\n \"retrieval_strategy\": \"hybrid\",\n \"expand_query\": false,\n \"rerank\": true,\n \"generate_answer\": true,\n \"include_sources\": true,\n \"limit\": 50\n}") .asString(); ``` ```php request('POST', 'https://api.tropicalia.dev/v1/projects/proj_9f8b7c6d/search', [ 'body' => '{ "query": "Best practices for sustainable tropical agriculture", "retrieval_strategy": "hybrid", "expand_query": false, "rerank": true, "generate_answer": true, "include_sources": true, "limit": 50 }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.tropicalia.dev/v1/projects/proj_9f8b7c6d/search"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"query\": \"Best practices for sustainable tropical agriculture\",\n \"retrieval_strategy\": \"hybrid\",\n \"expand_query\": false,\n \"rerank\": true,\n \"generate_answer\": true,\n \"include_sources\": true,\n \"limit\": 50\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "query": "Best practices for sustainable tropical agriculture", "retrieval_strategy": "hybrid", "expand_query": false, "rerank": true, "generate_answer": true, "include_sources": true, "limit": 50 ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.tropicalia.dev/v1/projects/proj_9f8b7c6d/search")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```