Docs / reference

API d’administration

Points de terminaison authentifiés qui modifient le contenu du site via des commits git validés.

Tous les endpoints d’administration nécessitent un agent service token : Authorization: Bearer jgx_agt_… (la CLI lit l’env JENKSGUO_ADMIN_TOKEN). Jenks crée des tokens dans la console sur https://admin.jenksguo.xyz/admin → Accès après connexion avec Google (Cloudflare Access) ; chacun a un nom, un périmètre (content, media, publish ; tous les tokens peuvent lire), une expiration et peut être révoqué. Écrire sur la branche main requiert aussi publish. Chaque écriture et chaque tentative refusée vont dans le journal d’audit. Voir Donner l’accès à un agent IA. Les écritures sont validées avec le même schéma que le build, puis commit dans GitHub. Le CI traduit les entrées modifiées dans chaque langue, reconstruit et déploie : main → jenksguo.pages.dev et jenksguo.xyz, dev → dev.jenksguo.xyz.

Méthode	Chemin	Outil
GET · POST	`/api/admin/tokens`	— (réservé aux personnes : lister ou créer des agent tokens ; SSO)
DELETE	`/api/admin/tokens/{id}`	— (réservé aux personnes : révoquer ; SSO)
POST	`/api/admin/login` · `/api/admin/logout`	— (développement local uniquement)
GET	`/api/admin/whoami`	`admin_whoami`
GET	`/api/admin/audit`	`admin_audit_log`
GET	`/api/admin/schema`	`admin_schema`
GET	`/api/admin/files`	`admin_list_files`
GET	`/api/admin/file`	`admin_read_file`
POST	`/api/admin/validate`	`admin_validate`
PUT	`/api/admin/file`	`admin_write_file`
DELETE	`/api/admin/file`	`admin_delete_file`
POST	`/api/admin/changes`	`admin_commit_changes`
POST	`/api/admin/ai-edit`	`admin_ai_edit`
GET	`/api/admin/translation`	`admin_read_translation`
PUT	`/api/admin/translation`	`admin_write_translation`
GET	`/api/admin/copy`	`admin_read_copy`
PUT	`/api/admin/copy`	`admin_write_copy`
GET	`/api/admin/deploys`	`admin_deploy_status`
POST	`/api/admin/promote`	`admin_promote`
POST	`/api/admin/cv`	`admin_publish_cv`
GET	`/api/admin/media`	`admin_list_media`
POST	`/api/admin/media`	`admin_upload_media`
PATCH	`/api/admin/media`	`admin_update_media`
DELETE	`/api/admin/media`	`admin_delete_media`

Erreurs : 401 unauthorized · unknown_token · token_expired · token_revoked, 403 missing_scope (avec needs[]) · sso_required · forbidden_path (seuls les fichiers de contenu sont inscriptibles), 422 invalid avec errors[], 409/502 github_error, 503 github_not_configured.

`admin_whoami` — Qui suis-je

Vérifiez votre justificatif : qui vous êtes (email SSO ou nom du agent token), vos périmètres, quand votre token expire et si la publication (GitHub) est configurée.

MCP : admin_whoami sur https://jenksguo.pages.dev/mcp/admin
REST : GET /api/admin/whoami (agent token)
Scope : read
CLI : jenks admin whoami

Aucun argument.

curl -s "https://jenksguo.pages.dev/api/admin/whoami" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_audit_log` — Journal d’audit

Actions d’administration récentes, les plus récentes en premier : qui (email SSO ou agent token), quoi, quels fichiers, branche, hôte et résultat. Un agent token ne voit que ses propres actions.

MCP : admin_audit_log sur https://jenksguo.pages.dev/mcp/admin
REST : GET /api/admin/audit?limit=&token= (agent token)
Scope : read
CLI : jenks admin audit [--limit 50]

Argument	Type	Obligatoire	Remarques
`limit`	integer	non
`token`	string	non	Uniquement cet id d’agent token (réservé aux personnes)

curl -s "https://jenksguo.pages.dev/api/admin/audit" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_schema` — Schéma de contenu

Le modèle de contenu : champs et règles des entrées, tags, lentilles, types, chemins inscriptibles, documents et conventions d’édition. À lire avant d’écrire.

MCP : admin_schema sur https://jenksguo.pages.dev/mcp/admin
REST : GET /api/admin/schema (agent token)
Scope : read
CLI : jenks admin schema

Aucun argument.

curl -s "https://jenksguo.pages.dev/api/admin/schema" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_list_files` — Lister les fichiers de contenu

Lister les fichiers de contenu modifiables sur une branche (chemin, taille, sha), éventuellement dans un dossier tel que content/corpus/experiences.

MCP : admin_list_files sur https://jenksguo.pages.dev/mcp/admin
REST : GET /api/admin/files?dir=&branch= (agent token)
Scope : read
CLI : jenks admin ls [dir]

Argument	Type	Obligatoire	Remarques
`dir`	string	non	par ex. content/corpus/projects (par défaut : tout le contenu)
`branch`	`main` · `dev`	non	main publie le site en ligne (jenksguo.pages.dev et son miroir jenksguo.xyz) ; dev prévisualise sur dev.jenksguo.xyz (par défaut main).

curl -s "https://jenksguo.pages.dev/api/admin/files" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_read_file` — Lire un fichier de contenu

Lire la source Markdown/JSON brute d’un fichier de contenu (avec son sha). Passer path, ou slug pour une entrée, une lentille ou une compétence.

MCP : admin_read_file sur https://jenksguo.pages.dev/mcp/admin
REST : GET /api/admin/file?path=&slug=&branch= (agent token)
Scope : read
CLI : jenks admin get <slug|path>

Argument	Type	Obligatoire	Remarques
`path`	string	non
`slug`	string	non
`branch`	`main` · `dev`	non	main publie le site en ligne (jenksguo.pages.dev et son miroir jenksguo.xyz) ; dev prévisualise sur dev.jenksguo.xyz (par défaut main).

curl -s "https://jenksguo.pages.dev/api/admin/file" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_validate` — Valider une modification

Valider le contenu d’un fichier par rapport au schéma de contenu sans commit. Renvoie une liste de problèmes (vide = valide).

MCP : admin_validate sur https://jenksguo.pages.dev/mcp/admin
REST : POST /api/admin/validate (agent token)
Scope : read
CLI : jenks admin validate <path> <file>

Argument	Type	Obligatoire	Remarques
`path`	string	oui
`content`	string	oui

curl -s -X POST https://jenksguo.pages.dev/api/admin/validate \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path":"content/corpus/projects/example.md","content":"<content>"}'

`admin_write_file` — Créer ou mettre à jour un fichier de contenu

Valider et commit un fichier de contenu (création ou remplacement). La publication est automatique : le CI retraduit les entrées modifiées dans toutes les langues, reconstruit et déploie (main → jenksguo.pages.dev et jenksguo.xyz, dev → dev.jenksguo.xyz) en quelques minutes.

MCP : admin_write_file sur https://jenksguo.pages.dev/mcp/admin
REST : PUT /api/admin/file (agent token)
Scope : content (+ publish pour la branche main)
CLI : jenks admin put <path> <file> -m <message>

Argument	Type	Obligatoire	Remarques
`path`	string	oui
`content`	string	oui
`message`	string	oui	Message de commit
`branch`	`main` · `dev`	non	main publie le site en ligne (jenksguo.pages.dev et son miroir jenksguo.xyz) ; dev prévisualise sur dev.jenksguo.xyz (par défaut main).

curl -s -X PUT https://jenksguo.pages.dev/api/admin/file \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path":"content/corpus/projects/example.md","content":"<content>","message":"<message>"}'

`admin_delete_file` — Supprimer un fichier de contenu

Supprimer un fichier de contenu (p. ex. retirer une entrée) avec un message de commit. L’historique Git le garde récupérable.

MCP : admin_delete_file sur https://jenksguo.pages.dev/mcp/admin
REST : DELETE /api/admin/file?path=&message=&branch= (agent token)
Scope : content (+ publish pour la branche main)
CLI : jenks admin rm <path> -m <message>

Argument	Type	Obligatoire	Remarques
`path`	string	oui
`message`	string	oui
`branch`	`main` · `dev`	non	main publie le site en ligne (jenksguo.pages.dev et son miroir jenksguo.xyz) ; dev prévisualise sur dev.jenksguo.xyz (par défaut main).

curl -s -X DELETE https://jenksguo.pages.dev/api/admin/file \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path":"content/corpus/projects/example.md","message":"<message>"}'

`admin_commit_changes` — Committer plusieurs fichiers en une fois

Valider et commit plusieurs modifications de fichiers en UN seul commit. Chaque modification est {path, content} ou {path, delete: true}.

MCP : admin_commit_changes sur https://jenksguo.pages.dev/mcp/admin
REST : POST /api/admin/changes (agent token)
Scope : content (+ publish pour la branche main)
CLI : jenks admin commit <changes.json> -m <message>

Argument	Type	Obligatoire	Remarques
`changes`	array	oui
`message`	string	oui
`branch`	`main` · `dev`	non	main publie le site en ligne (jenksguo.pages.dev et son miroir jenksguo.xyz) ; dev prévisualise sur dev.jenksguo.xyz (par défaut main).

curl -s -X POST https://jenksguo.pages.dev/api/admin/changes \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"changes":"<changes>","message":"<message>"}'

`admin_ai_edit` — Proposer une modification avec l’IA

Demander au modèle du site de réécrire un fichier de contenu à partir d’une instruction en anglais simple. Renvoie le contenu proposé, un diff et les problèmes de validation. Ne commit PAS — relisez, puis appelez admin_write_file.

MCP : admin_ai_edit sur https://jenksguo.pages.dev/mcp/admin
REST : POST /api/admin/ai-edit (agent token)
Scope : content
CLI : jenks admin ai-edit <slug|path> "<instruction>" [--apply]

Argument	Type	Obligatoire	Remarques
`path`	string	non
`slug`	string	non
`instruction`	string	oui
`branch`	`main` · `dev`	non	main publie le site en ligne (jenksguo.pages.dev et son miroir jenksguo.xyz) ; dev prévisualise sur dev.jenksguo.xyz (par défaut main).
`content`	string	non	Texte de fichier non enregistré facultatif pour servir de base (par défaut : le fichier enregistré).

curl -s -X POST https://jenksguo.pages.dev/api/admin/ai-edit \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"instruction":"<instruction>"}'

`admin_read_translation` — Lire une traduction

Un fichier de contenu dans une autre langue : les champs source en anglais, la traduction actuelle et son statut (à jour, obsolète, modifiée à la main, manquante). Fonctionne pour les entrées, lentilles, CV, arguments, pages point de vue, titres, talks et la doc. Langues : zh, zh-hant, ja, fr, es, eo.

MCP : admin_read_translation sur https://jenksguo.pages.dev/mcp/admin
REST : GET /api/admin/translation?path=&slug=&locale=&branch= (agent token)
Scope : read
CLI : jenks admin tr get <slug|path> <locale>

Argument	Type	Obligatoire	Remarques
`path`	string	non
`slug`	string	non
`locale`	`zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	oui
`branch`	`main` · `dev`	non	main publie le site en ligne (jenksguo.pages.dev et son miroir jenksguo.xyz) ; dev prévisualise sur dev.jenksguo.xyz (par défaut main).

curl -s "https://jenksguo.pages.dev/api/admin/translation" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_write_translation` — Modifier une traduction

Écrire le texte d’un fichier de contenu dans une autre langue (zh, zh-hant, ja, fr, es, eo) — par exemple une meilleure synthèse en chinois. Donnez uniquement les champs à changer ; lisez d’abord admin_read_translation pour les noms de champs. Le Markdown doit conserver les titres, blocs de code et liens en anglais. La modification est conservée jusqu’à ce que l’anglais change ; ensuite cette langue est retraduite automatiquement. L’anglais est la source : modifiez-le avec admin_write_file.

MCP : admin_write_translation sur https://jenksguo.pages.dev/mcp/admin
REST : PUT /api/admin/translation (agent token)
Scope : content (+ publish pour la branche main)
CLI : jenks admin tr put <slug|path> <locale> <fields.json> -m <message>

Argument	Type	Obligatoire	Remarques
`path`	string	non
`slug`	string	non
`locale`	`zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	oui
`fields`	object	oui	p. ex. {"summary": "…", "body": "## …"}
`message`	string	non	Message de commit
`branch`	`main` · `dev`	non	main publie le site en ligne (jenksguo.pages.dev et son miroir jenksguo.xyz) ; dev prévisualise sur dev.jenksguo.xyz (par défaut main).

curl -s -X PUT https://jenksguo.pages.dev/api/admin/translation \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"locale":"<locale>","fields":"<fields>"}'

`admin_read_copy` — Lire les textes d’interface du site

Les textes d’interface du site dans une langue — menus, titres de page, intros en une ligne, accroche du hero, boutons, descriptions SEO — sous forme clé → texte, avec l’anglais (et le chinois pour zh-hant) à côté. Filtrer avec un préfixe, p. ex. hero ou career.

MCP : admin_read_copy sur https://jenksguo.pages.dev/mcp/admin
REST : GET /api/admin/copy?locale=&prefix=&branch= (agent token)
Scope : read
CLI : jenks admin copy get <locale> [prefix]

Argument	Type	Obligatoire	Remarques
`locale`	`en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	oui
`prefix`	string	non
`branch`	`main` · `dev`	non	main publie le site en ligne (jenksguo.pages.dev et son miroir jenksguo.xyz) ; dev prévisualise sur dev.jenksguo.xyz (par défaut main).

curl -s "https://jenksguo.pages.dev/api/admin/copy" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_write_copy` — Modifier les textes d’interface du site

Modifier les textes d’interface dans une langue : values est clé → texte ("" supprime votre modification). en et zh sont les sources rédigées à la main : un changement en anglais est traduit en ja, fr, es et eo automatiquement — réglez aussi zh. Une modification dans une autre langue est conservée jusqu’à ce que son texte source change. Conservez exactement les {placeholders}.

MCP : admin_write_copy sur https://jenksguo.pages.dev/mcp/admin
REST : PUT /api/admin/copy (agent token)
Scope : content (+ publish pour la branche main)
CLI : jenks admin copy set <locale> <key> "<text>" -m <message>

Argument	Type	Obligatoire	Remarques
`locale`	`en` · `zh` · `zh-hant` · `ja` · `fr` · `es` · `eo`	oui
`values`	object	oui	p. ex. {"hero.sub": "…"}
`message`	string	non
`branch`	`main` · `dev`	non	main publie le site en ligne (jenksguo.pages.dev et son miroir jenksguo.xyz) ; dev prévisualise sur dev.jenksguo.xyz (par défaut main).

curl -s -X PUT https://jenksguo.pages.dev/api/admin/copy \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"locale":"<locale>","values":"<values>"}'

`admin_deploy_status` — État des déploiements

Exécutions CI récentes (traduire → build → déployer) avec statut, branche, commit et liens.

MCP : admin_deploy_status sur https://jenksguo.pages.dev/mcp/admin
REST : GET /api/admin/deploys?branch= (agent token)
Scope : read
CLI : jenks admin deploys

Argument	Type	Obligatoire	Remarques
`branch`	`main` · `dev`	non	main publie le site en ligne (jenksguo.pages.dev et son miroir jenksguo.xyz) ; dev prévisualise sur dev.jenksguo.xyz (par défaut main).

curl -s "https://jenksguo.pages.dev/api/admin/deploys" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_promote` — Promouvoir dev en production

Fusionner la branche dev dans main, publiant tout ce qui a été prévisualisé sur dev.jenksguo.xyz vers le site en ligne (jenksguo.pages.dev et jenksguo.xyz).

MCP : admin_promote sur https://jenksguo.pages.dev/mcp/admin
REST : POST /api/admin/promote (agent token)
Scope : publish
CLI : jenks admin promote

Argument	Type	Obligatoire	Remarques
`message`	string	non

curl -s -X POST https://jenksguo.pages.dev/api/admin/promote \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{}'

`admin_publish_cv` — Publier une nouvelle version de CV

Téléverser un nouveau PDF pour un CV (ai, web3 ou un nouveau slug) et en faire la version actuelle en une étape : le PDF va dans la médiathèque, la version précédente passe dans l’historique du CV (toujours téléchargeable), et la modification est commit (le CI la publie). Image d’aperçu et nouveau titre/synthèse facultatifs. L’URL stable /cv/.pdf sert ensuite le nouveau fichier.

MCP : admin_publish_cv sur https://jenksguo.pages.dev/mcp/admin
REST : POST /api/admin/cv (agent token)
Scope : content + media (+ publish pour la branche main)
CLI : jenks admin cv publish <slug> <file.pdf> --cv-version 2026.10 [--preview /media/…]

Argument	Type	Obligatoire	Remarques
`slug`	string	oui	ai, web3, ou un nouvel identifiant en kebab-case
`version`	string	oui	p. ex. 2026.10
`filename`	string	non
`data`	string	non	Octets du PDF, base64
`url`	string	non	Alternative à data : URL https du PDF
`preview`	string	non	Facultatif : une image /media/… déjà téléversée de la page 1
`title`	string	non
`summary`	string	non
`message`	string	non	Message de commit
`branch`	`main` · `dev`	non	main publie le site en ligne (jenksguo.pages.dev et son miroir jenksguo.xyz) ; dev prévisualise sur dev.jenksguo.xyz (par défaut main).

curl -s -X POST https://jenksguo.pages.dev/api/admin/cv \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"slug":"<slug>","version":"<version>"}'

`admin_list_media` — Lister les médias

Lister les images, vidéos et PDF téléversés (les plus récents en premier) : url, type, taille, dimensions, texte alternatif, Markdown prêt à coller et quelles entrées utilisent chaque fichier.

MCP : admin_list_media sur https://jenksguo.pages.dev/mcp/admin
REST : GET /api/admin/media?prefix=&cursor=&limit= (agent token)
Scope : read
CLI : jenks admin media ls [prefix]

Argument	Type	Obligatoire	Remarques
`prefix`	string	non	Préfixe de clé tel que 2026/10
`cursor`	string	non
`limit`	integer	non

curl -s "https://jenksguo.pages.dev/api/admin/media" \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

`admin_upload_media` — Téléverser des médias

Stocker une image (webp, jpg, png, gif, avif, svg), une vidéo (mp4, webm) ou un PDF, jusqu’à 25 Mo, dans Cloudflare R2 et obtenir son url publique /media/… et son Markdown. Envoyer data en base64 avec un filename, ou une url https publique à importer. Les fichiers sont publics par URL immédiatement ; référencez-les depuis le contenu avec admin_write_file. L’endpoint REST accepte aussi multipart/form-data (champ file).

MCP : admin_upload_media sur https://jenksguo.pages.dev/mcp/admin
REST : POST /api/admin/media (agent token)
Scope : media
CLI : jenks admin media upload <file|https-url> [--alt "…"]

Argument	Type	Obligatoire	Remarques
`filename`	string	non	Nom de fichier original ; devient la partie lisible de l’url.
`data`	string	non	Octets du fichier, base64 (un préfixe data: URL est autorisé).
`url`	string	non	Alternative à data : une URL https que le serveur télécharge.
`alt`	string	non	Texte alternatif : ce que montre l’image, pour les lecteurs d’écran et le bot.
`width`	integer	non
`height`	integer	non

curl -s -X POST https://jenksguo.pages.dev/api/admin/media \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{}'

`admin_update_media` — Mettre à jour le texte alternatif

Modifier le texte alternatif stocké d’un fichier téléversé (l’alt par défaut quand il est inséré dans le contenu).

MCP : admin_update_media sur https://jenksguo.pages.dev/mcp/admin
REST : PATCH /api/admin/media (agent token)
Scope : media
CLI : jenks admin media alt <key> "<alt text>"

Argument	Type	Obligatoire	Remarques
`key`	string	oui	Clé ou url du média, p. ex. 2026/10/xero-talk-1a2b3c4d5e.webp
`alt`	string	oui

curl -s -X PATCH https://jenksguo.pages.dev/api/admin/media \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"key":"<key>","alt":"<alt>"}'

`admin_delete_media` — Supprimer un média

Supprimer définitivement un fichier téléversé. Refusé tant que du contenu publié l’utilise, sauf si force est vrai. Non récupérable — contrairement aux fichiers de contenu, il n’y a pas d’historique git.

MCP : admin_delete_media sur https://jenksguo.pages.dev/mcp/admin
REST : DELETE /api/admin/media?key=&force= (agent token)
Scope : media
CLI : jenks admin media rm <key> [--force]

Argument	Type	Obligatoire	Remarques
`key`	string	oui
`force`	boolean	non

curl -s -X DELETE https://jenksguo.pages.dev/api/admin/media \
  -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"key":"<key>"}'

.mdCette page est traduite avec l’aide de l’IA ; les titres officiels restent en anglais.

API d’administration

admin_whoami — Qui suis-je

admin_audit_log — Journal d’audit

admin_schema — Schéma de contenu

admin_list_files — Lister les fichiers de contenu

admin_read_file — Lire un fichier de contenu

admin_validate — Valider une modification

admin_write_file — Créer ou mettre à jour un fichier de contenu

admin_delete_file — Supprimer un fichier de contenu

admin_commit_changes — Committer plusieurs fichiers en une fois

admin_ai_edit — Proposer une modification avec l’IA

admin_read_translation — Lire une traduction

admin_write_translation — Modifier une traduction

admin_read_copy — Lire les textes d’interface du site

admin_write_copy — Modifier les textes d’interface du site

admin_deploy_status — État des déploiements

admin_promote — Promouvoir dev en production

admin_publish_cv — Publier une nouvelle version de CV

admin_list_media — Lister les médias

admin_upload_media — Téléverser des médias

admin_update_media — Mettre à jour le texte alternatif

admin_delete_media — Supprimer un média