Publier de la documentation par l'API

Objectif : créer un espace, une collection et des articles Markdown dans Knowledge, par programme. C'est exactement ainsi que cette documentation a été publiée.

Prérequis : une clé API Knowledge de scope write (voir Clés API serveur).

1. Créer un espace¶

BASE=https://knowledge.api.puwapi.com/api/public/knowledge
KEY=pkk_live_xxx

SID=$(curl -s -X POST $BASE/spaces \
  -H "X-Server-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Ma base","mode":"public_kb","isIndexed":true}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

mode = public_kb (base publique), blog, ou internal (wiki collaboratif).

2. Créer une collection¶

CID=$(curl -s -X POST $BASE/spaces/$SID/collections \
  -H "X-Server-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Guides"}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

3. Créer un article Markdown, puis le publier¶

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

AID=$(curl -s -X POST $BASE/spaces/$SID/articles \
  -H "X-Server-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"title":"Bien démarrer","collectionId":"'$CID'","kind":"developer",
       "contentMarkdown":"# Bien démarrer\n\nBienvenue **dans la base**."}' \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')

curl -X POST $BASE/articles/$AID/publish -H "X-Server-API-Key: $KEY"

Un article est créé en draft ; l'endpoint publish le rend public.

4. Ordonner la lecture¶

curl -X POST $BASE/spaces/$SID/articles/reorder \
  -H "X-Server-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"articleIds":["'$AID1'","'$AID2'","'$AID3'"]}'

Le rang dans la liste devient le sortOrder (1, 2, 3…).

5. Résultat¶

L'espace est lisible à https://knowledge.puwapi.com/{org}/{slug} ({org} = le slug de votre organisation ; celui de l'espace est dans la réponse de création).

Idempotence & mises à jour¶

• Pour mettre à jour un article : PATCH /articles/{id} avec le nouveau contentMarkdown, puis re-publish. Rejouer ne duplique rien.
• Conservez la correspondance clé logique → id (par ex. dans un fichier d'état) pour réexécuter votre script sans recréer de doublons.
• Automatisez tout cela sans écrire de HTTP : voir Piloter Knowledge avec le serveur MCP.