RAG samples with Chat API

This article describes samples for interacting with RAG Assistants using the Chat API.

Below, you will find the parameters and structures needed to run queries with filters, variables, and conversational context.

Executing queries with filters and variables

The request body allows you to customize the query through the following parameters:

¹mandatory

For conversations with history, use the optional threadId element to refer to a particular conversation. These conversations will keep the History Count parameter from your RAG Assistants. If no threadId value is set, no history will be considered and your query will be treated as a one-off.

The variables parameter is used to fill in an associated prompt with values.

Filters

The filters parameter is used as a logical condition statement. Check the details in Filter Operators.

These are predefined filters you can use:

To use specific metadata filters, remember to ingest documents with the correct metadata.

Filter section sample

A valid filter section is as follows:

"filters": [
    {"key": "extension", "operator": "$ne", "value": "pdf"}, /* any extension different from pdf */
    {"key": "name", "operator": "$eq", "value": "sample"}, /* filename is sample*/
    {"key": "year", "operator": "$gte", "value": 2000} /* year greather than or equal 2000, notice the year was added during ingestion */
]

Request body

Below is the structure of a valid Request body:

{
  "threadId": "string", /* optional */
  "messages": [
        {
            "role": "user",
            "content": "question" // string
        }
  ],
  "variables": [ /* optional */
    {"key": "string", "value": "string"},
    ...
  ],
  "filters": [ /* optional */
    {
      "key": "string",
      "operator": "string", /* Optional */
      "value": "string or number"
    },
    ...
  ]
}

Response

Below is a sample Response structure with StatusCode 200 and Content-Type: application/json:

{
  "documents": [ // optional: could not return elements when no information is present
    {
      "pageContent": "Example page content", // mandatory
      "score": 0.9, // optional, depends on the retrieval selected
      "metadata": { // mandatory
        "source": "Example source", // mandatory, document URL
        "url": "Example source", // optional if ingested with the url element
        "description": "Example description", // optional
        "id": "guid", // mandatory, internal
        "doc_id": "guid", // mandatory, internal
        "name": "Example document", // mandatory
        "extension": "doc", // mandatory
        "loc": {
          "lines": { // optional section and valid for txt files
            "from": number,
            "to": number,
            },
          "pageNumber": number // optional an valid for PDF
        },
        // other key-value parameters can be exposed depending on the ingestion             
      }
    }
  ],
  "id": "someId", // mandatory
  "requestId": "someId", // mandatory
  "text": "Example reply", // mandatory
  "result": { // mandatory
    "success": true, // mandatory
    "messages": [ // optional
      "error messages if available"
    ]
  },
  "usage": { // optional
    "total_tokens": number,
    "completion_tokens": number,
    "prompt_tokens": number,
    "prompt_cost": number,
    "completion_cost": number,
    "total_cost": number,
    "currency": "USD",
    "prompt_tokens_details": {
      "cached_tokens": number
    },
    "completion_tokens_details": {
      "reasoning_tokens": number
    }
  }
}

The returned score element (when available) measures the semantic similarity between the question and the associated pageContent. This score is a value between 0 and 1, where 1 represents the closest similarity.

You can use the requestId element to review the details of the Requests in the Console.

Usage

The usage element is available since the 2025-03 release.

{
    "documents": [...],
    "text": "here the response...",
    "result": {
        "success": true,
        "messages": [...]
    },
    "requestId": "GUID",
    "usage": {
        "total_tokens": 958,
        "completion_tokens": 73,
        "prompt_tokens": 885,
        "prompt_cost": 0.000132,
        "completion_cost": 0.0000438,
        "total_cost": 0.0021759,
        "currency": "USD"
    }
}

{
    "event": "saia.rag.documents",
    "data": {
        "documents": [...],
        "text": "",
        "result": {
            "success": true,
            "messages": []
        },
        "usage": {
            "total_tokens": 1024,
            "completion_tokens": 56,
            "prompt_tokens": 968,
            "prompt_cost": 0.0001449,
            "completion_cost": 0.0000336,
            "total_cost": 0.00217854,
            "currency": "USD",
            "prompt_tokens_details": {
                "cached_tokens": 0
            },
            "completion_tokens_details": {
                "reasoning_tokens": 0
            }
        }
    }
}

StatusCode

StatusCode 200 is shown with Content-Type: application/json, when RAG Assistant does not exist or is disabled:

"error": {
      "code": 1101,
      "message": "Search Index Profile Name not found"
  },
  "status": "failed",
  "success": false,
  "text": ""
}

Simple query sample

The default RAG assistant is consulted.

Request Body

{
    "model": "saia:search:Default",
    "messages": [
        {
            "role": "user",
            "content": "Explain to me what is Enterprise AI?"
        }
    ]
}

cURL Sample

curl -X POST "$BASE_URL/chat" \
 -H "Authorization: Bearer $SAIA_PROJECT_APITOKEN" \
 -H "Content-Type: application/json" \
 --data '{
    "model": "saia:search:Default",
    "messages": [
        {
            "role": "user",
            "content": "Explain to me what is Enterprise AI?"
        }
    ]
}'

Sample with variables and filters

Request body

{
    "model": "saia:search:Default",
    "messages": [
        {
            "role": "user",
            "content": "Again, explain to me what is Enterprise AI?"
        }
    ],
    "filters": [
        {"key": "extension", "operator": "$ne", "value": "pdf"},
        {"key": "name", "operator": "$eq", "value": "sample"},
        {"key": "year", "operator": "$gte", "value": 2000}
    ],
    "variables": [
        {"key": "type", "value": "Doc"}
    ]
}

cURL Sample

curl -X POST "$BASE_URL/chat" \
 -H "Authorization: Bearer $SAIA_PROJECT_APITOKEN" \
 -H "Content-Type: application/json" \
 --data '{
    "model": "saia:search:Default",
    "messages": [
        {
            "role": "user",
            "content": "Again, explain to me what is Enterprise AI?"
        }
    ],
    "filters": [
        {"key": "extension", "operator": "$ne", "value": "pdf"},
        {"key": "name", "operator": "$eq", "value": "sample"},
        {"key": "year", "operator": "$gte", "value": 2000}
    ],
    "variables": [
        {"key": "type", "value": "Doc"}
    ]
}'