A API de IA da SuperCognit: constrói, publica e acompanha agentes a partir do teu código

A SuperCognit é uma plataforma no-code e, para a maioria das pessoas, isso basta: descreves o agente, associas o conhecimento, publicas. Mas a partir do momento em que geres agentes para uma centena de clientes, ligas conversas a um CRM ou integras a SuperCognit no teu próprio produto, clicar deixa de escalar. É para isso que existe a API — a mesma área de trabalho, comandada pelo teu código.

Uma chave, um cabeçalho

Cria uma chave de API na tua área de trabalho e envia-a no cabeçalho X-Api-Key. As chaves declaram âmbitos — é preciso escrita para tudo o que não seja um GET — e uma chave pode ficar limitada a um único produto, caso em que não toca em recursos da área de trabalho como ferramentas, bases de conhecimento ou webhooks. É toda a história da autenticação: sem OAuth, sem SDK para instalar.

curl https://api.supercognit.com/v1/products \
  -H "X-Api-Key: $SUPERCOGNIT_API_KEY"

Criar e publicar um agente sem abrir o painel

Um produto — agente de chat ou servidor MCP — é criado como rascunho, configurado e depois publicado. É exatamente o ciclo que o painel segue, e é por isso que as agências o usam para provisionar um agente por cliente diretamente no seu próprio onboarding.

curl -X POST https://api.supercognit.com/v1/products \
  -H "X-Api-Key: $SUPERCOGNIT_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "kind": "chat_agent",
    "title": "Acme support",
    "intro": "Hi! Ask me anything about Acme.",
    "systemPrompt": "You answer Acme customer questions from the attached knowledge."
  }'

A resposta traz o id e o slug do novo produto. A partir daí associas ferramentas e bases de conhecimento, alteras o prompt ou o preço e publicas — tudo pela mesma API.

O que a API cobre

• Produtos — criar, atualizar, publicar e despublicar agentes de chat e servidores MCP.
• Ferramentas — a biblioteca da área de trabalho: ferramentas LLM, HTTP e estáticas, os seus inputs e que produtos as usam.
• Bases de conhecimento — o conhecimento que sustenta as respostas e onde cada base está associada.
• Conversas — sessões e transcrições completas, com o modelo e a contagem de tokens em cada mensagem.
• Webhooks — endpoints, o registo de entregas e as tentativas.
• Carteira — o saldo de créditos de utilização e cada carregamento, débito e reembolso.
• Utilizadores finais — validar um token de sessão do lado do servidor, para a tua aplicação saber com quem fala.

Eventos, enviados para si

Consultar a API serve para recuperar histórico, mas o tempo real deve chegar sozinho. Regista um endpoint e a SuperCognit envia JSON por POST à medida que as conversas acontecem: conversation.created quando alguém inicia uma conversa, message.created em cada mensagem, message.completed quando o agente termina a resposta. As entregas são repetidas até cinco vezes com recuo exponencial e ficam registadas com o estado da resposta, para que nada desapareça em silêncio.

Cada pedido é assinado. Calcula o HMAC-SHA256 do corpo ORIGINAL com o segredo do endpoint e compara-o com o cabeçalho X-Supercognit-Signature — sobre os bytes exatos que recebeste, nunca sobre uma cópia reserializada do JSON.

import { createHmac, timingSafeEqual } from "node:crypto";

const expected = "sha256=" + createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");
const valid = timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));

O que as equipas constroem com ela

REST para os seus sistemas, MCP para clientes de IA

As duas superfícies para programadores respondem a perguntas diferentes. A API é a forma de o teu código comandar a SuperCognit. O MCP é a forma de os clientes de IA — Claude, Cursor, os teus próprios agentes — usarem o que publicas. Ambos correm sobre a mesma área de trabalho, por isso uma ferramenta construída uma vez fica acessível dos dois lados, e o servidor MCP da própria plataforma expõe os mesmos recursos dentro do assistente onde já trabalhas.

Comece pela referência

A referência completa é pública e interativa em api.supercognit.com/docs, gerada a partir de um documento OpenAPI 3.1 que podes dar diretamente a um gerador de clientes. Cria uma chave, corre a primeira chamada acima e vê a tua área de trabalho responder em JSON — grátis durante 7 dias.