Before integrating RAG-Buddy into your LLM pipeline, ensure you have set up a project in the SaaS portal and have an API key ready.

We distinguish between two primary use cases that are currently supported:

  • RAG+Citation
  • Text Classification

Select your use case from the tabs below to view the specific REST API endpoint details.

RAG+Citation Endpoint

The /ragc Endpoint

Endpoint URI:

https://api.ragbuddy.ai/ragc/v1

Note that this endpoint only works for the specific use case where the LLM returns the most relevant article from the context next to the actual answer.
Make sure to check out this Playground to experiment with the RAG+Citation Endpoint.

Versioning of the /ragc Endpoint

The /ragc endpoint implements versioning in its URL path, ensuring stable and predictable interactions with the RAG-Buddy service. The current version, designated as /ragc/v1, is established to be backward-compatible. This means that the v1 interface, encompassing its features and functionalities, will remain consistent and unchanged.

As RAG-Buddy evolves, new versions may be introduced to include advanced features or improvements. These will be accessible under different version paths (e.g., /ragc/v2). Importantly, new versions will not affect the existing v1 endpoint, allowing your current integrations to continue operating seamlessly.

We are dedicated to keeping our users informed about updates. New version releases and significant changes will be communicated through email notifications and posts on our blog, enabling users to stay updated and plan their transition to newer versions at their convenience.

/ragc Endpoint - Request

The /ragc endpoint in RAG-Buddy’s REST API is designed for handling requests specific to a RAG with citations use case.

A complete request to the /ragc endpoint consists of the following elements:

  • RAG-C Request Fields
  • Additonal LLM Fields
  • Request Headers

Read on for more detail on each of these components.

RAG-C Request Fields

These request fields are used to specify the remote LLM and to construct the (system and user) messages fields of the LLM.

  • remote_llm_url (required):

    • Type: string
    • Description: The URL of the remote Large Language Model (LLM) that RAG-Buddy will interact with.
    • For example: https://api.openai.com/v1/chat/completions
    Currently, RAG-Buddy only supports the OpenAI Chat models. Please contact us if you would like to use a different LLM.

  • system_intro (required):

    • Type: string
    • Description: A brief introduction or description that sets the context for the RAG interaction.
    • For example: You are a customer support agent of the e-banking application called Piggy Bank Extraordinaire.

  • system_instructions (optional):

    • Type: string or null
    • Description: Custom instructions for how the system should handle the request. If not provided, default instructions are used. These instructions are used to control the RAG-Buddy Citation Engine. It is recommended to use the default instructions unless you are familiar with the RAG-Buddy Citation Engine.
    • Default instructions (omit this field in case you make no changes to it):
Select the best article to reply to the question of the user below.
If you can find the answer in the articles listed below, then:
You MUST select exactly one article from the listed articles.
You MUST add the ID of the selected article at the start of your answer in the format "(ID:number) your answer", For example: (ID:1) your answer.
You MUST provide a short summarized answer.
If you cannot find the answer in the list of articles below, then:
You MUST say "(ID:None) I cannot answer this" and MUST say nothing more.
  • articles (required):
    • Type: array of objects (Article)
    • Description: A collection of articles, each with an ID and content. These articles serve as the context for the LLM to generate a grounded response.
      • Article:
        • ID: string (required) - A unique identifier for the article.
        • content: string (required) - The content of the article.
    • For example:
[
    {
        "ID": "123e4567-e89b-12d3-a456-426655440000",
        "content": "Interest Rates on Piggy Bank Extraordinaire's Savings Accounts\nAt Piggy Bank Extraordinaire, we understand the importance of saving for your future. That's why our Gold Plus Savings Account offers a competitive interest rate of 2.6% per annum, ensuring your savings grow steadily over time. For those seeking more flexibility, our Silver Flexi Savings Account provides an interest rate of 1.8% per annum, with the added benefit of no minimum balance requirement. Our Bronze Everyday Savings Account is perfect for daily transactions, offering a 1.2% interest rate per annum. With Piggy Bank Extraordinaire, you can choose the savings account that best suits your financial goals and lifestyle."
    },
    {
        "ID": "123e4567-e89b-12d3-a456-426655440001",
        "content": "Comparing Interest Rates: Piggy Bank Extraordinaire vs. Other Banks\nWhen it comes to choosing a bank for your savings, interest rates play a crucial role. Piggy Bank Extraordinaire stands out with its competitive rates. Our Gold Plus Savings Account offers an interest rate of 2.6% per annum, significantly higher than the industry average of 2.0%. In comparison, Big Bank offers 2.2% on its equivalent account, and Global Trust offers 2.1%. Furthermore, Piggy Bank Extraordinaire's Silver Flexi and Bronze Everyday accounts also outperform their counterparts at other banks, offering higher returns on your deposits. With Piggy Bank Extraordinaire, you can be assured of getting one of the best rates in the market for your savings."
    },
    {
        "ID": "123e4567-e89b-12d3-a456-426655440002",
        "content": "Understanding Fixed Deposit Interest Rates at Piggy Bank Extraordinaire\nFixed Deposits at Piggy Bank Extraordinaire are an excellent way to earn higher interest on your savings. Our Fixed Deposit accounts offer various tenures ranging from 6 months to 5 years, with interest rates varying accordingly. For a 6-month deposit, enjoy an interest rate of 2.0% per annum. The rate increases to 2.5% for a 1-year term and peaks at 3.5% for a 5-year term. These rates are designed to reward longer commitments with higher returns. Our Fixed Deposits are perfect for customers who wish to lock in their savings for a fixed period to earn a guaranteed return without the risks associated with market fluctuations."
    }
]
  • user_message (required):
    • Type: string
    • Description: The user’s query or message that the RAG+Citation pipeline will process.
    • For example: What are the interest rates for the Gold Plus Savings Account?

/ragc Endpoint - Response

The response is essentially the response as it would have been returned by the LLM directly. The only difference is that the RAG-Buddy Citation Engine parses the result and provides the response content and the selected article (the citation) in explicit fields: answer and article_id.

The answer and article_id are not returned explicitely for a streaming response. In that case these values need to be parsed by the client from the choices.message.content response field.

Here is an example response from the /ragc endpoint:

{
    "id": "chatcmpl-8hzHAAX********GG",
    "object": "chat.completion",
    "created": 1705494340,
    "model": "gpt-4",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "(ID:123e4567-e89b-12d3-a456-426655440000) The interest rate for the Gold Plus Savings Account at Piggy Bank Extraordinaire is 2.6% per annum."
            },
            "logprobs": null,
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 634,
        "completion_tokens": 29,
        "total_tokens": 663
    },
    "system_fingerprint": "fp_b738595050",
    "answer": "The interest rate for the Gold Plus Savings Account at Piggy Bank Extraordinaire is 2.6% per annum.",
    "article_id": "123e4567-e89b-12d3-a456-426655440000"
}

The content below is independent of the use case.

​
Additonal LLM Fields

These fields are specific to the LLM and are forwarded to the LLM as-is. For the OpenAI API, these fields are documented here.

The two required fields for this OpenAI endpoint are model and messages. The messages field is constructed from the fields in the previous section. Don’t send the messages field explicitly in the request body.

RAG-Buddy currently only supports the OpenAI Chat models.

Next to the model field you probably want to send the temperature field as well. This field controls the randomness of the LLM. The higher the temperature, the more random the LLM will respond. To make use of the RAG-Buddy Cache, we recommend setting the temperature to 0.0.

RAG-Buddy supports streaming responses from the LLM. To enable this, set the stream field to true.

​
Request Headers

The following request headers are required:

  • Content-Type: application/json
  • Authorization: Bearer $OPENAI_API_KEY
  • Helvia-RAG-Buddy-Token: RAG_CA_**********

Optional request headers:

  • Helvia-RAG-Buddy-Cache-Control: <...> Set this header to no-cache to disable reading from the RAG-Buddy Cache. To disable writing set it to no-write; disable both set it to no-cache, no-write. By default, reading and writing from/to the RAG-Buddy Cache is enabled.
A bit more detail on the Cache Control headers is provided here.

​
Response headers

The response headers are the response headers as returned by the LLM with the addition of one extra header: Helvia-RAG-Buddy-Cache-Status. This header indicates whether the RAG-Buddy Cache was used for this request. If the header is returned it means there was a cache hit. The actual value of the header is the (internally used) cache key that was used to retrieve the context from the cache.

Proxy EndpointCode examples