> For the complete documentation index, see [llms.txt](https://docs.gaiodataos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gaiodataos.com/gaio-dataos-portuguese/tools/api.md).

# API

<figure><img src="/files/4CfxJIZ4iH6C3wcZEK6I" alt=""><figcaption></figcaption></figure>

Outros sistemas podem utilizar a inteligência analítica do **Gaio** por meio de **APIs**. Essa funcionalidade permite conectar **fluxos do Gaio** a serviços externos via **APIs RESTful**, utilizando autenticação segura por **chaves de API (API Keys)**.

***

### Como Utilizar

#### 1. Acessar a Aba API

No painel esquerdo, clique no ícone **API**.

* Utilize a aba **Chave API** para criar e gerenciar suas chaves.
* Utilize a aba **API** para configurar integrações com serviços externos.

***

### 2. Criar uma API Key

<figure><img src="/files/ikFpcf6GcuLxIobWHz3h" alt=""><figcaption></figcaption></figure>

1. Clique no botão **"+"** no canto superior direito da aba API Key.
2. Preencha os campos:
   1. **Nome:** Nome da chave (ex.: Doc)
   2. **Status:** Selecione **Ativo**
3. Clique em **generate**.
4. Após gerar a chave, copie e armazene-a com segurança.
5. Para visualizar ou renovar a chave, utilize o ícone de olho ou o botão de renovação.
6. Clique em **Salvar**.

***

### 3. Configurar uma Integração de API

<figure><img src="/files/AjcCfliDEndPnmz7QVIS" alt=""><figcaption></figcaption></figure>

1. Vá até a aba **API** e clique em **"+"** para adicionar uma nova integração.
2. Preencha os campos:
   1. **Nome:** Nome da integração (ex.: `SendToCRM`)
   2. **Endpoint:** Apenas o endpoint final (ex.: `https://api.example.com/send`)
3. **Configurar Authorization Token**
   1. Escolha onde o token de autorização será lido.
      1. Locais suportados:
         * **Cabeçalho** (recomendado)
         * Query parameters (se necessário)
4. **Selecionar fluxo** (opcional: Selecione o flow do Gaio que será executado quando a API for chamada.
5. **Inserir dados em uma tabela** (opcional): Permite mapear os dados recebidos pela API em uma tabela.
   1. Quando definido:
      1. Os dados da requisição são armazenados como linhas
      2. A tabela fica disponível para o flow executado
      3. Permite processamento em lote, auditoria e rastreabilidade
6. **Tipo de saída:** Define como a resposta da API será gerada.

   **Tabela** → Retorna dados de uma tabela\
   **Customizar** → Permite definir manualmente o corpo da resposta

**Exemplo de Resposta Customizada**

```json
{
  "status": "success",
  "message": "Request processed successfully",
  "data": {
    "execution_id": "{{ params.execution_id }}"
  }
}
```

7. **Tabela Resultado:** Selecione a tabela que contém os dados que serão consumidos via API.
8. Vá até a aba **Chave API** e associe a chave criada anteriormente.
9. Clique em **Salvar**.

***

### 4.  API Task · MCP Tool

<figure><img src="/files/mXv9pd9KzGzqRAzqWYli" alt=""><figcaption></figcaption></figure>

A aba **MCP Tool** permite expor uma API Task existente como uma ferramenta utilizável por agentes de IA. Após habilitada, a API pode ser invocada programaticamente por agentes durante o processo de raciocínio e execução.

Isso transforma sua API em uma ferramenta de IA de primeira classe, utilizável em:

* Agentes de Chat
* Agentes de Fluxo
* Pipelines automatizados de decisão

***

#### O que o MCP Tool Define

* Como a API é apresentada aos agentes
* Quais inputs o agente deve fornecer
* Se a ferramenta está habilitada para execução
* Como o agente entende quando e por que utilizá-la

***

#### Como Configurar o MCP Tool

1. Defina um nome claro e orientado à ação para a ferramenta.
2. Descreva o que ela faz e quando deve ser utilizada.
3. Defina o schema de entrada esperado:

```json
{
  "review_text": "string",
  "language": "string"
}
```

Clique em **Gerar** para criar automaticamente o schema com base na configuração da API.

Ative ou desative a ferramenta utilizando o switch de **Status**.

***

#### 5. Execução e Resultados

Após salvar a configuração:

* A API pode ser disparada manualmente ou como parte de um processo automatizado no Gaio.
* Se um processo for selecionado, ele será executado sempre que o endpoint da API do Gaio for chamado.

Isso significa que qualquer análise pode ser executada externamente ao Gaio, como:

* Criar/aplicar modelo preditivo
* Inserir ou deletar dados
* Chamar APIs externas (REST)
* Acessar fontes externas
* Utilizar qualquer outra funcionalidade do Gaio

***

#### Limite de Linhas

É possível limitar o número de linhas retornadas pela API do Gaio, mesmo que a tabela contenha milhões de registros.

Exemplo:

```
https://your_url/endpoint?limit=10
```

***

#### Paginação

Utilize `limit` e `offset` para navegar em grandes volumes de dados:

```
https://your_url/endpoint?limit=10&offset=10
```

Ou `limit` e `page`:

```
https://your_url/endpoint?limit=10&page=1
```

***

#### Parâmetros Customizados

Adicione parâmetros personalizados para filtrar a resposta da API.

Exemplo:

```
https://your_url/endpoint?limit=10&page=1&param_name_one=sales&param_name_two=male
```

Se a query anterior à API utilizar esses parâmetros como filtro, apenas os dados solicitados serão retornados.

Exemplo de uso:\
Enviar o código do cliente na chamada da API e receber apenas os produtos recomendados para aquele cliente.

{% hint style="warning" %}
Cada API do Gaio gera uma chave de acesso única.
{% endhint %}

### API Task · Live Requests

<figure><img src="/files/pQwpWyBeehacVqN17iZ5" alt=""><figcaption></figcaption></figure>

A aba **Solicitações ao vivo** permite monitorar chamadas da API em tempo real após a execução da API Task. Ela fornece visibilidade sobre requisições recebidas, comportamento de execução e dados em tempo de execução, sendo essencial para depuração e observabilidade.

***

#### O que você pode visualizar:

Após a API ser chamada, cada requisição aparece no painel Solicitações ao vivo com:

* Dados da requisição recebida
* Parâmetros e payload
* Contexto de execução
* Resposta ou resultado
* Erros (quando aplicável)

Essas informações são exibidas em tempo real, sem necessidade de redeploy ou reinicialização.

***

#### Casos de Uso Típicos

* Depuração de autenticação
* Validação de payloads
* Monitoramento de execução de flows
* Verificação de respostas customizadas
* Observação de chamadas de API disparadas por agentes
* Troubleshooting de integrações externas

***

### Boas Práticas

* **Segurança:** Nunca compartilhe sua API Key. Utilize o status Inactive para desativar temporariamente o acesso.
* **Versionamento:** Crie novas entradas para APIs com alterações estruturais.
* **Validação:** Teste endpoints manualmente antes de integrá-los a fluxos automatizados