# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gaiodataos.com/gaio-dataos-portuguese/tools/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.