API#

Para la integración con sistemas externos (si es necesario), Sherpa AI Server ofrece un conjunto de herramientas para el intercambio de datos a través de la API.

La sección "API" es un manual de los métodos de API disponibles en formato Swagger. En esta sección se presentan las siguientes pestañas:

1. Clave
2. Almacenamiento
3. Registro
4. Cuentas
5. Servidor IA

1. Clave (API Key)#

En esta sección, el usuario puede ver su clave de acceso única a la API en el campo Clave. También al cambiar este campo es necesario confirmar la acción presionando uno de los botones:

(Asignación) - Asignar nueva clave;

(Actualizar) - Actualizar clave actual.

A continuación se encuentra el campo informativo "Authorization", que se utiliza para proporcionar un token de acceso, confirmando que el Usuario tiene derecho a realizar la acción solicitada.

Ejemplo:

“Bearer” — tipo de token,

“Y2Y5M2U3OGUtMDk1ZC00MGNjLTkwNWUtZTYyNjUwM_______” — el token en sí, que el servidor utilizará para identificar al Usuario.

Las solicitudes a la API se realizan con la transmisión obligatoria de la Clave API, que se almacena en la configuración de la Cuenta. Ejemplos detallados de solicitudes se presentan en la sección de cada bloque por separado.

Códigos de respuesta:

2. Almacenamiento#

Permite gestionar el Almacenamiento. El usuario puede crear nuevas carpetas y archivos, obtener información sobre carpetas y archivos, actualizar información sobre carpetas y archivos, así como eliminar carpetas y archivos.

En esta página se encuentran pestañas con métodos:

Al hacer clic en el ícono a la derecha del método deseado, se despliega la página correspondiente:

1. Creación de nueva carpeta#

• Endpoint: /api/folders/create
• Método: POST;
• Autorización: obligatoria;
• Parámetros:
  • Nombre: Nombre de la nueva carpeta;
  • Descripción: Descripción para la nueva carpeta.
• Ejemplo:

2. Obtención de información sobre la carpeta por GUID#

• Endpoint: /api/folders/read/{guid}
• Método: GET;
• Autorización: obligatoria;
• Parámetros:
  • Guid (obligatorio): Guid de la nueva carpeta.
• Ejemplo:

3. Obtención de lista de carpetas relacionadas con GUID#

• Endpoint: /api/folders/list
• Método: GET;
• Autorización: obligatoria;
• Parámetros: ninguno;
• Ejemplo:

4. Actualización de información sobre la carpeta por GUID#

• Endpoint: /api/folders/update
• Método: PUT;
• Autorización: obligatoria;
• Parámetros:
  • Guid (obligatorio): Guid de la carpeta;
  • Nombre: Nombre de la nueva carpeta;
  • Descripción: Descripción para la nueva carpeta.
• Ejemplo:

5. Creación de nuevo archivo#

• Endpoint: /api/files/create
• Método: POST;
• Autorización: obligatoria;
• Parámetros:
  • name (obligatorio): Nombre del archivo;
  • name_new (obligatorio): Nuevo nombre del archivo;
  • description (obligatorio): Descripción del archivo;
  • folder_id (obligatorio): GUID o ruta a la carpeta donde se añadirá el archivo;
  • Metadata (obligatorio): Metadatos del archivo;
  • file (obligatorio): Archivo en formato binario, o en codificaciones Base16 / Base32.
• Ejemplo:

6. Obtención de información sobre el archivo por GUID#

• Endpoint: /api/files/read/{guid}
• Método: GET;
• Autorización: obligatoria;
• Parámetros:
  • Nombre (obligatorio): Nombre del nuevo archivo.
• Ejemplo:

| Solicitud | Respuesta | | --------------------------------------------------------------------------------- | ------ ||

json</p><p> {</p><p> "Name": "example.txt",</p><p> }</p><p>

7. Actualización de información del archivo por GUID#

• Endpoint: /api/files/update
• Método: PUT;
• Autorización: obligatoria;
• Parámetros:
  • Name (obligatorio): Nombre del nuevo archivo;
  • folder_guid: ID de la carpeta donde se debe agregar el archivo;
  • file: Archivo en formato binario, o en codificaciones Base16 / Base32;
• Ejemplo:

8. Eliminación de archivo/carpeta#

• Endpoint: /api/files/delete
• Método: DELETE;
• Autorización: obligatoria;
• Parámetros:
  • file_folder_guid (obligatorio): GUID o ruta al archivo o carpeta;
  • type_processing (obligatorio): Tipo de procesamiento. Valores posibles:
    0 = Auto, 1 = Archivo, 2 = Directorio.
• Ejemplo:

9. Carga de archivo#

• Endpoint: /api/files/uploadfile
• Método: POST;
• Autorización: obligatoria;
• Parámetros:
  • file (obligatorio): Archivo para cargar;
  • folder_id: ID de la carpeta donde se debe agregar el archivo;
  • metadata: Metadatos del archivo.
• Ejemplo:

10. Descarga de archivo por GUID#

• Endpoint: /api/files/download/{guid}
• Método: GET;
• Autorización: obligatoria;
• Parámetros:
  • filename (obligatorio): Nombre del archivo.
• Ejemplo:

3. Registro#

Permite gestionar los Registros. El usuario puede crear un nuevo Registro, obtener información sobre el Registro, actualizar la información del Registro y eliminar el Registro.

En la parte superior de la página se encuentra una tabla con todos los niveles de Registro:

En la parte inferior se encuentran las pestañas con los métodos:

Al hacer clic en el ícono a la derecha del método deseado, se despliega la página correspondiente:

1. Creación de Registro#

• Endpoint: /api/log/create
• Método: POST;
• Autorización: obligatoria;
• Parámetros:
  • RobotGUID: GUID del Robot;
  • ProcessVersionGUID: GUID de la versión del Proceso;
  • JobGUID: GUID del Trabajo;
  • Level: nivel de Registro;

Message (obligatorio): texto del Registro.

• Ejemplo:

2. Obtención de información del Registro por GUID#

• Endpoint: /api/log/read/{guid}
• Método: GET;
• Autorización: obligatoria;
• Parámetros:
  • Guid (obligatorio): Guid del Registro.
• Ejemplo:

3. Obtención de lista de archivos relacionados con GUID#

• Endpoint: /api/log/list
• Método: POST;
• Autorización: obligatoria;
• Parámetros: ninguno.
• Ejemplo:

4. Eliminación de Registros pertenecientes a la cuenta actual y creados antes del tiempo seleccionado#

• Endpoint: /api/log/purge
• Método: DELETE;
• Autorización: obligatoria;
• Parámetros:
  • Time (obligatorio): marca de tiempo en formato Unix (Unix timestamp);
• Ejemplo:

4. Cuentas#

Permite gestionar las Cuentas. El usuario puede crear una nueva Cuenta, obtener información sobre la Cuenta, actualizar la información de la Cuenta y eliminar la Cuenta.

En esta página se encuentran las pestañas con los métodos:

Al hacer clic en el ícono a la derecha del método deseado, se despliega la página correspondiente:

• Endpoint: /api/account/create
• Método: POST;
• Autorización: obligatoria;
• Parámetros:
  • Login (obligatorio) — Login para la nueva Cuenta;
  • Password (obligatorio) — Contraseña para la nueva Cuenta;
  • FirstName — Nombre para la nueva Cuenta;
  • LastName — Apellido para la nueva Cuenta;
  • Email — E-mail para la nueva Cuenta;
  • Phone — Teléfono para la nueva Cuenta;
  • Company — Empresa para la nueva Cuenta;
  • Department — Departamento para la nueva Cuenta.
• Ejemplo:| Solicitud | Respuesta | | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | |

  json</p><p> {</p><p> "Login": "Nueva Cuenta de Prueba",</p><p> "Password": "newPassword123",</p><p> }</p><p>

  | ["guid": "c39713ea-d8b9-4669-976e-5ff39677dc64"] |

2. Obtención de información de la Cuenta por GUID#

• Endpoint: /api/account/read/{guid}
• Método: GET;
• Autorización: obligatoria;
• Parámetros:
  • GUID (obligatorio): GUID de la Cuenta.
• Ejemplo:

3. Actualización de información de la Cuenta por GUID#

• Endpoint: /api/account/update
• Método: PUT;
• Autorización: obligatoria;
• Parámetros:
  • Guid (obligatorio) — GUID de la Cuenta a actualizar;
  • Login — Login de la Cuenta a actualizar;
  • Password — Contraseña de la Cuenta a actualizar;
  • FirstName — Nombre en la Cuenta a actualizar;
  • LastName — Apellido de la Cuenta a actualizar;
  • Email — E-mail de la Cuenta a actualizar;
  • Phone — Teléfono en la Cuenta a actualizar;
  • Company — Empresa de la Cuenta a actualizar;
  • Department — Departamento de la Cuenta a actualizar.
• Ejemplo:

4. Eliminación de la Cuenta por GUID#

• Endpoint: /api/account/delete/{guid}
• Método: DELETE;
• Autorización: obligatoria;
• Parámetros:
  • Guid (obligatorio): Guid de la Cuenta;
• Ejemplo:

5. Servidor de IA#

Permite gestionar redes neuronales. El usuario puede enviar un objeto JSON y recibir una respuesta de la red neuronal, obtener información sobre el modelo actualmente utilizado, recibir una respuesta del Asistente o enviar un mensaje en el chat.

Al hacer clic en el ícono a la derecha del método deseado, se despliega la página correspondiente:

1. Adición de fragmentos de texto a un archivo existente#

• Endpoint: /api/files/addchunk
• Método: POST;
• Autorización: obligatoria;
• Parámetros:
  • text_chunk (obligatorio): Fragmento de texto;
  • guid_file (obligatorio): GUID del archivo o ruta al archivo;
  • metadata (obligatorio): Metadatos del fragmento.
• Ejemplo:

2. Búsqueda de embeddings por texto dado#

• Endpoint: /api/files/search
• Método: GET;
• Autorización: obligatoria;
• Parámetros:
  • text_for_search (obligatorio): Texto para buscar;
  • n_top (obligatorio): Número de resultados top;
  • files_ids (obligatorio): Cadena JSON con la lista de GUID o rutas a archivos;
  • folder_ids (obligatorio): Cadena JSON con la lista de GUID o rutas a carpetas;
  • enable_subfolders (obligatorio): Habilitación de subcarpetas. Valores posibles: 0 = Falso, 1 = Verdadero.
• Ejemplo:

3. Obtención de respuesta de la red neuronal#

• Endpoint: /api/threads/message
• Método: POST;
• Autorización: obligatoria;
• Parámetros:
  • messages (obligatorio): Array de objetos, cada uno representando un mensaje;
  • content: Texto del mensaje;
  • role: Rol del remitente del mensaje. Valores posibles: system, user;
  • name: Nombre del remitente del mensaje;
  • temperature: Número de punto flotante que determina el grado de aleatoriedad en las respuestas de la red neuronal. Valor por defecto: 0.7;
  • model (obligatorio): Cadena que indica la ruta al modelo, por ejemplo, /model-store/meta-llama/Meta-Llama-3-8B-Instruct;
  • assistant_id: Identificador del asistente;
  • thread_id: Identificador del chat;
  • info: Información del sistema.
• Ejemplo:

4. Obtención de información sobre el modelo actualmente utilizado#

• Endpoint: /api/threads/models
• Método: GET;
• Autorización: obligatoria;
• Parámetros: ninguno.
• Ejemplo:

  Solicitud

  Respuesta

  /api/threads/models

  json</p><p> {</p><p> "object": "list",</p><p> "data": [</p><p> {</p><p> "id": "/model-store/meta-llama/Meta-Llama-3-8B-Instruct", </p><p> "object": "model",</p><p> "created": 1735113788,</p><p> "owned_by": "vllm",</p><p> "root": "/model-store/meta-llama/Meta-Llama-3-8B-Instruct",</p><p> "parent": null,</p><p> "permission": [</p><p> {</p><p> "id": "modelperm-d7ddf889e9aa423b9949d1cdc551ff21",</p><p> "object": "model_permission",</p><p> "created": 1735113788,</p><p> "allow_create_engine": false,</p><p> "allow_sampling": true,</p><p> "allow_logprobs": true,</p><p> "allow_search_indices": false,</p><p> "allow_view": true,</p><p> "allow_fine_tuning": false,</p><p> "organization": "*",</p><p> "group": null,</p><p> "is_blocking": false</p><p> }</p><p> ]</p><p> }</p><p> ]</p><p> }</p><p>

5. Obtención de mensajes del Asistente#

• Endpoint: /api/threads/getUpdates
• Método: GET;
• Autorización: obligatoria;
• Parámetros:
  • assistant_id (obligatorio): Identificador del asistente;
  • offset: Identificador del mensaje desde el cual se debe obtener la lista de mensajes;
  • thread_id (obligatorio): Identificador del chat.
• Ejemplo:

6. Envío de un mensaje en el chat#

• Endpoint: /api/threads/chat
• Método: POST;
• Autorización: obligatoria;
• Parámetros:
  • thread_id (obligatorio): Identificador del chat;
  • role (obligatorio): Rol del remitente del mensaje (por ejemplo, assistant);
  • content (obligatorio): Texto del mensaje;
  • assistant_id: Identificador del asistente;
  • model_id: Identificador del grupo de modelos;
  • temperature: Número de punto flotante que determina el grado de aleatoriedad en las respuestas de la red neuronal. Valor por defecto: 0.7;
  • prompt: Contexto inicial o instrucción para el modelo;
  • title: Título del chat;
  • file_id: Lista de ID de archivos adjuntos al mensaje (array JSON);
  • folder_id: Lista de ID de carpetas (o objetos con id) adjuntos al mensaje (array JSON),
  • info: Información del sistema.
• Ejemplo: