> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills API

> Execução de receitas analíticas (skills), gerenciamento de segredos e perguntas sugeridas para o assistente.

A **Skills API** é o motor de execução de receitas analíticas da strattum.ai. Cada skill é um script versionado no Workspace Git que os agentes executam — via Console, API ou MCP Server — para responder perguntas de negócio recorrentes e rodar automações.

## Base URL

```
http://localhost:8007
```

## Autenticação

A Skills API é acessada internamente pelo console da strattum.ai via BFF (Next.js). A versão 1.0 não exige autenticação direta — o acesso é controlado pela rede privada do cliente.

## Endpoints

> **[GET /skills](#get-skills)**
>
> Lista todas as skills disponíveis no workspace.

> **[POST /skills](#post-skills)**
>
> Cria uma nova skill.

> **[GET /secrets](#get-secrets)**
>
> Lista as chaves de segredos configurados (nunca os valores).

> **[POST /secrets](#post-secrets)**
>
> Cria ou atualiza um segredo.

***

## GET /skills

Lista todas as skills disponíveis no workspace atual.

### Exemplos de chamada

```bash cURL theme={null}
curl http://localhost:8007/skills
```

```python Python theme={null}
import httpx

resp = httpx.get("http://localhost:8007/skills")
data = resp.json()
print(f"{data['total']} skills disponíveis")
for skill in data["skills"]:
    print(skill["name"], "-", skill["description"])
```

```javascript JavaScript theme={null}
const resp = await fetch('http://localhost:8007/skills')
const { skills, total } = await resp.json()
```

### Resposta

**200 OK**

```json theme={null}
{
  "skills": [
    {
      "name": "tickets_em_aberto",
      "description": "Lista os tickets de suporte em aberto por cliente e prioridade.",
      "steps": [
        {
          "type": "sql",
          "query": "SELECT * FROM main_clean.fct_tickets WHERE status = 'open' ORDER BY priority DESC"
        }
      ],
      "tags": ["suporte", "tickets"]
    }
  ],
  "total": 1
}
```

**skills** `array`

Lista de skills disponíveis.

**Campos de cada skill**

**name** `string`

Identificador único da skill (snake\_case). Usado como nome da tool MCP exposta ao assistente.

**description** `string`

Descrição legível da skill. O assistente usa este texto para decidir quando chamar a skill.

**steps** `array`

Passos de execução da skill. Cada passo tem `type` (`sql`, `cypher`, `code`) e `query`/`code`.

**tags** `array`

Tags para organização e filtro das skills.

**total** `integer`

Total de skills disponíveis.

***

## POST /skills

Cria uma nova skill no workspace.

### Body (`application/json`)

**name** `string` *required*

Identificador único da skill em snake\_case. Exemplo: `receita_por_cliente`.

**description** `string` *required*

Descrição clara do que a skill faz. O assistente usa este texto para decidir quando utilizá-la.

**steps** `array` *required*

Lista de passos de execução. Cada passo deve ter `type` (`sql`, `cypher` ou `code`) e o conteúdo correspondente.

**tags** `array`

Tags opcionais para organização.

### Exemplos de chamada

```bash cURL theme={null}
curl -X POST http://localhost:8007/skills \
  -H "Content-Type: application/json" \
  -d '{
    "name": "receita_por_cliente",
    "description": "Calcula a receita total por cliente nos últimos 90 dias.",
    "steps": [
      {
        "type": "sql",
        "query": "SELECT cliente_id, SUM(valor) as receita FROM main_clean.fct_pedidos WHERE data_pedido >= CURRENT_DATE - INTERVAL 90 DAY GROUP BY cliente_id ORDER BY receita DESC LIMIT 20"
      }
    ],
    "tags": ["financeiro", "clientes"]
  }'
```

```python Python theme={null}
import httpx

resp = httpx.post("http://localhost:8007/skills", json={
    "name": "receita_por_cliente",
    "description": "Calcula a receita total por cliente nos últimos 90 dias.",
    "steps": [
        {
            "type": "sql",
            "query": "SELECT cliente_id, SUM(valor) as receita FROM main_clean.fct_pedidos WHERE data_pedido >= CURRENT_DATE - INTERVAL 90 DAY GROUP BY cliente_id ORDER BY receita DESC LIMIT 20",
        }
    ],
    "tags": ["financeiro", "clientes"],
})
skill = resp.json()
print("Skill criada:", skill["name"])
```

### Resposta

**201 Created**

```json theme={null}
{
  "name": "receita_por_cliente",
  "description": "Calcula a receita total por cliente nos últimos 90 dias.",
  "steps": [...],
  "tags": ["financeiro", "clientes"]
}
```

***

## GET /secrets

Lista as **chaves** dos segredos configurados no workspace. Os valores nunca são retornados por este endpoint.

### Exemplos de chamada

```bash cURL theme={null}
curl http://localhost:8007/secrets
```

### Resposta

**200 OK**

```json theme={null}
{
  "secrets": [
    {
      "key": "OPENAI_API_KEY",
      "description": "Chave da API OpenAI para geração de embeddings"
    },
    {
      "key": "SLACK_BOT_TOKEN",
      "description": "Token do bot Slack para notificações"
    }
  ]
}
```

**secrets** `array`

Lista de segredos configurados, contendo apenas chave e descrição — nunca o valor.

***

## POST /secrets

Cria ou atualiza um segredo no workspace. Se a chave já existir, o valor é sobrescrito.

### Body (`application/json`)

**key** `string` *required*

Nome da variável de ambiente ou identificador do segredo. Exemplo: `OPENAI_API_KEY`.

**value** `string` *required*

Valor do segredo. Armazenado de forma segura — não é retornado após gravação.

**description** `string`

Descrição opcional do uso do segredo.

### Exemplos de chamada

```bash cURL theme={null}
curl -X POST http://localhost:8007/secrets \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SLACK_BOT_TOKEN",
    "value": "xoxb-...",
    "description": "Token do bot Slack para notificações de alertas"
  }'
```

```python Python theme={null}
import httpx

resp = httpx.post("http://localhost:8007/secrets", json={
    "key": "SLACK_BOT_TOKEN",
    "value": "xoxb-...",
    "description": "Token do bot Slack para notificações de alertas",
})
print(resp.status_code)
```

### Resposta

**200 OK** — segredo salvo

```json theme={null}
{ "key": "SLACK_BOT_TOKEN", "saved": true }
```

**400 Bad Request** — campos obrigatórios ausentes

```json theme={null}
{ "error": "key and value are required" }
```

> [!WARNING]
>
> Os valores de segredos nunca são retornados pela API após gravação. Se você perder um valor, precisará sobrescrevê-lo com um novo.

***

## Perguntas sugeridas

O endpoint de perguntas sugeridas é exposto pelo BFF do console e utilizado internamente para apresentar sugestões contextuais ao usuário.

### GET /api/skills/suggested-questions

Retorna perguntas sugeridas com base nos conectores ativos do workspace.

**Parâmetros de query:**

**connector\_ids** `string`

IDs de conectores separados por vírgula. Quando omitido, retorna sugestões globais.

**Resposta:**

```json theme={null}
{
  "questions": [
    "Quais são os tickets em aberto com prioridade alta?",
    "Qual cliente gerou mais receita nos últimos 30 dias?",
    "Quais contatos não foram contactados nos últimos 60 dias?"
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.