api pública

Integre com o cuby.

A mesma API que o painel usa. REST + JSON, autenticação Bearer, webhooks assinados por HMAC-SHA256. O cuby-mcp é o cliente oficial pra Claude Desktop e outros clientes MCP.

Autenticação

Toda rota exige um header Authorization: Bearer <API_KEY>. A chave estática vive na tabela settings como api_key e não expira. Peça uma pelo [email protected].

curl https://cuby.cubelabs.dev/api/rag/conversations/users \
  -H "Authorization: Bearer $CUBY_API_KEY"

Endpoints principais

method	path	o que faz
GET	/api/rag/conversations/users	Lista contatos (usuários WhatsApp), filtrados por tag.
GET	/api/rag/conversations	Lista conversas (mensagens). Suporta busca, datas, rating.
GET	/api/rag/conversations/{id}	Detalhe de uma conversa.
GET	/api/rag/test-query?q=...	Busca MMR na base de conhecimento.
GET	/api/rag/conversations/tags	Tags em uso.
PUT	/api/rag/conversations/tags	Substitui as tags de um usuário.
POST	/api/rag/conversations/takeover	Liga/desliga takeover humano.
PUT	/api/rag/conversations/{id}/approve	Aprova ou edita a resposta pendente da IA.
POST	/api/twilio/send-whatsapp	Envia mensagem WhatsApp (texto ou mídia).
POST	/api/broadcasts	Dispara broadcast (HSM ou freeform).
POST	/api/documents/manual	Ingere documento na base (chunking + embeddings).
GET	/api/prompts	Lista prompts nomeados.
PUT	/api/prompts/{name}	Atualiza prompt (deve conter {context}).
GET	/api/webhook-logs/events?phone=	Eventos de entrega Twilio por telefone.

Webhooks — inscrever

Cadastre uma URL pra receber eventos do cuby. O corpo é JSON, a assinatura HMAC-SHA256 chega em X-Cuby-Signature: sha256=<hex> calculada com o secret retornado no cadastro.

curl -X POST https://cuby.cubelabs.dev/api/v1/webhooks/subscriptions \
  -H "Authorization: Bearer $CUBY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-app.com/webhooks/cuby",
    "events": ["conversation_approved", "message_inbound"],
    "description": "produção"
  }'

events: [] (array vazio) = recebe tudo. Endpoints CRUD:GET /api/v1/webhooks/subscriptions,POST,PUT /api/v1/webhooks/subscriptions/{id},DELETE /api/v1/webhooks/subscriptions/{id}.

Payload dos eventos

Cada entrega tem o mesmo envelope:

POST /webhooks/cuby
X-Cuby-Signature: sha256=…
X-Cuby-Delivery: 42-1735000000000
Content-Type: application/json

{
  "event": "conversation_approved",
  "timestamp": "2026-08-06T23:59:00.000Z",
  "data": {
    "action_type": "conversation_approved",
    "actor_email": "[email protected]",
    "conversation_id": 12345,
    "target": "whatsapp:+5511999998888",
    "metadata": { … },
    "tokens_used": 812,
    "cost_usd": 0.0031,
    "source": "cuby_chatbot"
  }
}

Verificar assinatura

import { createHmac, timingSafeEqual } from 'crypto';

const signature = req.headers['x-cuby-signature']?.replace('sha256=', '');
const expected = createHmac('sha256', SECRET).update(rawBody).digest('hex');
const ok = signature && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!ok) return res.status(401).end();

MCP — cuby-mcp

Servidor MCP oficial, com 67 ferramentas. Roda via stdio, envolve a API acima com Authorization: Bearer. Cobre leitura (conversas, base de conhecimento, analytics, eventos), escrita (envio, aprovação, takeover, tags, notas) e admin (documentos, prompts, broadcasts, settings, webhooks).

{
  "mcpServers": {
    "cuby": {
      "command": "node",
      "args": ["/path/to/cuby-mcp/dist/index.js"],
      "env": {
        "CUBY_API_BASE_URL": "https://cuby.cubelabs.dev",
        "CUBY_API_KEY": "sk_..."
      }
    }
  }
}

Dúvida ou API key? [email protected].