Table of contents
Official Content
  • This documentation is valid for:

This API enables the creation of new assistants, the modification of their definitions, and the retrieval of information about them. In addition, it allows the execution of prompts associated with previously defined assistants.

The following endpoints require a Globant Enterprise AI API token related to project scope.

Check the generic variables needed to use the API.

Endpoints

Method Path Description
GET /assistant/{id} Gets assistant data
POST /assistant Creates a new assistant
PUT /assistant/{id} Updates an assistant
DELETE /assistant/{id} Deletes an assistant
POST /assistant/text/begin Begins a text conversation with the Globant Enterprise AI Assistant
POST /assistant/text Sends a text prompt to the Globant Enterprise AI Assistant
POST /assistant/chat Sends a chat request to the Globant Enterprise AI Assistant
GET /assistant/request/{id}/status Retrieves the status of a request
POST /assistant/request/{id}/cancel Cancels a request
GET /assistant/{id}/status Gets the current status of the Data Analyst Assistant data set loading process.
POST /assistant/{id}/datasets/extend Extends the data sets of an existing Data Analyst Assistant.

 

Deprecated/assistant/text/begin and /assistant/text.

GET/assistant/{id}

Gets assistant data.

Parameters

Name Type Description
id string Assistant ID.
detail string Defines the level of detail required. The available options are summary (default) or full.

If you use the default summary option, the active revision details will be shown. The full option will display information about all revisions.

Response

{
  "assistantId": "string",
  "assistantName": "string",
  "assistantStatus": "integer", /* 1:Enabled, 2:Disabled */
  "intents": [ /* One element when summary, everything when using full detail*/
      {
          "assistantIntentDefaultRevision": "string",
          "assistantIntentDescription": "string",
          "assistantIntentId": "string",
          "assistantIntentName": "string",
          "revisions": [
              {
                  "metadata": [
                      {
                          "key": "string",
                          "type": "string",
                          "value": "string"
                      },
                      {
                          "key": "string",
                          "type": "string",
                          "value": "string"
                      }
                  ],
                  "modelName": "string",
                  "prompt": "string",
                  "providerName": "string",
                  "revisionDescription": "string",
                  "revisionId": "string",
                  "revisionName": "string",
                  "timestamp": "timestamp",
                  "variables": [ /* Optional */
                    {
                      "key": "string"
                    },
                    ...
                  ]
              }
          ]
      }
  ],
  "projectId": "string",
  "projectName": "string"
}

cURL Sample

curl -X GET "$BASE_URL/v1/assistant/{id}" \
 -H "Authorization: Bearer $SAIA_PROJECT_APITOKEN" \
 -H "Content-Type: application/json"
# using the full detail option change the URL to
$BASE_URL/v1/assistant/{id}?detail=full

POST/assistant

Creates a new assistant.

Request Body

{
  "type": "string", /* text, chat */
  "name": "string", /* Required */
  "description": "string",
  "prompt": "string", /* Required */
  "llmSettings": {
    "providerName": "string",
    "modelName": "string",
    "temperature": "decimal",
    "maxTokens": "integer",
  },
  "welcomeData": {
    "title": "string",
    "description": "string",
    "features": [
        {
            "title": "string",
            "description": "string"
        },
        ...
    ],
    "examplesPrompt": [
        {
            "title": "string",
            "description": "string",
            "promptText": "string"
        },
        ...
    ]
  }
}

Note: If you do not provide the WelcomeData section when creating an assistant, it will be empty.

 

Response

{
  "assistantId": "string",
  "assistantName": "string",
  "assistantStatus": "integer", /* 1:Enabled, 2:Disabled */
  "intents": [
    {
      "assistantIntentDefaultRevision": "integer",
      "assistantIntentDescription": "string",
      "assistantIntentId": "string",
      "assistantIntentName": "string",
      "revisions": [
        {
          "revisionId": "integer",
          "revisionName": "string",
          "revisionDescription": "string",
          "providerName": "string",
          "modelName": "string",
          "prompt": "string",
          "timestamp": "timestamp",
          "metadata": [
            {
              "key": "string",
              "value": "string",
              "type": "string"
            },
            ...
          ],
          "variables": [ /* Optional */
            {
              "key": "string"
            },
            ...
          ]
        }
      ]
    }
  ],
  "projectId": "string",
  "projectName": "string",
  "welcomeData": {
    "title": "string",
    "description": "string",
    "features": [
        {
            "title": "string",
            "description": "string"
        },
        ...
    ],
    "examplesPrompt": [
        {
            "title": "string",
            "description": "string",
            "promptText": "string"
        },
        ...
    ]
  }
}

The returned assistantId is needed for other related APIs.

cURL Sample

curl -X POST "$BASE_URL/v1/assistant" \
 -H "Authorization: Bearer $SAIA_PROJECT_APITOKEN" \
 -H "Content-type: application/json" \
 --data '{
      "type": "chat",
      "name": "TestAssistant",
      "prompt": "Translate the following text to Esperanto"
 }'

Sample with WelcomeData

curl -X POST "$BASE_URL/v1/assistant" \
 -H "Authorization: Bearer $SAIA_PROJECT_APITOKEN" \
 -H "Content-type: application/json" \
 --data '{
    "type": "chat",
    "name": "Welcome data Assistant",
    "prompt": "Translate to English",
    "welcomeData": {
            "title": "Assistant with WelcomeData",
            "description": "It is to test WelcomeData",
            "features": [
                {
                    "title": "First Feature",
                    "description": "First Feature Description"
                },
                {
                    "title": "Second Feature",
                    "description": "Second Feature Description"
                }
            ],
            "examplesPrompt": [
                {
                    "title": "First Prompt Example",
                    "description": "First Prompt Example Description",
                    "promptText": "You are an assistant specialized in translating ..."  
                }
            ]
        }
}'

PUT/assistant/{id}

Updates an existing assistant. The assistant type property cannot be changed.

Parameters

Name Type Description
id string ID of the assistant.

Request Body

{
  "name": "string", /* Optional */
  "description": "string", /* Optional */
  "status": "integer", /* Optional      1:Enabled, 2:Disabled */
  "action": "string", /* save, saveNewRevision (default), savePublishNewRevision */
  "revisionId": "integer", /* Required if user needs to update an existent revision when action = save */
  "prompt": "string", /* Required if revisionId is specified or in case of actions saveNewRevision and savePublishNewRevision*/
  "llmSettings": {
    "providerName": "string",
    "modelName": "string",
    "temperature": "decimal",
    "maxTokens": "integer",
  },
  "welcomeData": {
    "title": "string",
    "description": "string",
    "features": [
        {
            "title": "string",
            "description": "string"
        },
        ...
    ],
    "examplesPrompt": [
        {
            "title": "string",
            "description": "string",
            "promptText": "string"
        },
        ...
    ]
  }
}

Note: If an assistant had WelcomeData and an update does not include this section, the existing information is deleted and becomes empty. Therefore, if you want to add new information to the WelcomeData, you must include both the old and the new information. If you only send the new one, it will completely replace the old one.

 

The default value of the action parameter, saveNewRevision, will create a new revision but will not set it as active. The save option will update the active revision. The savePublishNewRevision option will create a new revision and set it as active.

If only an update of name, description, or status is needed, at least one of them must be provided without any changes in the revision; it can be specified as:

{
  "name": "string",
  "description": "string",
  "status": "integer", /* 1:Enabled, 2:Disabled */
  "action": "string" /* use "save" action */
}

Response

{
  "assistantId": "string",
  "assistantName": "string",
  "assistantStatus": "integer", /* 1:Enabled, 2:Disabled */
  "intents": [ /* One element when summary, everything when using full detail*/
      {
          "assistantIntentDefaultRevision": "string",
          "assistantIntentDescription": "string",
          "assistantIntentId": "string",
          "assistantIntentName": "string",
          "revisions": [
              {
                  "metadata": [
                      {
                          "key": "string",
                          "type": "string",
                          "value": "string"
                      },
                      {
                          "key": "string",
                          "type": "string",
                          "value": "string"
                      }
                  ],
                  "modelName": "string",
                  "prompt": "string",
                  "providerName": "string",
                  "revisionDescription": "string",
                  "revisionId": "string",
                  "revisionName": "string",
                  "timestamp": "timestamp",
                  "variables": [ /* Optional */
                    {
                      "key": "string"
                    },
                    ...
                  ]
              }
          ]
      }
  ],
  "projectId": "string",
  "projectName": "string",
  "welcomeData": {
    "title": "string",
    "description": "string",
    "features": [
        {
            "title": "string",
            "description": "string"
        },
        ...
    ],
    "examplesPrompt": [
        {
            "title": "string",
            "description": "string",
            "promptText": "string"
        },
        ...
    ]
  }
}

cURL Sample

curl -X PUT "$BASE_URL/v1/assistant/{id}" \
 -H "Authorization: Bearer $SAIA_PROJECT_APITOKEN" \
 -H "Content-type: application/json" \
 --data '{
      "action": "savePublishNewRevision",
      "prompt": "translate the following text to Latin",
      "llmSettings":{
          "modelName":"gpt-3.5-turbo",
          "temperature":0.0
      }
 }'

Sample with Welcome Data Update

curl -X PUT "$BASE_URL/v1/assistant/{id}" \
 -H "Authorization: Bearer $SAIA_PROJECT_APITOKEN" \
 -H "Content-type: application/json" \
 --data '{
      "welcomeData": {
            "title": "Updated WelcomeData assistant",
            "description": "It is to update WelcomeData",
            "features": [
                {
                    "title": "First Feature Updated",
                    "description": "Updated First Feature Description"
                },
                {
                    "title": "Second Feature Updated",
                    "description": "UpdatedSecond Feature Description"
                }
            ],
            "examplesPrompt": [
                {
                    "title": "Updated First Prompt Example",
                    "description": "Updated First Prompt Example Description",
                    "promptText": "You are an assistant specialized in translating ..."  
                }
            ]
        }
}'

DELETE/assistant/{id}

Deletes an assistant.

Parameters

Name Type Description
id string Assistant ID (required)

Response

StatusCode 200 indicates a successful deletion; otherwise, StatusCode 400* with a collection of errors.

cURL Sample

curl -X DELETE "$BASE_URL/v1/assistant/{id}" \
 -H "Authorization: Bearer $SAIA_PROJECT_APITOKEN" \
 -H "Content-type: application/json"

POST/assistant/text/begin (Deprecated)

Begins a text conversation with the Globant Enterprise AI Assistant.

Parameters

Name Type Description
assistant string Name of the assistant.
prompt string Text prompt for the assistant.
revision integer Revision number.
revisionName string Name of the revision.

Response

{
  "requestId": "string",
  "error": {
    "code": 0,
    "message": "string"
  },
  "success": true,
  "providerName": "string",
  "providerResponse": "string",
  "progress": 0,
  "timestamp": "string",
  "status": "string",
  "text": "string"
}

cURL Sample

curl -X POST $BASE_URL/v1/assistant/text/begin \
  -H "Content-Type: application/json" \
  --data '{
    "assistant": "string",
    "prompt": "string",
    "revision": 0,
    "revisionName": "string"
  }'

POST/assistant/text (Deprecated)

Sends a text prompt to the Globant Enterprise AI Assistant.

Parameters

Name Type Description
assistant string Name of the assistant.
prompt string Text prompt for the assistant.
revision integer Revision number.
revisionName string Name of the revision.
variables collection A list of key/value properties (optional).

Response

{
  "requestId": "string",
  "error": {
    "code": 0,
    "message": "string"
  },
  "success": true,
  "providerName": "string",
  "providerResponse": "string",
  "progress": 0,
  "timestamp": "string",
  "status": "string",
  "text": "string"
}

cURL Sample

curl -X POST $BASE_URL/v1/assistant/text \
  -H "Content-Type: application/json" \
  --data '{
    "assistant": "AssistantName",
    "prompt": "Your Input here",
    "revision": 1
  }'

POST/assistant/chat

Sends a chat request to the Globant Enterprise AI Assistant.

Parameters

Name Type Description
assistant string Name of the assistant.
messages array Chat request data.
revision integer Revision number.
revisionName string Name of the revision.
variables collection A list of key/value properties (optional).

Response

{
  "requestId": "string",
  "error": {
    "code": 0,
    "message": "string"
  },
  "success": true,
  "providerName": "string",
  "providerResponse": "string",
  "progress": 0,
  "timestamp": "string",
  "status": "string",
  "text": "string"
}

cURL Sample

curl -X POST $BASE_URL/v1/assistant/chat \
  -H "Content-Type: application/json" \
  --data '{
    "assistant": "string",
    "messages": [
      {
        "role": "string",
        "content": "string"
      }
    ],
    "variables": [
        {"key": "string", "value": "string"},
        {"key": "string", "value": "string"}
    ],
    "revision": 0,
    "revisionName": "string"
  }'

Note that the variables section is optional and depends on your Prompt configuration.

GET/assistant/request/{id}/status

Retrieves the status of a request.

Parameters

Name Type Description
requestId string (uuid) ID of the request.

Response

{
  "requestId": "string",
  "error": {
    "code": 0,
    "message": "string"
  },
  "providerName": "string",
  "providerResponse": "string",
  "progress": 0,
  "timestamp": "string",
  "status": "string"
}

cURL Sample

curl -X GET $BASE_URL/v1/assistant/request/{requestId}/status

POST/assistant/request/{id}/cancel

Cancels a request.

Parameters

Name Type Description
requestId string (uuid) ID of the request.

Response

{
  "requestId": "string",
  "error": {
    "code": 0,
    "message": "string"
  },
  "providerResponse": "string",
  "timestamp": "string",
  "status": "string"
}

cURL Sample

curl -X POST $BASE_URL/v1/assistant/request/{requestId}/cancel

GET/assistant/{id}/status

Gets the current status of the data set loading process from the Data Analyst Assistant.

Parameters

Name Type Description
id string Data Analyst Assistant ID.

Response

StatusCode 200 indicates a successful execution; otherwise, StatusCode 400* with a collection of errors.

Possible return errors:

cURL Sample

curl --location '$BASE_URL/v1/assistant/{{assistantId}}/status' \
-H 'Authorization: &SAIA_APITOKEN' \
-H 'Content-Type: application/json' \

POST/assistant/{id}/datasets/extend

Upload one or more dataset files to the associated {id} Data Analyst Assistant. Note that the file extension must be .csv.

Response

StatusCode 200 indicates a successful execution; otherwise, StatusCode 400* with a collection of errors.

Possible return errors:

cURL Sample

curl --location '$BASE_URL/v1/assistant/{{assistantId}}/datasets/extend' \
--header 'Authorization: &SAIA_APITOKEN' \
--form 'file=@"/C:/temp/Dataset1.csv"'
--form 'file=@"/C:/temp/Dataset2.csv"'
Last update: October 2024 | © GeneXus. All rights reserved. GeneXus Powered by Globant