API and webhooks

Which entry point to use

You want to…	Use
Read, create and edit documents from a script or AI agent	The MCP server, with an API key
Be notified when something changes in the wiki	Webhooks (below)
Talk to the wiki’s AI from another app (mobile, desktop)	The chat API, with a Keycloak token (below)
Understand the routes the app itself uses	The REST API (below)

The API key (nwk_) only works on MCP. REST routes answer 401 to it: they authenticate through the browser session.

Webhooks

In Configurações → Webhooks (admin), register an address and choose the events. On every change, the wiki sends a signed POST to it, in the background.

Events:

• 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
• * for all

Headers on each delivery:

Header	Content
NextWiki-Event	The event, e.g. documents.update
NextWiki-Signature	t=<unix>,s=<hex>: HMAC-SHA256 of "<unix>.<corpo>" with the webhook secret
User-Agent	NextWiki-Webhooks/1.0

The body is JSON with id, event, createdAt, actorId, webhookSubscriptionId and payload (the id and model of the resource that changed) — fetch the rest through MCP if you need it.

Check the signature before trusting the body, and reject deliveries with a t that is too old. A failed delivery is not retried, and 25 consecutive failures disable the webhook. The screen keeps the last 50 deliveries and sends a test event.

Chat API for apps

External apps (the desktop app, a mobile app) talk to the wiki’s AI using the person’s own Keycloak token. You need:

1. SSO through Keycloak configured (see administration).
2. The app’s client listed under Apps aceitos pelo token (KEYCLOAK_APPS_PERMITIDOS).

Method	Route	What it does
GET	/api/chat/projetos	Workspaces and projects the person can read
POST	/api/chat	A question, with the answer and sources
GET POST	/api/workspaces/{wid}/conversas	List (?colecaoId=) and create conversations
GET PATCH DELETE	/api/workspaces/{wid}/conversas/{id}	Read, rename and delete
PUT	/api/workspaces/{wid}/conversas/mensagens/{id}/avaliacao	👍/👎 with a reason
POST	/api/arquivos/anexo	Upload an attachment for the conversation

To receive the answer bit by bit (streaming), use the SignalR hub /api/hub/chat, which accepts the same token.

The person only sees what they would already see in the browser. Limits: POST /api/chat accepts 12 requests per minute per IP (RATE_LIMIT_SENSIVEL), 30 per person and 300 per app; GET /api/chat/projetos is outside the per-IP limit. On the hub, use WebSocket: with long polling, each poll counts toward the per-person and per-app limits.

The app’s REST API

The Next Wiki app is built on a REST API under /api, authenticated by the session (the nextwiki_session cookie, issued at sign-in). Errors follow the ProblemDetails standard (RFC 7807). The main groups:

Area	Routes
Documents	/api/documentos/{id} — content, rename, move, type, tags, comments, versions and restore, publish, export docx/pdf, archive and restore
Collections	/api/colecoes/{id} — permissions, links, pinned documents, metrics, types, stories
Workspaces	/api/workspaces/{id} — tree, search (/busca?q=), semantic search, trash, authentication, printing
Members and groups	/api/workspaces/{wid}/membros, /convites, /grupos, /contas
AI	/api/workspaces/{wid}/ia — providers, skills, ask, conflicts, semantic search; /api/workspaces/{wid}/agentes; /api/execucoes/{id}
Integrations	/api/me/integracoes, /api/colecoes/{id}/gitlab, /api/workspaces/{wid}/webhooks
API keys	/api/chaves
Public	/api/publico/{token} — document shared by link, no sign-in

These routes change with the product and carry no compatibility guarantee between versions. To integrate, prefer MCP and webhooks.