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

Lista todas as skills disponíveis no workspace.

POST /skills

Cria uma nova skill.

GET /secrets

Lista as chaves de segredos configurados (nunca os valores).

POST /secrets

Cria ou atualiza um segredo.

---

GET /skills

Lista todas as skills disponíveis no workspace atual.

Exemplos de chamada

cURL

curl http://localhost:8007/skills

Resposta

200 OK

{
  "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.

Show 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

cURL

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"]
  }'

Resposta

201 Created

{
  "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

cURL

curl http://localhost:8007/secrets

Resposta

200 OK

{
  "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

cURL

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"
  }'

Resposta

200 OK — segredo salvo

{ "key": "SLACK_BOT_TOKEN", "saved": true }

400 Bad Request — campos obrigatórios ausentes

{ "error": "key and value are required" }

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:

{
  "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?"
  ]
}