Quickstart Guide

In this guide, we'll use Postman to add a few documents to your Gainly semantic index and then perform a Hybrid search.

Set Up Postman¶

First download the Postman app, then install and launch it
Once you launch Postman, click the New button
Then select HTTP
Click the Headers tab
1. Under the Key column, enter: x-api-key
2. Under the Value column, paste the Test API Key from your Gainly Dashboard.

Add Documents¶

Now we'll add some documents to your Gainly semantic index using the Add Document endpoint.

In Postman, change the HTTP method to POST
Enter the following URL:

https://api.gainly.ai/v20241104/documents
Click the Body tab:

Click the raw radiobutton, and then select JSON in the dropdown menu

Then enter a document into the body field:

{
    "title": "",    
    "content": ""
}

If you have your own document to add, you can add it into the title and content parameters. If you don't have any documents handy, feel free to use this example document:

{
    "title": "Alpaca Fleece and Its Economic Impact",
    "content": "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.\n\nThe 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.\n\nAlpaca 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."
}

Then click the Send button to add your document
If your document was created successfully, you'll see a 200 OK response

The response will include a unique id for your document
Congrats! You just added your first document! 🥳

Now let's add two more documents by repeating the steps above. Feel free to use your own documents, or use the following two example documents:

{
    "title": "Alpaca Behavior and Social Structure",
    "content": "Alpacas are highly social animals, and their behavior is largely shaped by their herd dynamics. They have a well-defined social structure within the herd, often with a dominant female taking the lead. This hierarchy is usually established through subtle behaviors such as body posturing, spitting, and even gentle pushing. The social bonds within the herd are strong, and alpacas often exhibit a sense of loyalty and companionship, sticking close to one another for safety and comfort.\n\nOne of the most endearing behaviors of alpacas is their gentle humming. This soft, continuous sound is believed to be a form of communication, expressing a range of emotions from contentment to concern. Mothers often hum to their newborns, known as cria, to reassure them and strengthen their bond. In contrast, alpacas can also produce a loud, high-pitched scream when they feel threatened or are warning the herd of potential danger. This alarm call is an instinctual behavior passed down from their wild ancestors, who relied on this vocalization to alert the group to predators.\n\nAlpacas also engage in dust bathing, a common behavior where they roll in dry dirt or sand to coat their fur. This behavior helps them manage parasites and maintain their fleece in good condition. While they are generally gentle and approachable, alpacas can become defensive if they feel their personal space is invaded, especially during feeding times. They may spit as a form of protest, but this is usually directed at other alpacas rather than humans. Understanding these behaviors is key to managing and caring for alpacas, as it helps handlers build a trusting relationship with these intelligent and sensitive animals."
}

{
    "title": "Alpaca Reproduction and Breeding Practices",
    "content": "Alpaca reproduction is unique and fascinating, particularly because they are induced ovulators. Unlike many other mammals that have a specific breeding season, female alpacas do not ovulate on a regular cycle. Instead, the act of mating triggers ovulation, which means that alpacas can breed at any time of the year, depending on environmental conditions and the health of the herd. This adaptation is likely a result of their evolution in the challenging environments of the Andes, where food availability and climate conditions can vary greatly throughout the year.\n\nBreeding practices among alpaca farmers are carefully managed to ensure the health and genetic diversity of the herd. Selective breeding is used to improve fleece quality, enhance specific physical traits, and prevent genetic disorders. For example, breeders may choose mates based on the fineness and density of their fleece, the animal's conformation (body structure), and temperament. Breeding decisions are also influenced by the alpaca's lineage, as maintaining genetic diversity is crucial to the long-term health of the herd.\n\nGestation in alpacas lasts about 11.5 months, and births typically occur without complications. Female alpacas, or dams, are attentive mothers and are often observed humming to their cria immediately after birth to strengthen the maternal bond. The cria are usually up and nursing within an hour of birth, and they grow rapidly in the first few weeks of life. Breeders monitor the health and development of both the dam and cria closely during this period to ensure they are thriving.\n\nIn some cases, artificial insemination and embryo transfer techniques are used in alpaca breeding, particularly in regions where it is difficult to bring animals together for natural mating. These advanced reproductive technologies allow breeders to introduce desirable genetic traits from distant herds, further enhancing the quality of their stock. However, natural breeding remains the most common practice, and the bond between the dam and cria is a critical component of herd dynamics and overall herd health."
}

Once you've successfully added these documents, it's time to perform a search!

Perform a Search¶

Now we'll perform a Hybrid search using the Search Documents endpoint.

Use the following URL for the request:

https://api.gainly.ai/v20241104/search

Paste the following into the body field:

{
    "query": "",
    "search_type": "hybrid"
}

Update the query parameter with search terms for the documents you added earlier. If you're using the sample documents provided above, you can use the following value for the query parameter:
```
{
    "query": "is alpaca wool hypoallergenic?",
    "search_type": "hybrid"
}
```
Click the Send button to execute the search
You'll see a 200 OK response from Gainly, along with the search results 👏

Now you've successfully added documents to your Gainly semantic index, and performed your first AI search. Nicely done! 💪