API#

La pantalla de API es un directorio de los métodos API disponibles en formato Swagger.

En la pantalla de API ahora hay tres pestañas disponibles:

1. Swagger
   En esta subsección se abre la documentación interactiva de la API. El usuario puede ver las solicitudes disponibles, sus parámetros, la estructura de la respuesta y utilizar Swagger como referencia para verificar integraciones.

La documentación también está disponible en el siguiente enlace:

2. ReDoc
   En esta subsección se abre una representación alternativa de la documentación de la API.

ReDoc es conveniente para la lectura: es más fácil revisar la descripción de los métodos, los esquemas de datos y los campos obligatorios de las solicitudes.

3. Token
   La subsección Token está destinada a la gestión de tokens de acceso a la API en Sherpa AI Server.

   En la pantalla de API tokens se muestra una tabla con la lista de los tokens API creados.

Para cada token en la lista se muestran:

En cada fila a la derecha están disponibles las siguientes acciones con el token:

• actualizar / reemitir el token;
• editar el token;
• eliminar el token.

Al regenerar un token, su secreto anterior deja de funcionar inmediatamente. El nuevo secreto se muestra una sola vez. Es importante copiarlo y actualizar todas las integraciones que utilizan este token. Si el nuevo valor no se guardó, es necesario regenerar el token otra vez.

Sobre la tabla hay botones:

• Crear — abre una ventana emergente para crear un nuevo token API.

En la ventana se debe indicar el nombre del token API y seleccionar roles de la lista desplegable. Ambos campos son obligatorios.

También se puede configurar la fecha de expiración del token. Si se marca la casilla "Sin fecha de expiración", el token se creará sin fecha de caducidad. Si la casilla no está seleccionada, en el campo "Fecha de expiración" se indica la fecha y hora hasta las cuales el token estará activo. Para seleccionar la fecha hay un ícono de calendario.

En la parte inferior de la ventana hay dos botones: "Cancelar" cierra la ventana sin guardar, y "Crear" crea un nuevo token API. El botón de creación se habilita después de completar los campos obligatorios.

Después de crearlo, guarde el valor del token mostrado en un lugar seguro y utilícelo solo en integraciones con los roles asignados.

• Actualizar — recarga la lista de tokens en la pantalla de API tokens.

Solicitudes Swagger sin parámetros en el cuerpo#

Las solicitudes requieren un token API válido cuya función permita la acción seleccionada, o una sesión autenticada. Las solicitudes se ejecutan dentro de la cuenta actual. No es necesario indicar el campo account_guid: el servidor determina la cuenta mediante el token o la sesión.

Antes de ejecutar una solicitud, se deben comprobar sus condiciones. La ejecución asíncrona requiere el estado waiting. La eliminación debe comprobarse solo con objetos creados para esta comprobación en una Cuenta independiente. No se puede eliminar una Carpeta de objetos que tenga subcarpetas.

Las solicitudes se pueden ejecutar en Swagger del siguiente modo:

1. Es necesario abrir la pestaña "Swagger". Para un token API, haga clic en "Authorize" e introduzca su valor. Para la autenticación por sesión, inicie sesión en Sherpa AI Server.

2. Es necesario seleccionar un método y hacer clic en "Try it out". Es necesario introducir los GUID de objetos existentes en los parámetros de ruta.

3. Para POST /api/v1/threads/{thread_guid}/runs/{run_guid}/execute_async, es necesario dejar un objeto JSON vacío en "Request body":

   Copiar

   {}
   

   Esta solicitud requiere el encabezado Content-Type: application/json.

4. En los siguientes métodos de eliminación, el cuerpo de la solicitud es opcional. Se puede enviar la solicitud sin cuerpo y sin el encabezado Content-Type:

   • DELETE /api/v1/folders/{folder_guid}/files/{file_guid};
   • DELETE /api/v1/folders/{folder_guid};
   • DELETE /api/v1/object_folders/{object_folder_guid}.

   Las solicitudes JSON anteriores, incluido {}, siguen siendo compatibles. Para un cuerpo JSON, incluya el encabezado Content-Type: application/json.

5. Es necesario hacer clic en "Execute" y comprobar el código de respuesta.

Un inicio asíncrono correcto devuelve 200 y el estado in_progress. La generación finaliza más tarde. Una eliminación correcta devuelve 204 sin cuerpo. Pruebe la eliminación con objetos de prueba.

Si recibe 403, compruebe la autenticación y los permisos de la función. Si recibe 404, compruebe los GUID y si los objetos pertenecen a la cuenta actual. La ejecución debe tener el estado waiting. Una ejecución con respuesta externa se completa mediante un cliente API. No se puede eliminar una carpeta de objetos que contenga subcarpetas.

Si recibe 422, compruebe que se hayan incluido los datos de autenticación, que el cuerpo JSON enviado sea válido y que el encabezado Content-Type sea correcto.