Référence API — Knowledge

Knowledge est le module de contenu : wiki interne, base de connaissance publique et blog. Il expose une gestion membre (JWT), une surface publique anonyme (lecture par slug), une surface d'intégration par clé API, et un serveur MCP.

• Base URL — prod : https://knowledge.api.puwapi.com · dev : http://localhost:6300

Concepts¶

• Space (espace) — mode : internal (wiki collaboratif), public_kb (base publique), blog. Chaque espace a un slug unique global.
• Collection — regroupe des articles dans un espace.
• Article — kind : rich (éditeur Tiptap, JSON) ou developer (Markdown, contentMarkdown). Le kind est immuable. Statuts : draft → review → published → archived. sortOrder = ordre de lecture.

Gestion membre (JWT + gating knowledge)¶

Base : /api/knowledge

Méthode	Route	Rôle
GET/POST	/api/knowledge/spaces	Lister / créer des espaces
GET/PATCH/DELETE	/api/knowledge/spaces/{id}	Détail / modifier / supprimer
GET/POST	/api/knowledge/spaces/{id}/collections	Collections
PATCH/DELETE	/api/knowledge/collections/{id}	Modifier / supprimer une collection
GET/POST	/api/knowledge/spaces/{id}/articles	Lister / créer des articles
GET/PATCH/DELETE	/api/knowledge/articles/{id}	Détail / modifier / archiver
POST	/api/knowledge/spaces/{id}/articles/reorder	Ordre de lecture ({ articleIds })
POST	/api/knowledge/articles/{id}/status	Transition de statut
POST	/api/knowledge/articles/{id}/publish	Publier
GET	/api/knowledge/articles/{id}/versions	Historique des versions
POST	/api/knowledge/articles/{id}/versions/{vid}/restore	Restaurer une version
GET/POST	/api/knowledge/articles/{id}/comments	Commentaires
GET	/api/knowledge/search	Recherche interne
GET	/api/knowledge/spaces/{id}/analytics	Statistiques d'un espace

IA (/api/knowledge/ai) : suggest, rewrite, summarize, qa (branché sur le module IA).

Clés API (/api/knowledge/keys) : GET, POST ({label, scope}), DELETE {id}.

Surface d'intégration (clé API — X-Server-API-Key)¶

Base : /api/public/knowledge — miroir machine-à-machine de la gestion membre. Le scope write est requis pour les mutations (sinon 403).

Méthode	Route
GET	/spaces, /spaces/{id}, /spaces/{id}/collections, /spaces/{id}/articles, /articles/{id}, /search
POST	/spaces, /spaces/{id}/collections, /spaces/{id}/articles, /spaces/{id}/articles/reorder, /articles/{id}/status, /articles/{id}/publish
PATCH	/spaces/{id}, /collections/{id}, /articles/{id}
DELETE	/spaces/{id}, /collections/{id}, /articles/{id}

Sur cette surface, un article créé est de kind = developer (Markdown) par défaut.

Exemple — créer et publier un article :

BASE=https://knowledge.api.puwapi.com/api/public/knowledge
# 1) créer l'espace
curl -X POST $BASE/spaces -H "X-Server-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Docs","mode":"public_kb"}'
# 2) créer une collection puis un article developer (contentMarkdown)
curl -X POST $BASE/spaces/$SID/articles -H "X-Server-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"title":"Intro","collectionId":"'$CID'","kind":"developer","contentMarkdown":"# Titre\n\ncorps"}'
# 3) publier
curl -X POST $BASE/articles/$AID/publish -H "X-Server-API-Key: $KEY"

Surface publique anonyme (lecture par slug)¶

Base : /api/knowledge/public — directory, spaces/{slug}, spaces/{slug}/articles, spaces/{slug}/articles/{articleSlug}, abonnés blog (subscribe/confirm/unsubscribe), spaces/{slug}/qa. Aucune clé requise ; n'expose jamais d'tenantId.

Serveur MCP¶

@puwapi/knowledge-mcp expose ~20 outils (lecture + écriture d'articles/espaces/collections, versions, reorder, publish/archive) au-dessus de la surface d'intégration. Configuration : PUWAPI_KNOWLEDGE_API_KEY (obligatoire) + PUWAPI_KNOWLEDGE_API_URL (défaut prod). Le scope write de la clé conditionne les outils d'écriture.