> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.eyelevel.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.eyelevel.ai/_mcp/server. # search.documents POST https://api.groundx.ai/api/v1/search/documents Content-Type: application/json Search documents on GroundX for the most relevant information to a given query by documentId(s). The result of this query is typically used in one of two ways; `result.search.text` can be used to provide context to a language model, facilitating RAG, or `result.search.results` can be used to observe chunks of text which are relevant to the query, facilitating citation. Reference: https://docs.eyelevel.ai/reference/api-reference/search/documents ## Authentication - `X-API-Key` header (required) — API Key authentication via header ## Request ### Query parameters - `n` (integer, optional, default: 20) — The maximum number of returned search results. Accepts 1-100 with a default of 20. - `nextToken` (string, optional) — A token for pagination. If the number of search results for a given query is larger than n, the response will include a "nextToken" value. That token can be included in this field to retrieve the next batch of n search results. - `verbosity` (integer, optional) — The amount of data returned with each search result. 0 == no search results, only the recommended context. 1 == search results but no searchData. 2 == search results and searchData. ### Body (application/json) This endpoint expects a SearchDocumentsRequest. - `query` (string, required, default: my search query) — The search query to be used to find relevant documentation. - `documentIds` (list of string, required) — An array of unique documentIds to be searched. - `filter` (SearchDocumentsRequestFilter, optional) — A dictionary of key-value pairs that can be used to pre-filter documents prior to a search. - `relevance` (double, optional, default: 10) — The minimum search relevance score required to include the result. By default, this is 10.0. ## Response ### 200 Search query success - `search` (SearchResponseSearch, required) ## Errors ### 400 Bad Request Error Invalid request data - `any` ### 401 Unauthorized Error Unauthorized to access resource with given ID - `any` ## Types ### SearchDocumentsRequestFilter A dictionary of key-value pairs that can be used to pre-filter documents prior to a search. ### SearchResponseSearch - `count` (integer, optional) — Total results - `results` (list of SearchResultItem, optional) — Search results - `query` (string, optional) — The original search request query - `score` (double, optional) — Confidence score in the search results - `searchQuery` (string, optional) — The actual search query, if the search request query was re-written - `text` (string, optional) — Suggested context for LLM completion - `nextToken` (string, optional) — For paginated results ### SearchResultItem - `boundingBoxes` (list of BoundingBoxDetail, optional) — Coordinates corresponding to the areas of the document where the chunk appears - `bucketId` (integer, optional) — Content bucket the search result belongs to - `chunkId` (string, optional) — Unique system generated ID for the chunk - `documentId` (string, optional) — Unique system generated ID for the document - `fileName` (string, optional) — Name of ingested file - `fileSummary` (string, optional) — System-generated summary of the source document - `multimodalUrl` (string, optional) — An image clipping of the table or figure object from the document - `pageImages` (list of string, optional) - `pages` (list of SearchResultItemPagesItems, optional) - `processId` (string, optional) — Unique system generated ID for the ingest process that included this document - `score` (double, optional) — Confidence score in the search result - `searchData` (SearchResultItemSearchData, optional) — Document, section, and chunk search data, both custom and system-generated - `sectionSummary` (string, optional) — System-generated summary of the document section containing this result - `sourceUrl` (string, optional) — Source document URL - `suggestedText` (string, optional) — System-generated text, re-written for LLM completions - `text` (string, optional) — Original text from the source document ### BoundingBoxDetail - `bottomRightX` (double, optional) — The x coordinate of the lower right corner of the bounding box - `bottomRightY` (double, optional) — The y coordinate of the lower right corner of the bounding box - `pageNumber` (integer, optional) — The page number the bounding box appears on, using a 1-based array indexing (starts with page 1, not page 0) - `topLeftX` (double, optional) — The x coordinate of the upper left corner of the bounding box - `topLeftY` (double, optional) — The y coordinate of the upper left corner of the bounding box ### SearchResultItemPagesItems - `height` (double, optional) — The height of the page image - `imageUrl` (string, optional) — A jpg of the page the chunk appears on - `number` (double, optional) — The page number - `width` (double, optional) — The width of the page image ### SearchResultItemSearchData Document, section, and chunk search data, both custom and system-generated ## Examples **Request** ```json { "query": "climate change impact on agriculture", "documentIds": [ "a3f1c9e2-4b7d-4f8a-9c2e-1d2f3b4a5c6d", "b7e2d3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f" ] } ``` **Response** ```json { "search": { "count": 1, "results": [ { "boundingBoxes": [ { "bottomRightX": 450.5, "bottomRightY": 780.3, "pageNumber": 3, "topLeftX": 120, "topLeftY": 700 } ], "bucketId": 42, "chunkId": "chunk-9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d", "documentId": "a3f1c9e2-4b7d-4f8a-9c2e-1d2f3b4a5c6d", "fileName": "Climate_Change_Agriculture_Study.pdf", "fileSummary": "A comprehensive study on the effects of climate change on global agricultural productivity.", "multimodalUrl": "https://cdn.groundx.ai/images/climate_change_fig3.png", "pageImages": [ "https://cdn.groundx.ai/pages/climate_change_page3.jpg" ], "pages": [ { "height": 1123, "imageUrl": "https://cdn.groundx.ai/pages/climate_change_page3.jpg", "number": 3, "width": 794 } ], "processId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90", "score": 95.7, "searchData": {}, "sectionSummary": "This section discusses the projected decrease in crop yields due to rising temperatures and altered precipitation patterns.", "sourceUrl": "https://www.example-research.org/climate-agriculture", "suggestedText": "Rising global temperatures are expected to reduce crop yields significantly in tropical and temperate regions.", "text": "Recent studies indicate that climate change will adversely affect agricultural output, particularly in vulnerable regions where temperature increases and water scarcity are most pronounced." } ], "query": "climate change impact on agriculture", "score": 95.7, "searchQuery": "climate change impact on agriculture", "text": "Rising global temperatures and changing precipitation patterns are expected to impact agricultural productivity worldwide.", "nextToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwYWdlIjoxfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" } } ``` **SDK Code** ```python import requests url = "https://api.groundx.ai/api/v1/search/documents" payload = { "query": "climate change impact on agriculture", "documentIds": ["a3f1c9e2-4b7d-4f8a-9c2e-1d2f3b4a5c6d", "b7e2d3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"] } headers = { "X-API-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.groundx.ai/api/v1/search/documents'; const options = { method: 'POST', headers: {'X-API-Key': '', 'Content-Type': 'application/json'}, body: '{"query":"climate change impact on agriculture","documentIds":["a3f1c9e2-4b7d-4f8a-9c2e-1d2f3b4a5c6d","b7e2d3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"]}' }; 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.groundx.ai/api/v1/search/documents" payload := strings.NewReader("{\n \"query\": \"climate change impact on agriculture\",\n \"documentIds\": [\n \"a3f1c9e2-4b7d-4f8a-9c2e-1d2f3b4a5c6d\",\n \"b7e2d3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f\"\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-Key", "") 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.groundx.ai/api/v1/search/documents") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-API-Key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"query\": \"climate change impact on agriculture\",\n \"documentIds\": [\n \"a3f1c9e2-4b7d-4f8a-9c2e-1d2f3b4a5c6d\",\n \"b7e2d3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f\"\n ]\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.groundx.ai/api/v1/search/documents") .header("X-API-Key", "") .header("Content-Type", "application/json") .body("{\n \"query\": \"climate change impact on agriculture\",\n \"documentIds\": [\n \"a3f1c9e2-4b7d-4f8a-9c2e-1d2f3b4a5c6d\",\n \"b7e2d3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f\"\n ]\n}") .asString(); ``` ```php request('POST', 'https://api.groundx.ai/api/v1/search/documents', [ 'body' => '{ "query": "climate change impact on agriculture", "documentIds": [ "a3f1c9e2-4b7d-4f8a-9c2e-1d2f3b4a5c6d", "b7e2d3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f" ] }', 'headers' => [ 'Content-Type' => 'application/json', 'X-API-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.groundx.ai/api/v1/search/documents"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"query\": \"climate change impact on agriculture\",\n \"documentIds\": [\n \"a3f1c9e2-4b7d-4f8a-9c2e-1d2f3b4a5c6d\",\n \"b7e2d3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f\"\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "X-API-Key": "", "Content-Type": "application/json" ] let parameters = [ "query": "climate change impact on agriculture", "documentIds": ["a3f1c9e2-4b7d-4f8a-9c2e-1d2f3b4a5c6d", "b7e2d3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f"] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.groundx.ai/api/v1/search/documents")! 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() ```