Chat API

The Chat API simplifies how businesses connect to various AI models across different providers. It acts as a single point of access, eliminating the need to manage multiple SDKs or APIs. This means you can interact with any supported LLM using just one SDK. In addition, the API centralizes the use of any Assistant in a single entry point.

Check the generic variables needed to use the API.

Endpoint

The general endpoint is as follows:

The v1/chat/completions, /chat/completions and /chat endpoints are supported and you can choose either endpoint. Both have the same interface (Request/Response) as the OpenAI Chat Completion API. These endpoints can be called using the OpenAI SDKs.

POST/chat

Request

• Method: POST
• Path: $BASE_URL/v1/chat/completions
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer $GEAI_APITOKEN
  • saia-conversation-id: $CONVERSATION_ID
    
    The header saia-conversation-id is used to maintain the context of a conversation in Flows. This identifier allows the system to link messages sent within the same session, preventing each one from being interpreted as a separate conversation. The value of the header can be a UUID or any alphanumeric string. If you change this value, a new conversation is automatically started. The conversations will expire after 10 minutes of inactivity and will be automatically deleted.
    
    In the case of Agents, the header saia-conversation-id must be a UUID and is used to allow reusing certain components of the Agent’s execution; however, it is essential to send the entire collection of messages so that the Agent has the full conversation context, which ensures compatibility with the OpenAI chat API implementation. You can use any UUID, as long as it hasn’t been used before. The conversation remains valid as long as a new version of the Agent is not published.
    
    Currently, if the response takes more than 60 seconds to be generated, it will not be received. Therefore, this endpoint is suitable only for simple Flows that do not require many interaction steps.
• Request Body

The payload will vary depending on the selected Assistant. The general pattern is as follows:

{
    "model": "string", // mandatory
    "messages": [ ... ], // at least one message
    "stream": boolean // optional
}

The model needs to specify an assistant_type and a specific_parameter whose format depends on that type. Its format is as follows:

"model": "saia:<assistant_type>:<specific_parameter>"

The following table describes the supported assistant_type and their corresponding specific_parameter.

The messages element defines the desired messages to be added. The minimal value needs to be the following, where the content details the user input.

{
    "role": "string", /* user, system and may support others depending on the selected model */
    "content": "string"
}

You can add additional parameters. Below are possible body samples.

Agent Sample

{
    "model": "saia:agent:JarvisTools",
    "messages": [
        {
            "role": "user",
            "content": "I need the price of the product to clean screens in the (here put the URL) site."
        },
        {
            "role": "assistant",
            "content": "Sure, I can look that up. Do you have the exact product name or should I search for all screen-cleaning products on the site?"
        },
        {
            "role": "user",
            "content": "Search all screen-cleaning products."
        }
    ],
    "stream": false
}

The expected result is to stream the translated content depending on the Prompt defined.

cURL Sample

curl -X POST "$BASE_URL/v1/chat/completions" \
 -H 'Authorization: Bearer $GEAI_APITOKEN' \
 -H 'content-type: application/json' \
 -H 'saia-conversation-id: $CONVERSATION_ID' \
 -d '{
    "model": "saia:agent:JarvisTools",
    "messages": [
        {
            "role": "user",
            "content": "I need the price of the product to clean screens in the (here put the URL) site."
        },
        {
            "role": "assistant",
            "content": "Sure, I can look that up. Do you have the exact product name or should I search for all screen-cleaning products on the site?"
        },
        {
            "role": "user",
            "content": "Search all screen-cleaning products."
        }
    ],
    "stream": false
}'

Assistant Sample

{
    "model": "saia:assistant:translate-to-spanish", /* Using a Standard Assistant named 'translate-to-spanish' */
    "messages": [
        {
            "role": "user",
            "content": "Hi, welcome to Globant Enterprise AI!!"
        }
    ],
    "stream": true
}

The expected result is to stream the translated content depending on the Prompt defined.

cURL Sample

curl -X POST "$BASE_URL/v1/chat/completions" \
 -H 'Authorization: Bearer $GEAI_APITOKEN' \
 -H 'content-type: application/json' \
 -d '{
    "model": "saia:assistant:translate-to-spanish",
    "messages": [
        {
            "role": "user",
            "content": "Hi, welcome to Globant Enterprise AI!!"
        }
    ],
    "stream": true
}'

Chat with Data Assistant Sample

{
    "model": "saia:assistant:ChatWithData",
    "messages": [
        {
            "role": "user",
            "content": "How many covid deaths were there in Singapore 2022?"
        }
    ]
}

cURL Sample

curl -X POST "$BASE_URL/v1/chat/completions" \
 -H 'Authorization: Bearer $GEAI_APITOKEN' \
 -H 'content-type: application/json' \
 -d '{
    "model": "saia:assistant:ChatWithData",
    "messages": [
       {
            "role": "user",
            "content": "How many covid deaths were there in Singapore 2022?"
        }
    ],
   "stream": false
}'

If the request is processed successfully, the response is returned in JSON format, which includes two key components: the query, represented by key = “query”, and the result of the execution, accessible through key = “dataSet”.

{
    "index": 0,
    "message": {
        "role": "assistant",
        "content": "{\"query\":{\"id\":\"db7c1e09-c059-4b96-9847-f174b1af6974\",\"name\":\"CovidDeathsInSingapore2022\",\"description\":\"Covid Deaths In Singapore2022\",\"expression\":\"Query CovidDeathsInSingapore2022 [OutputType='Table', Paging='False']\\r\\n{\\r\\n\\tSum(NewDeaths) [Name='Element01']\\r\\n\\t#filters\\r\\n\\t\\tCountryISO = 'SG'\\r\\n\\t\\tYear(Date) = 2022\\r\\n\\t#end\\r\\n}\",\"removeDuplicates\":false,\"outputType\":\"Table\",\"paging\":false},\"dataSet\":{\"id\":\"3dc46b4b-700a-42d2-8cd0-34669979c590\",\"pageNumber\":1,\"totalPages\":1,\"totalRows\":1,\"metadata\":[{\"name\":\"Element01\",\"type\":\"datum\",\"caption\":\"Sum of New Deaths\",\"dataType\":\"number\"}],\"data\":[{\"Element01\":\"386\"}]}}"
    }
}

API Assistant Sample

{
    "model": "saia:assistant:test-openapi-weather-assistant",
    "stream": false,
    "messages": [
        {
            "role": "user",
            "content": "weather in madrid"
        }
    ]
}

cURL Sample

curl -X POST "$BASE_URL/v1/chat/completions" \
 -H 'Authorization: Bearer $GEAI_APITOKEN' \
 -H 'content-type: application/json' \
 -d '{
    "model": "saia:assistant:test-openapi-weather-assistant",
    "messages": [
       {
            "role": "user",
            "content": "weather in madrid"
        }
    ],
   "stream": false
}'

RAG Sample

{
    "threadId": "uuid_as_string", /* conversation identifier (optional) */
    "model": "saia:search:Default", /* Using the Default RAG Assistant */
    "messages": [
        {
            "role": "user",
            "content": "Summarize the features of Globant Enterprise AI"
        }
    ],
    "stream": true
}

The expected result is to query the Default RAG Assistant and stream a reply once the sources are obtained.

cURL Sample

curl -X POST "$BASE_URL/v1/chat/completions" \
 -H 'Authorization: Bearer $GEAI_APITOKEN' \
 -H 'content-type: application/json' \
 -d '{
    "model": "saia:search:Default",
    "messages": [
        {
            "role": "user",
            "content": "Summarize the features of Globant Enterprise AI"
        }
    ],
    "stream": true
}'

More information: RAG samples with Chat API

Flow Sample

{
    "model": "saia:flow:87507723-3e3b-47f6-a1d0-aa53370c71d2",  /* Where 87507723-3e3b-47f6-a1d0-aa53370c71d2 is the bot_id*/  
    "messages": [
      {
        "role": "user",
        "content": "Question for flow"
      }
    ]
}

cURL Sample

curl -X POST "$BASE_URL/v1/chat/completions" \
-H 'Authorization: Bearer $GEAI_APITOKEN' \
-H 'content-type: application/json;charset=utf-8' \
-H 'saia-conversation-id: $CONVERSATION_ID' \
-d '{
    "model": "saia:flow:87507723-3e3b-47f6-a1d0-aa53370c71d2",    
    "messages": [
      {
        "role": "user",
        "content": "Question for flow"
      }
    ]
}'

Direct Chat with LLMs 

In addition to interacting with Assistants, Agents, Flows, and RAG Assistants, the Chat API also allows Direct Chat with Large Language Models (LLMs).

This capability enables advanced configuration options that are not always exposed when using higher-level abstractions.

One of the main advantages of direct LLM interaction is the ability to use optional reasoning parameters, such as reasoning_effort, which provides fine-grained control over how much reasoning the model applies when generating a response.

reasoning_effort parameter

The optional reasoning_effort parameter controls the depth of reasoning applied by supported models.

Supported values:

• "Low"
• "Medium"
• "High"
• "none" (supported starting from OpenAI GPT-5.1, to explicitly disable reasoning)

This parameter is supported by:

• OpenAI models starting from version 5
• Claude models starting from version 4.1
• Gemini models starting from version 2.0
• All corresponding reasoning-capable models from these providers

cURL Sample

curl --location "$BASE_URL/v1/chat/completions" \
-H 'Authorization: Bearer $GEAI_APITOKEN' 
-H 'content-type: application/json' \
-d '{
    "model": "openai/gpt-5.1",
    "messages": [
        {
            "role": "user",
            "content": "Cuantas a tiene la palabra universidad, despues de traducirla a Frances"
        }
    ],
    "stream": false,
    "temperature": 1,
    "reasoning_effort": "low",
    "max_tokens": 10000
}'

How to integrate Globant Enterprise AI with third-party SDKs

cURL

curl -X POST "$BASE_URL/v1/chat/completions" \
-H 'Authorization: Bearer $GEAI_APITOKEN' \
-H 'X-Saia-Cache-Enabled: false' \
-H 'content-type: application/json' \
-d '{
    "model": "openai/gpt-4o",
    "messages": [
         {
            "role": "system",
            "content": "You are a professional Translator. Translate the user text to English. Just output one word. "
        },
        {
            "role": "user",
            "content": "Hola"
        }
    ],
    "stream": false
}'

Note that in the model parameter, you must specify the model in the format provider/nameModel.

OpenAI SDK for Python

from openai import OpenAI

api_key = "$(GEAI_APITOKEN)"
api_base = "https://api.saia.ai/v1/chat/completions"

openai = OpenAI(api_key=api_key, base_url=api_base)

completion = openai.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hello world"}])

print(completion.choices[0].message.content)

OpenAI SDK for TypeScript

const { Configuration, OpenAIApi } = require("openai");

const configuration = new Configuration({
  apiKey: SAIA_APITOKEN,
  basePath: "https://api.saia.ai/v1/chat/completions",  
});
const openai = new OpenAIApi(configuration);

async function main() {
  const chatCompletion = await openai.createChatCompletion({
    model: "gpt-4o-mini",
    messages: [{role: "user", content: "Hello world"}],
  });
  
  console.log(chatCompletion.data.choices[0].message);
}

main();

How to call Gemini 1.5 pro

cURL

curl -X POST "$BASE_URL/v1/chat/completions" \
-H 'Authorization: Bearer $GEAI_APITOKEN' \
-H 'X-Saia-Cache-Enabled: false' \
-H 'content-type: application/json' \
-d '{
    "model": "vertex_ai/gemini-1.5-pro-preview-0409",
    "messages": [
         {
            "role": "system",
            "content": "You are a professional Translator. Translate the user text to English. Just output one word. "
        },
        {
            "role": "user",
            "content": "Hola"
        }
    ],
    "stream": false
}'

Creating and Using an Assistant with Variables

First, you need to create an assistant with the variables, and then pass the variables when you use it.

cURL - Creating the Assistant

curl --location 'https://api.saia.ai/v1/assistant' 
-H 'content-type: application/json' 
-H 'Authorization: Bearer $GEAI_APITOKEN' 
-d '{
    "type": "chat",
    "name": "Test-variables",
    "prompt": "You are a translator. Translate to {language}."
}'

cURL - Using the Assistant

curl --location 'https://api.saia.ai/v1/chat/completions' 
-H 'Saia-Auth: $GEAI_APITOKEN' 
-H 'X-Saia-Cache-Enabled: false' 
-H 'content-type: application/json' 
-d '{
    "model": "saia:assistant:Test-variables",
    "messages": [
        {
            "role": "user",
            "content": "Hello"
        }
    ],
    "variables": [
        {
            "key": "language",
            "value": "French"
        }
  ],
    "stream": false
}'