API#

Para integração com sistemas externos (se necessário), o Sherpa AI Server oferece um conjunto de ferramentas para troca de dados via API.

A seção "API" é um guia sobre os métodos de API disponíveis no formato Swagger. Nesta seção, estão apresentadas as seguintes abas:

1. Chave
2. Armazenamento
3. Log
4. Contas
5. Servidor de IA

1. Chave (API Key)#

Nesta seção, o usuário pode ver sua chave de acesso única à API no campo Chave. Além disso, ao alterar este campo, é necessário confirmar a ação pressionando um dos botões:

(Assignment) - Atribuir nova chave;

(Refresh) - Atualizar chave atual.

Abaixo está o campo informativo "Authorization", que é usado para fornecer o token de acesso, confirmando que o Usuário tem permissão para executar a ação solicitada.

Exemplo:

“Bearer” — tipo de token,

“Y2Y5M2U3OGUtMDk1ZC00MGNjLTkwNWUtZTYyNjUwM_______” — o próprio token que o servidor usará para identificar o Usuário.

As solicitações à API devem incluir obrigatoriamente a chave da API, que é armazenada nas configurações da Conta. Exemplos detalhados de solicitações são apresentados na seção de cada bloco separadamente.

Códigos de resposta:

2. Armazenamento#

Permite gerenciar o Armazenamento. O usuário pode criar novas pastas e arquivos, obter informações sobre pastas e arquivos, atualizar informações sobre pastas e arquivos, bem como excluir pastas e arquivos.

Nesta página, estão as abas com os métodos:

Ao clicar no ícone à direita do método desejado, a página correspondente é exibida:

1. Criação de nova pasta#

• Endpoint: /api/folders/create
• Método: POST;
• Autorização: obrigatória;
• Parâmetros:
  • Name: Nome da nova pasta;
  • Description: Descrição para a nova pasta.
• Exemplo:

2. Obtenção de informações sobre a pasta por GUID#

• Endpoint: /api/folders/read/{guid}
• Método: GET;
• Autorização: obrigatória;
• Parâmetros:
  • Guid (obrigatório): Guid da nova pasta.
• Exemplo:

3. Obtenção da lista de pastas relacionadas ao GUID#

• Endpoint: /api/folders/list
• Método: GET;
• Autorização: obrigatória;
• Parâmetros: nenhum;
• Exemplo:

4. Atualização de informações sobre a pasta por GUID#

• Endpoint: /api/folders/update
• Método: PUT;
• Autorização: obrigatória;
• Parâmetros:
  • Guid (obrigatório): Guid da pasta;
  • Name: Nome da nova pasta;
  • Description: Descrição para a nova pasta.
• Exemplo:

5. Criação de novo arquivo#

• Endpoint: /api/files/create
• Método: POST;
• Autorização: obrigatória;
• Parâmetros:
  • name (obrigatório): Nome do arquivo;
  • name_new (obrigatório): Novo nome do arquivo;
  • description (obrigatório): Descrição do arquivo;
  • folder_id (obrigatório): GUID ou caminho para a pasta onde o arquivo será adicionado;
  • Metadata (obrigatório): Metadados do arquivo;
  • file (obrigatório): Arquivo em formato binário, ou em codificações Base16 / Base32.
• Exemplo:

6. Obtenção de informações sobre o arquivo por GUID#

• Endpoint: /api/files/read/{guid}
• Método: GET;
• Autorização: obrigatória;
• Parâmetros:
  • Name (obrigatório): Nome do novo arquivo.
• Exemplo:

| Solicitação | Resposta | | --------------------------------------------------------------------------------- | ------ ||

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

7. Atualização de informações do arquivo por GUID#

• Endpoint: /api/files/update
• Método: PUT;
• Autorização: obrigatória;
• Parâmetros:
  • Name (obrigatório): Nome do novo arquivo;
  • folder_guid: ID da pasta onde o arquivo deve ser adicionado;
  • file: Arquivo em formato binário, ou em codificações Base16 / Base32;
• Exemplo:

8. Exclusão de arquivo/pasta#

• Endpoint: /api/files/delete
• Método: DELETE;
• Autorização: obrigatória;
• Parâmetros:
  • file_folder_guid (obrigatório): GUID ou caminho para o arquivo ou pasta;
  • type_processing (obrigatório): Tipo de processamento. Valores possíveis:
    0 = Auto, 1 = File, 2 = Directory.
• Exemplo:

9. Upload de arquivo#

• Endpoint: /api/files/uploadfile
• Método: POST;
• Autorização: obrigatória;
• Parâmetros:
  • file (obrigatório): Arquivo para upload;
  • folder_id: ID da pasta onde o arquivo deve ser adicionado;
  • metadata: Metadados do arquivo.
• Exemplo:

10. Download de arquivo por GUID#

• Endpoint: /api/files/download/{guid}
• Método: GET;
• Autorização: obrigatória;
• Parâmetros:
  • filename (obrigatório): Nome do arquivo.
• Exemplo:

3. Log#

Permite gerenciar Logs. O usuário pode criar um novo Log, obter informações sobre o Log, atualizar informações sobre o Log, bem como excluir o Log.

Na parte superior da página, há uma tabela com todos os níveis de Log:

Na parte inferior, estão as abas com os métodos:

Ao clicar no ícone à direita do método desejado, a página correspondente é exibida:

1. Criação de Log#

• Endpoint: /api/log/create
• Método: POST;
• Autorização: obrigatória;
• Parâmetros:
  • RobotGUID: GUID do Robô;
  • ProcessVersionGUID: GUID da versão do Processo;
  • JobGUID: GUID do Trabalho;
  • Level: nível de Log;

Message (obrigatório): texto do Log.

• Exemplo:

2. Obtenção de informações sobre o Log por GUID#

• Endpoint: /api/log/read/{guid}
• Método: GET;
• Autorização: obrigatória;
• Parâmetros:
  • Guid (obrigatório): Guid do Log.
• Exemplo:

3. Obtenção da lista de arquivos relacionados ao GUID#

• Endpoint: /api/log/list
• Método: POST;
• Autorização: obrigatória;
• Parâmetros: nenhum.
• Exemplo:

4. Exclusão de Logs pertencentes à conta atual e criados antes do tempo selecionado#

• Endpoint: /api/log/purge
• Método: DELETE;
• Autorização: obrigatória;
• Parâmetros:
  • Time (obrigatório): timestamp em formato Unix (Unix timestamp);
• Exemplo:

4. Contas#

Permite gerenciar Contas. O usuário pode criar uma nova Conta, obter informações sobre a Conta, atualizar informações sobre a Conta, bem como excluir a Conta.

Nesta página, há abas com os métodos:

Ao clicar no ícone à direita do método desejado, a página correspondente é exibida:

• Endpoint: /api/account/create
• Método: POST;
• Autorização: obrigatória;
• Parâmetros:
  • Login (obrigatório) — Login para a nova Conta;
  • Password (obrigatório) — Senha para a nova Conta;
  • FirstName — Nome para a nova Conta;
  • LastName — Sobrenome para a nova Conta;
  • Email — E-mail para a nova Conta;
  • Phone — Telefone para a nova Conta;
  • Company — Empresa para a nova Conta;
  • Department — Departamento para a nova Conta.
• Exemplo:| Requisição | Resposta | | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | |

  json</p><p> {</p><p> "Login": "Nova Conta de Teste",</p><p> "Password": "newPassword123",</p><p> }</p><p>

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

2. Obtenção de informações da Conta pelo GUID#

• Endpoint: /api/account/read/{guid}
• Método: GET;
• Autorização: obrigatória;
• Parâmetros:
  • GUID (obrigatório): GUID da Conta.
• Exemplo:

3. Atualização de informações da Conta pelo GUID#

• Endpoint: /api/account/update
• Método: PUT;
• Autorização: obrigatória;
• Parâmetros:
  • Guid (obrigatório) — GUID da Conta a ser atualizada;
  • Login — Login da Conta a ser atualizada;
  • Password — Senha da Conta a ser atualizada;
  • FirstName — Nome na Conta a ser atualizado;
  • LastName — Sobrenome da Conta a ser atualizado;
  • Email — E-mail da Conta a ser atualizado;
  • Phone — Telefone na Conta a ser atualizado;
  • Company — Empresa da Conta a ser atualizada;
  • Department — Departamento da Conta a ser atualizado.
• Exemplo:

4. Exclusão da Conta pelo GUID#

• Endpoint: /api/account/delete/{guid}
• Método: DELETE;
• Autorização: obrigatória;
• Parâmetros:
  • Guid (obrigatório): Guid da Conta;
• Exemplo:

5. Servidor de IA#

Permite gerenciar redes neurais. O usuário pode enviar um objeto JSON e receber uma resposta da rede neural, obter informações sobre o modelo atualmente utilizado, receber uma resposta do Assistente ou enviar uma mensagem no chat.

Ao clicar no ícone à direita do método desejado, a página correspondente é exibida:

1. Adição de blocos de texto a um arquivo existente#

• Endpoint: /api/files/addchunk
• Método: POST;
• Autorização: obrigatória;
• Parâmetros:
  • text_chunk (obrigatório): Bloco de texto;
  • guid_file (obrigatório): GUID do arquivo ou caminho para o arquivo;
  • metadata (obrigatório): Metadados do bloco.
• Exemplo:

2. Encontrar embeddings para um texto fornecido#

• Endpoint: /api/files/search
• Método: GET;
• Autorização: obrigatória;
• Parâmetros:
  • text_for_search (obrigatório): Texto para busca;
  • n_top (obrigatório): Número de resultados principais;
  • files_ids (obrigatório): String JSON com a lista de GUID ou caminhos para arquivos;
  • folder_ids (obrigatório): String JSON com a lista de GUID ou caminhos para pastas;
  • enable_subfolders (obrigatório): Habilitar subpastas. Valores possíveis: 0 = Falso, 1 = Verdadeiro.
• Exemplo:

3. Obtenção de resposta da rede neural#

• Endpoint: /api/threads/message
• Método: POST;
• Autorização: obrigatória;
• Parâmetros:
  • messages (obrigatório): Array de objetos, cada um representando uma mensagem;
  • content: Texto da mensagem;
  • role: Papel do remetente da mensagem. Valores possíveis: system, user;
  • name: Nome do remetente da mensagem;
  • temperature: Número de ponto flutuante que determina o grau de aleatoriedade nas respostas da rede neural. Valor padrão: 0.7;
  • model (obrigatório): String que indica o caminho para o modelo, por exemplo, /model-store/meta-llama/Meta-Llama-3-8B-Instruct;
  • assistant_id: Identificador do assistente;
  • thread_id: Identificador do chat;
  • info: Informações do sistema.
• Exemplo:

4. Obtenção de informações sobre o modelo atualmente utilizado#

• Endpoint: /api/threads/models
• Método: GET;
• Autorização: obrigatória;
• Parâmetros: nenhum.
• Exemplo:

  Requisição

  Resposta

  /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. Recebendo mensagem do Assistente#

• Endpoint: /api/threads/getUpdates
• Método: GET;
• Autorização: obrigatória;
• Parâmetros:
  • assistant_id (obrigatório): Identificador do assistente;
  • offset: Identificador da mensagem a partir da qual é necessário obter a lista de mensagens;
  • thread_id (obrigatório): Identificador do chat.
• Exemplo:

6. Enviando mensagem no chat#

• Endpoint: /api/threads/chat
• Método: POST;
• Autorização: obrigatória;
• Parâmetros:
  • thread_id (obrigatório): Identificador do chat;
  • role (obrigatório): Papel do remetente da mensagem (por exemplo, assistant);
  • content (obrigatório): Texto da mensagem;
  • assistant_id: Identificador do assistente;
  • model_id: Identificador do grupo de modelos;
  • temperature: Número de ponto flutuante que determina o grau de aleatoriedade nas respostas da rede neural. Valor padrão: 0.7;
  • prompt: Contexto inicial ou instrução para o modelo;
  • title: Título do chat;
  • file_id: Lista de IDs de arquivos anexados à mensagem (array JSON);
  • folder_id: Lista de IDs de pastas (ou objetos com id) anexados à mensagem (array JSON),
  • info: Informação do sistema.
• Exemplo: