Retrieve Passages¶

Retrieve relevant passages based on the user's query. Enables you to quickly build powerful LLM applications.

What are passages?

Passages are semantically meaningful excerpts extracted from your documents. Each passage is approximately 100-200 words long, and represents either an entire document or a section of a document.

These passages serve as context for your Large Language Model (LLM) when building LLM applications.

Retrieval-Augmented Generation (RAG)

If you're building a RAG system, we recommend our Generate Answer endpoint which provides a complete RAG system. For other LLM applications, we recommend using this Retrieve Passages endpoint as your retrieval system.

Endpoint¶

POST /v20241104/retrieve

API Request¶

Required Parameters

query string required

Query text for the search.

MinLength: 1 MaxLength: 10000

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

document_id array of strings

Array specifying one or more document IDs.
Info
- Only documents with an id matching one of the values in the array will be considered.
- Example (single document ID):
```
"document_id": ["4nD1gZIB7caKVIeL2MgL"]
```
- Example (multiple document IDs):
```
"document_id": ["4nD1gZIB7caKVIeL2MgL", "4wdRU5QBP4_EawzZupIF"]
```
- For each document ID string:
  
  MinLength: 1 MaxLength: 128
MinLength: 1 MaxLength: 10

filter object

JSON object specifying the filter criteria.

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.
multilingual_search boolean

Whether to search documents across multiple languages.

Default is false.
Info

If set to true:
- Gainly will search documents across all languages.
- language parameter will be ignored.
retrieval_limit integer

Limit on the maximum number of relevant passages retrieved. Default is 10.

Info

Lower values will result in your LLM consuming fewer input tokens, but may also result in a less relevant answer.

For most use cases, we recommend a value between 5 and 25.

Min: 1 Max: 100

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/retrieve

cURLAI PromptC#GoJavaNode.jsPHPPythonRuby

curl -X POST "https://api.gainly.ai/v20241104/retrieve" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \  # (1)!
  -d '{
    "query": "does alpaca fleece contain lanolin"
  }'

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 operation with ID "retrieve" (see OpenAPI spec: https://api.gainly.ai/v20241104/openapi.json)
2. Implement authentication using the header "X-API-Key" as described in the docs: https://docs.gainly.ai/latest/api-reference/authentication/
3. Implement rate limit handling as described in the docs: https://docs.gainly.ai/latest/api-reference/rate-limits/
4. Implement error handling
5. Handle the response according to the RetrieveResults schema in the OpenAPI spec

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

var client = new HttpClient();

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

var payload = new {
    query = "does alpaca fleece contain lanolin"
};

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/retrieve"

    payload := map[string]interface{}{
        "query": "does alpaca fleece contain lanolin",
    }

    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/retrieve";

var payload = """
    {
        "query": "does alpaca fleece contain lanolin"
    }
    """;

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/retrieve';

const payload = {
    query: "does alpaca fleece contain lanolin"
};

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/retrieve';

$payload = [
    'query' => 'does alpaca fleece contain lanolin'
];

$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/retrieve"

payload = {
    "query": "does alpaca fleece contain lanolin"
}

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/retrieve')

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: 'does alpaca fleece contain lanolin'
}.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": "retrieve_result",
    "url": "/v20241104/retrieve",
    "query": "does alpaca fleece contain lanolin",
    "data": [
        {
            "passage": "Alpaca Fleece and Its Economic Impact. Alpaca fleece is one of the most valued natural fibers in the world, known for its softness, warmth, and hypoallergenic properties. Unlike sheep's wool, alpaca fleece does not contain lanolin, making it hypoallergenic and more suitable for people with sensitive skin. The fiber is also naturally water-resistant and has excellent thermal insulation properties, making it an ideal material for cold-weather clothing. 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, shiny locks.",
            "document_id": "4nD1gZIB7caKVIeL2MgL",
            "title": "Alpaca Fleece and Its Economic Impact",
            "source_uri": "/doc/alpaca-fleece-economic-20241012",
            "confidence_level": "high",
            "tenant_id": "tenant123",
            "language": "en",
            "created_at": "2024-10-12T18:20:25.358391Z",
            "updated_at": "2024-10-12T18:20:25.358405Z"
        },
        {
            "passage": "Alpaca yarn is prized for its softness, warmth, and durability, making it a favorite among knitters, weavers, and textile manufacturers. It is used to create a wide range of products, including sweaters, scarves, hats, blankets, and more. In addition to its natural warmth, alpaca fiber is also lightweight and breathable, making it suitable for both winter and summer garments. The natural colors of alpaca fleece, ranging from white to black and various shades of brown and gray, allow for beautiful, undyed textiles, though the fiber also takes dye well for more vibrant colors.\n\nThe processing and production of alpaca textiles not only provide high-quality, sustainable products 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.",
            "document_id": "B3AegpIB7caKVIeL78nJ",
            "title": "Alpaca Fiber Processing and Textile Production",
            "source_uri": "/doc/alpaca-fiber-textile-20241012",
            "confidence_level": "medium",
            "tenant_id": "tenant123",
            "language": "en",
            "created_at": "2024-10-12T19:05:18.420115Z",
            "updated_at": "2024-10-12T19:05:18.420159Z"
        },
        {
            "passage": "Alpaca Fiber and the Global Fashion Industry. Alpaca fiber has gained significant recognition in the global fashion industry due to its luxurious qualities and sustainable production. Known for its softness, warmth, and durability, alpaca fiber is often compared to cashmere and is highly sought after by fashion designers and textile manufacturers. Unlike sheep wool, alpaca fiber lacks lanolin, making it hypoallergenic and suitable for people with sensitive skin. It also has a natural luster, giving it a silky appearance that enhances the visual appeal of garments made from alpaca fiber.",
            "document_id": "DHAggpIB7caKVIeLN8lu",
            "title": "Alpaca Fiber and the Global Fashion Industry",
            "source_uri": "/doc/alpaca-fiber-global-fashion-20241012",
            "confidence_level": "medium",
            "tenant_id": "tenant123",
            "language": "en",
            "created_at": "2024-10-12T19:06:42.297067Z",
            "updated_at": "2024-10-12T19:06:42.297080Z"
        },
        {
            "passage": "Alpaca Fiber Processing and Textile Production. Once alpaca fleece is harvested, it undergoes a series of processing steps to transform it into usable fiber for textile production. The process begins with sorting and grading the fleece based on fiber quality, length, and color. The finest and softest fibers are reserved for high-end products, while coarser fibers may be used for rugs or other durable items. After sorting, the fleece is cleaned to remove dirt, debris, and natural oils.\n\nThe cleaned fleece is then carded, a process that disentangles and aligns the fibers, making them easier to spin into yarn. Depending on the desired texture and thickness of the yarn, the fibers may be blended with other natural or synthetic fibers during this stage. The carded fibers are then spun into yarn using either traditional hand-spinning methods or modern spinning machines. The resulting yarn can vary in thickness, strength, and texture, depending on its intended use.",
            "document_id": "B3AegpIB7caKVIeL78nJ",
            "title": "Alpaca Fiber Processing and Textile Production",
            "source_uri": "/doc/alpaca-fiber-textile-20241012",
            "confidence_level": "medium",
            "tenant_id": "tenant123",
            "language": "en",
            "created_at": "2024-10-12T19:05:18.420115Z",
            "updated_at": "2024-10-12T19:05:18.420159Z"
        },
        {
            "passage": "One of the key selling points of alpaca fiber in the fashion industry is its sustainability. Alpacas are gentle on the environment, with a low ecological footprint compared to other livestock. They require less water and food, and their soft-padded feet do not damage the ground, making them an eco-friendly option for fiber production. Additionally, alpaca farming supports rural economies, particularly in the Andean regions of South America, where the majority of the world's alpaca population is found.\n\nThe rise of eco-conscious consumerism has further boosted the popularity of alpaca fiber in the fashion industry. Consumers are increasingly seeking out products that are not only high-quality but also produced in a way that minimizes environmental impact and supports ethical labor practices. Alpaca fiber fits well within this trend, offering a natural, biodegradable, and renewable resource that aligns with the values of sustainability and social responsibility.",
            "document_id": "DHAggpIB7caKVIeLN8lu",
            "title": "Alpaca Fiber and the Global Fashion Industry",
            "source_uri": "/doc/alpaca-fiber-global-fashion-20241012",
            "confidence_level": "medium",
            "tenant_id": "tenant123",
            "language": "en",
            "created_at": "2024-10-12T19:06:42.297067Z",
            "updated_at": "2024-10-12T19:06:42.297080Z"
        },
        {
            "passage": "The global demand for alpaca fiber has led to its use in a wide range of fashion products, including sweaters, scarves, coats, and accessories. High-end fashion brands have incorporated alpaca fiber into their collections, recognizing its versatility and the growing consumer interest in sustainable and ethically sourced materials. Alpaca fiber is available in a variety of natural colors, from white and fawn to brown, gray, and black, allowing designers to create pieces with a natural palette or dye the fiber for more vibrant colors.",
            "document_id": "DHAggpIB7caKVIeLN8lu",
            "title": "Alpaca Fiber and the Global Fashion Industry",
            "source_uri": "/doc/alpaca-fiber-global-fashion-20241012",
            "confidence_level": "medium",
            "tenant_id": "tenant123",
            "language": "en",
            "created_at": "2024-10-12T19:06:42.297067Z",
            "updated_at": "2024-10-12T19:06:42.297080Z"
        },
        {
            "passage": "The global demand for alpaca fleece has led to a significant economic impact in the regions where alpacas are bred, particularly in Peru, which is home to the largest population of alpacas in the world. The fleece is harvested once a year, and a single alpaca can produce around 5 to 10 pounds of fleece annually. The quality of the fleece can vary based on the age and breed of the alpaca, with the finest and softest fibers typically coming from younger animals.",
            "document_id": "4nD1gZIB7caKVIeL2MgL",
            "title": "Alpaca Fleece and Its Economic Impact",
            "source_uri": "/doc/alpaca-fleece-economic-20241012",
            "confidence_level": "low",
            "tenant_id": "tenant123",
            "language": "en",
            "created_at": "2024-10-12T18:20:25.358391Z",
            "updated_at": "2024-10-12T18:20:25.358405Z"
        },
        {
            "passage": "As the fashion industry continues to evolve, alpaca fiber is expected to play an even larger role in the production of luxury and sustainable garments. Its unique properties and ethical production make it a valuable asset for designers looking to create beautiful, high-quality fashion that meets the demands of today's conscientious consumers. The growing global interest in alpaca fiber also highlights the importance of preserving traditional practices and supporting the communities that have raised and cared for these animals for generations.",
            "document_id": "DHAggpIB7caKVIeLN8lu",
            "title": "Alpaca Fiber and the Global Fashion Industry",
            "source_uri": "/doc/alpaca-fiber-global-fashion-20241012",
            "confidence_level": "low",
            "tenant_id": "tenant123",
            "language": "en",
            "created_at": "2024-10-12T19:06:42.297067Z",
            "updated_at": "2024-10-12T19:06:42.297080Z"
        },
        {
            "passage": "Alpaca farming is often seen as a sustainable and profitable agricultural practice. Small-scale farmers can raise alpacas for fleece production, which can be sold raw or processed into yarn, garments, and other textiles. In regions like the Andes, where the harsh climate makes traditional farming challenging, alpaca farming provides a reliable source of income for rural communities. Additionally, the growing interest in sustainable and ethically sourced materials has increased the popularity of alpaca fleece in the global market, leading to higher prices and greater opportunities for breeders and artisans.",
            "document_id": "4nD1gZIB7caKVIeL2MgL",
            "title": "Alpaca Fleece and Its Economic Impact",
            "source_uri": "/doc/alpaca-fleece-economic-20241012",
            "confidence_level": "low",
            "tenant_id": "tenant123",
            "language": "en",
            "created_at": "2024-10-12T18:20:25.358391Z",
            "updated_at": "2024-10-12T18:20:25.358405Z"
        },
        {
            "passage": "Alpaca owners need to be vigilant about signs of illness, as alpacas can be quite stoic and may not show obvious symptoms until they are seriously ill. Common indicators of health problems include weight loss, lethargy, changes in appetite, and abnormal behavior. Routine health checks, including regular monitoring of body condition, dental care, and hoof trimming, are important to catch any issues early.\n\nOne unique aspect of alpaca care is managing their teeth. Since alpacas' teeth continue to grow throughout their lives, it may be necessary to file or trim them if they become too long, particularly the fighting teeth of males. Another critical aspect of alpaca health is shearing. Alpacas need to be shorn once a year to prevent overheating and to maintain the quality of their fleece. Proper shearing also reduces the risk of skin infections and helps keep the animals comfortable, especially in warmer climates.",
            "document_id": "9HD5gZIB7caKVIeLg8hd",
            "title": "Alpaca Health and Veterinary Care",
            "source_uri": "/doc/alpaca-health-vet-20241012",
            "confidence_level": "low",
            "tenant_id": "tenant123",
            "language": "en",
            "created_at": "2024-10-12T18:24:25.828278Z",
            "updated_at": "2024-10-12T18:24:25.828292Z"
        }
    ],
    "document_id": null,
    "tenant_id": null,
    "filter": null,
    "language": null,
    "multilingual_search": true,
    "retrieval_limit": 10,
    "ai_search_cutoff_score": 35,
    "total_number_of_results": 20,
    "token_usage": {
        "semantic_tokens": 9,
        "llm_tokens": {
            "llm_output_tokens": 0,
            "llm_input_tokens": 0,
            "model": null
        }
    },
    "livemode": false
}

Confidence Level¶

confidence_level represents Gainly's assessment of how relevant a passage is to the query.

It will have one of the following values:

very_high
high
medium
low
not_available

Token Usage¶

token_usage indicates the number of tokens used to process the query.

"token_usage": {
    "semantic_tokens": 9,      // determined by the size of 'query' field
    "llm_tokens": {
        "llm_output_tokens": 0,
        "llm_input_tokens": 0,
        "model": null
    }
}