API e webhooks

Qual porta de entrada usar

Você quer…	Use
Ler, criar e editar documentos por um script ou agente de IA	O servidor MCP, com chave de API
Ser avisado quando algo muda na wiki	Webhooks (abaixo)
Conversar com a IA da wiki a partir de outro app (celular, desktop)	A API da conversa, com token do Keycloak (abaixo)
Entender as rotas que o próprio app usa	A API REST (abaixo)

A chave de API (nwk_) só vale no MCP. As rotas REST respondem 401 a ela: elas autenticam pela sessão do navegador.

Webhooks

Em Configurações → Webhooks (admin), cadastre um endereço e escolha os eventos. A cada mudança, a wiki faz um POST assinado para ele, em segundo plano.

Eventos:

• documents.create, documents.update, documents.move, documents.publish, documents.unpublish, documents.archive, documents.unarchive, documents.delete
• collections.create, collections.update, collections.delete
• comments.create
• members.invite
• * para todos

Cabeçalhos de cada entrega:

Cabeçalho	Conteúdo
NextWiki-Event	O evento, ex.: documents.update
NextWiki-Signature	t=<unix>,s=<hex>: HMAC-SHA256 de "<unix>.<corpo>" com o segredo do webhook
User-Agent	NextWiki-Webhooks/1.0

O corpo é JSON com id, event, createdAt, actorId, webhookSubscriptionId e payload (o id e o model do recurso que mudou) — busque o resto pelo MCP se precisar.

Confira a assinatura antes de confiar no corpo, e recuse entregas com t muito antigo. Uma entrega que falha não é reenviada, e 25 falhas seguidas desligam o webhook. A tela guarda as últimas 50 entregas e envia um evento de teste.

API da conversa para apps

Apps externos (o app de mesa, um app de celular) conversam com a IA da wiki usando o token do Keycloak da própria pessoa. É preciso:

1. O SSO por Keycloak configurado (veja administração).
2. O cliente do app listado em Apps permitidos (KEYCLOAK_APPS_PERMITIDOS).

Método	Rota	O que faz
GET	/api/chat/projetos	Workspaces e projetos que a pessoa pode ler
POST	/api/chat	Uma pergunta, com a resposta e as fontes
GET POST	/api/workspaces/{wid}/conversas	Listar (?colecaoId=) e criar conversas
GET PATCH DELETE	/api/workspaces/{wid}/conversas/{id}	Ler, renomear e excluir
PUT	/api/workspaces/{wid}/conversas/mensagens/{id}/avaliacao	👍/👎 com motivo
POST	/api/arquivos/anexo	Enviar um anexo para a conversa

Para receber a resposta aos poucos (streaming), use o hub SignalR /api/hub/chat, que aceita o mesmo token.

A pessoa só vê o que já veria no navegador. Limites: POST /api/chat aceita 12 pedidos por minuto por IP (RATE_LIMIT_SENSIVEL), 30 por pessoa e 300 por app; GET /api/chat/projetos fica fora do limite por IP. No hub, use WebSocket: em long polling, cada consulta conta nos limites por pessoa e por app.

API REST do app

O app da Next Wiki é feito sobre uma API REST em /api, autenticada pela sessão (cookie nextwiki_session, emitido no login). Os erros seguem o padrão ProblemDetails (RFC 7807). Os principais grupos:

Área	Rotas
Documentos	/api/documentos/{id} — conteúdo, renomear, mover, tipo, tags, comentários, versões e restauração, publicar, exportar docx/pdf, arquivar e restaurar
Coleções	/api/colecoes/{id} — permissões, links, documentos fixados, métricas, tipos, histórias
Workspaces	/api/workspaces/{id} — árvore, busca (/busca?q=), busca semântica, lixeira, autenticação, impressão
Membros e grupos	/api/workspaces/{wid}/membros, /convites, /grupos, /contas
IA	/api/workspaces/{wid}/ia — provedores, skills, perguntar, conflitos, busca semântica; /api/workspaces/{wid}/agentes; /api/execucoes/{id}
Integrações	/api/me/integracoes, /api/colecoes/{id}/gitlab, /api/workspaces/{wid}/webhooks
Chaves de API	/api/chaves
Público	/api/publico/{token} — documento compartilhado por link, sem login

Essas rotas mudam com o produto e não têm garantia de compatibilidade entre versões. Para integrar, prefira o MCP e os webhooks.