API#

A tela da API é um guia dos métodos de API disponíveis no formato Swagger.

Na tela da API, agora estão disponíveis três abas:

1. Swagger
   Nesta subseção, a documentação interativa da API é aberta. O usuário pode visualizar as requisições disponíveis, seus parâmetros, a estrutura da resposta e usar o Swagger como um guia para verificar integrações.

A documentação também está disponível através do link:

2. ReDoc
   Nesta subseção, uma representação alternativa da documentação da API é aberta.

ReDoc é conveniente para leitura: é mais fácil visualizar a descrição dos métodos, esquemas de dados e campos obrigatórios das requisições.

3. Token
   A subseção Token é destinada à gestão de tokens de acesso à API no Sherpa AI Server.

   Na tela da API, os tokens são exibidos em uma tabela com a lista dos tokens de API criados.

Para cada token na lista, são mostrados:

Em cada linha à direita, estão disponíveis as seguintes ações com o token:

• atualizar / reemitir token;
• editar token;
• excluir token.

Ao gerar novamente um token, o segredo anterior deixa de funcionar imediatamente. O novo segredo é exibido uma única vez. É importante copiá-lo e atualizar todas as integrações que usam esse token. Se o novo valor não foi salvo, é necessário gerar o token novamente.

Acima da tabela, estão localizados os botões:

• Criar — abre uma janela pop-up para criar um novo token de API.

Na janela, é necessário indicar o nome do token da API e selecionar funções na lista suspensa. Ambos os campos são obrigatórios.

Também é possível configurar a data de expiração do token. Se marcar a caixa "Indefinido", o token será criado sem data de expiração. Se a caixa não estiver marcada, no campo "Data de expiração" deve ser indicada a data e hora até as quais o token estará ativo. Um ícone de calendário está disponível para selecionar a data.

Na parte inferior da janela, estão localizados dois botões: "Cancelar" fecha a janela sem salvar, e "Criar" cria um novo token de API. O botão de criação se torna disponível após o preenchimento dos campos obrigatórios.

Após a criação, guarde o valor exibido do token em um local seguro e use-o somente em integrações com as funções atribuídas a ele.

• Atualizar — recarrega a lista de tokens na tela de tokens da API.

Requisições Swagger sem parâmetros no corpo#

As requisições exigem um token de API válido cuja função permita a ação selecionada, ou uma sessão autenticada. As requisições são executadas na conta atual. Não é necessário informar o campo account_guid: o servidor determina a conta pelo token ou pela sessão.

Antes de executar uma solicitação, suas condições devem ser verificadas. A execução assíncrona exige o status waiting. A exclusão deve ser verificada apenas em objetos criados para essa verificação em uma Conta separada. Uma Pasta de objetos com subpastas não pode ser excluída.

As solicitações podem ser executadas no Swagger da seguinte forma:

1. É necessário abrir a aba "Swagger". Para um token de API, clique em "Authorize" e informe seu valor. Para autenticação por sessão, entre no Sherpa AI Server.

2. É necessário selecionar um método e clicar em "Try it out". É necessário informar os GUIDs de objetos existentes nos parâmetros de caminho.

3. Para POST /api/v1/threads/{thread_guid}/runs/{run_guid}/execute_async, é necessário manter um objeto JSON vazio em "Request body":

   Copiar

   {}
   

   Esta requisição exige o cabeçalho Content-Type: application/json.

4. Nos seguintes métodos de exclusão, o corpo da requisição é opcional. É possível enviar a requisição sem corpo e sem o cabeçalho 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}.

   As requisições JSON anteriores, incluindo {}, continuam sendo aceitas. Para um corpo JSON, informe o cabeçalho Content-Type: application/json.

5. É necessário clicar em "Execute" e verificar o código da resposta.

Um início assíncrono bem-sucedido retorna 200 e o status in_progress. A geração termina depois. Uma exclusão bem-sucedida retorna 204 sem corpo. Teste a exclusão com objetos de teste.

Se receber 403, verifique a autenticação e as permissões da função. Se receber 404, verifique os GUIDs e se os objetos pertencem à conta atual. A execução deve ter o status waiting. Uma execução com resposta externa é concluída por um cliente de API. Uma pasta de objetos que contenha subpastas não pode ser excluída.

Se receber 422, verifique se os dados de autenticação estão presentes, se o corpo JSON enviado é válido e se o cabeçalho Content-Type está correto.