Search Documents¶

Search documents using AI-Semantic Search, Lexical (Keyword) Search, or Hybrid Search. Returns a list of relevant results.

Endpoint¶

POST /v20241104/search

API Request¶

Required Parameters

query string required

Query text for the search.

MinLength: 1 MaxLength: 1000

search_type string (enum) required

Type of search to perform.

Valid values: ai_semantic | hybrid | lexical
Info
- ai_semantic performs an AI-Semantic Search.
- hybrid performs a Hybrid Search.
- lexical performs a Lexical Search.
Which Search Type to Use?

If you're not sure which search type is best for your use case, we recommend starting with hybrid (and experimenting with different hybrid_search_ai_ratio parameter values) and then switching to ai_semantic or lexical search types if necessary.

Optional Parameters

ai_search_cutoff_score integer

Only documents with a score above this threshold will be considered. Default is 50.

Info

Use higher values (closer to 90) to consider only the most relevant documents. Use lower values to include more documents, even if they are less relevant.

Min: 0 Max: 90

Only applies to AI-Semantic Search and Hybrid Search (ignored for Lexical Search).

excerpts boolean

Whether to return an excerpt for each search result.

Info

Set this to false for use cases like ecommerce product search where excerpts are not typically displayed.

Default is true.

facet array of strings

Array specifying the facet criteria.

facet_advanced array of objects

Array of JSON objects specifying advanced facet criteria.

filter object

JSON object specifying the filter criteria.

fuzzy_search boolean

Whether to enable fuzzy searches, to account for typos.

Only applies to Lexical Search and Hybrid Search (ignored for AI-Semantic Search as it handles typos automatically).

Default is true.

highlights boolean

Whether to add highlights to relevant words/phrases in search results.

Info

Set this to false if you don't need to emphasize matching terms in search results, such as in ecommerce product search.

Default is true.

highlight_fragments integer

The maximum number of highlighted fragments to return. Default is 5.

Min: 1 Max: 10

highlight_fragment_size integer

The size of each highlighted fragment, in characters. Default is 100.

Min: 25 Max: 500

highlight_tags object

An object containing the tags used for highlighting search results. Used only when highlights is set to true.
Child parameters

pre_tag string required

The tag to insert before the highlighted term. Default is **.

MinLength: 1 MaxLength: 250

post_tag string required

The tag to insert after the highlighted term. Default is **.

MinLength: 1 MaxLength: 250

Example:
```
"highlight_tags": {
    "pre_tag": "<em>",
    "post_tag": "</em>"
}    
```
hybrid_search_ai_ratio float

Ratio used in Hybrid search, where higher values favor AI-Semantic matches over Lexical matches. Default is 0.6.

Ignored for other search types.

Min: 0.2 Max: 0.8

language string (enum)

Language code (of a supported language) that indicates the language of the documents to search.

Default is en.
Info
- Ignored if multilingual_search is true.
limit integer

Limit on the maximum number of results to return per request. Default is 10.

Additional results can be fetched if more are available.

Min: 1 Max: 100

multilingual_search boolean

Whether to search documents across multiple languages.

Default is false.
Info
- Can only be set to true for search_type = ai_semantic.
- If set to true:
  - Gainly will search documents across all languages.
  - language parameter will be ignored.
page integer

A cursor used for pagination when there are multiple pages of results. Default is 1.
Info
- Don't include this parameter in the initial API request.
- Set this to the next_page value from the previous API response to fetch the subsequent page of results.
Min: 1

sort array of objects

An array of JSON objects specifying sort criteria for the search results.

By default, search results are sorted in descending order of relevance score _score. This parameter allows you to override that behavior.

tenant_id array of strings

Array specifying one or more Tenant IDs.
Info
- Only documents with a tenant_id matching one of the values in the array will be considered.
- Example (single tenant ID):
```
"tenant_id": ["tenant123"],
```
- Example (multiple tenant IDs):
```
"tenant_id": ["tenant123", "tenant124"],
```
- For each tenant ID string:
  
  MinLength: 1 MaxLength: 250
MinLength: 1 MaxLength: 10

POST /v20241104/search

cURLAI PromptC#GoJavaNode.jsPHPPythonRuby

curl -X POST "https://api.gainly.ai/v20241104/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \  # (1)!
  -d '{
    "query": "what are the benefits of alpaca fleece?",
    "search_type": "hybrid"
  }'

Replace YOUR_API_KEY_HERE with the value of your API key.

# Prompt for AI coding assistants/IDEs (e.g., ChatGPT, Claude, GitHub Copilot, Cursor, Windsurf)

Using the Gainly API:
1. Write code to call the search_documents operation (see OpenAPI spec: https://api.gainly.ai/v20241104/openapi.json)
2. Use "hybrid" as the default value for the search_type parameter
3. Implement authentication using the header "X-API-Key" as described in the docs: https://docs.gainly.ai/latest/api-reference/authentication/
4. Implement rate limit handling as described in the docs: https://docs.gainly.ai/latest/api-reference/rate-limits/
5. Implement error handling
6. Handle the response according to the SearchResults schema in the OpenAPI spec
7. Implement pagination to handle multiple pages of results as described in the docs: https://docs.gainly.ai/latest/docs/pagination/

using System.Net.Http;
using System.Text.Json;
using System.Text;

var client = new HttpClient();

var url = "https://api.gainly.ai/v20241104/search";

var payload = new {
    query = "what are the benefits of alpaca fleece?",
    search_type = "hybrid"
};

var content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY_HERE"); // (1)!

var response = await client.PostAsync(url, content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

Replace YOUR_API_KEY_HERE with the value of your API key.

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://api.gainly.ai/v20241104/search"

    payload := map[string]interface{}{
        "query":       "what are the benefits of alpaca fleece?",
        "search_type": "hybrid",
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "YOUR_API_KEY_HERE") // (1)!

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result)
}

Replace YOUR_API_KEY_HERE with the value of your API key.

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

var client = HttpClient.newHttpClient();

var url = "https://api.gainly.ai/v20241104/search";

var payload = """
    {
        "query": "what are the benefits of alpaca fleece?",
        "search_type": "hybrid"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Content-Type", "application/json")
    .header("X-API-Key", "YOUR_API_KEY_HERE") // (1)!
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Replace YOUR_API_KEY_HERE with the value of your API key.

const axios = require('axios');  // or: import axios from 'axios';

const url = 'https://api.gainly.ai/v20241104/search';

const payload = {
    query: 'what are the benefits of alpaca fleece?',
    search_type: 'hybrid'
};

const headers = {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY_HERE' // (1)!
};

axios.post(url, payload, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error('Error:', error.message));

Replace YOUR_API_KEY_HERE with the value of your API key.

<?php

$client = new \GuzzleHttp\Client();

$url = 'https://api.gainly.ai/v20241104/search';

$payload = [
    'query' => 'what are the benefits of alpaca fleece?',
    'search_type' => 'hybrid'
];

$response = $client->request('POST', $url, [
    'json' => $payload,
    'headers' => [
        'Content-Type' => 'application/json',
        'X-API-Key' => 'YOUR_API_KEY_HERE' # (1)!
    ],
]);

echo $response->getBody();

Replace YOUR_API_KEY_HERE with the value of your API key.

import requests

url = "https://api.gainly.ai/v20241104/search"

payload = {
    "query": "what are the benefits of alpaca fleece?",
    "search_type": "hybrid"
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY_HERE" # (1)!
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)

Replace YOUR_API_KEY_HERE with the value of your API key.

require 'json'
require 'uri'
require 'net/http'
require 'openssl'

url = URI('https://api.gainly.ai/v20241104/search')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['X-API-Key'] = 'YOUR_API_KEY_HERE' # (1)!
request.body = {
    query: 'what are the benefits of alpaca fleece?',
    search_type: 'hybrid'
}.to_json

response = http.request(request)
puts response.read_body

Replace YOUR_API_KEY_HERE with the value of your API key.

API Response¶

{
    "object": "search_result",
    "url": "/v20241104/search",
    "query": "what are the benefits of alpaca fleece?",
    "search_type": "hybrid",
    "hybrid_search_ai_ratio": 0.6,
    "data": [
        {
            "id": "4nD1gZIB7caKVIeL2MgL",
            "title": "**Alpaca** **Fleece** and Its Economic Impact",
            "excerpt": "...**Alpaca** **Fleece** and Its Economic Impact... **Alpaca** **fleece** is one of the most valued natural fibers in the world, known for its softness, warmth,... Unlike sheep's wool, **alpaca** **fleece** does not contain lanolin, making it hypoallergenic and more suitable... There are two types of **alpaca** **fleece**: Huacaya and Suri... Huacaya **fleece** is crimped, giving it a fluffy appearance, while Suri **fleece** is silky and forms long,...",
            "confidence_level": "very_high",
            "metadata": null,
            "source_uri": "/doc/alpaca-fleece-economic-20241012a",
            "tenant_id": "tenant226",
            "language": "en",
            "sort_value": null,
            "created_at": "2024-10-12T18:20:25.358391Z",
            "updated_at": "2024-10-12T18:20:25.358405Z"
        },
        {
            "id": "B3AegpIB7caKVIeL78nJ",
            "title": "**Alpaca** Fiber Processing and Textile Production",
            "excerpt": "...**Alpaca** yarn is prized for its softness, warmth, and durability, making it a favorite among knitters,... The natural colors of **alpaca** **fleece**, ranging from white to black and various shades of brown and gray... but also support local economies in **alpaca**-producing regions... The craftsmanship involved in transforming raw **fleece** into finished goods is a testament to the enduring... value and appeal of **alpaca** fiber in the global market...",
            "confidence_level": "high",
            "metadata": null,
            "source_uri": "/doc/alpaca-fiber-textile-20241012",
            "tenant_id": "tenant226",
            "language": "en",
            "sort_value": null,
            "created_at": "2024-10-12T19:05:18.420115Z",
            "updated_at": "2024-10-12T19:05:18.420159Z"
        },
        {
            "id": "DHAggpIB7caKVIeLN8lu",
            "title": "**Alpaca** Fiber and the Global Fashion Industry",
            "excerpt": "...**Alpaca** Fiber and the Global Fashion Industry... **Alpaca** fiber has gained significant recognition in the global fashion industry due to its luxurious qualities... Known for its softness, warmth, and durability, **alpaca** fiber is often compared to cashmere and is highly... Unlike sheep wool, **alpaca** fiber lacks lanolin, making it hypoallergenic and suitable for people with... natural luster, giving it a silky appearance that enhances the visual appeal of garments made from **alpaca**...",
            "confidence_level": "medium",
            "metadata": null,
            "source_uri": "/doc/alpaca-fiber-global-fashion-20241012",
            "tenant_id": "tenant226",
            "language": "en",
            "sort_value": null,
            "created_at": "2024-10-12T19:06:42.297067Z",
            "updated_at": "2024-10-12T19:06:42.297080Z"
        }
    ],
    "tenant_id": null,
    "filter": null,
    "sort": [
        {
            "_score": {
                "order": "desc"
            }
        }
    ],
    "facet": null,
    "facet_advanced": null,
    "facet_result": {},
    "language": "en",
    "multilingual_search": false,
    "fuzzy_search": null,
    "has_more": false,
    "next_page": null,
    "total_number_of_results": 3,
    "page": 1,
    "limit": 10,
    "highlights": true,
    "excerpts": true,
    "ai_search_cutoff_score": 35,
    "token_usage": {
        "semantic_tokens": 5,
        "llm_tokens": {
            "llm_output_tokens": 0,
            "llm_input_tokens": 0,
            "model": null
        }
    },
    "livemode": false
}

The response shown above is for Hybrid Search. The response for AI-Semantic Search and Lexical Search will be identical with these exceptions:

search_type value of ai_semantic or lexical.
semantic_tokens value of 0 for Lexical search, as it does not consume semantic tokens.

If no matches are found for the search term, the API response will be identical to the one above but with an empty data array and a total_number_of_results value of 0.

    "data": [],
    "total_number_of_results": 0,

Excerpt¶

excerpt represents the relevant part of the document that matches the search.

Confidence Level¶

confidence_level represents Gainly's assessment of how relevant a document is to the search.

Info

confidence_level is derived from the relevance score (_score) and represents a more human-readable value.

It will have one of the following values:

very_high
high
medium
low
not_available

Please see basic faceting and advanced faceting for details on the facet_result property.

Pagination¶

Please see pagination for details on navigating multiple pages of results.