Guide pour agents IA

Résumé complet de l'API Markdodo pour les agents IA n'utilisant pas le protocole MCP

Présentation

Ce guide récapitule l'ensemble des règles et endpoints de l'API Markdodo de manière synthétique, destiné aux agents IA qui interagissent avec l'API via des requêtes HTTP REST classiques.

Si votre environnement supporte le protocole MCP, le lien de connexion du serveur MCP est disponible sur votre dashboard utilisateur dans la section dédiée à votre site. Le serveur MCP expose les mêmes fonctionnalités via des outils dédiés (list_pages, create_page, update_page, delete_page, upload_image, upload_image_base64, read_page_markdown).

Authentification

Toutes les requêtes doivent inclure le header :

Authorization: Bearer <cle_api>

Règles critiques

1. Slugs immuables

Le slug est l'identifiant unique d'une page. Une fois créé, il ne peut plus être modifié. Le slug vide "" est réservé à la page d'accueil.

2. Menu et sous-menu

Les champs position_menu_page et position_submenu_page sont des FLOAT.

Une valeur 0 masque la page du menu correspondant.

3. Liens internes

[Voir la page](slug-de-la-page)
[Accueil]()

4. Hiérarchie parent/enfant

Pour placer une page dans un sous-menu :

définir id_parent_page
utiliser position_submenu_page > 0

5. Images

URL externe :

![alt](https://example.com/image.jpg)

Image hébergée :

![alt](slug-image)

6. Markdown étendu

[Texte]{align:center}
[Texte]{size:1.2}
[Texte]{tag:#3498db}
{BR}

7. Affichage des dates

show_date_page permet d'afficher ou masquer les dates de création et modification.

0 : masquer
1 : afficher

Endpoints

Lister les pages

GET /api/pages

Retourne les métadonnées des pages.

Lire le Markdown brut

GET /api/pages/markdown/[slug-page]

Exemple :

GET /api/pages/markdown/documentation

Créer une page

POST /api/pages

{
  "slug_page": "ma-page",
  "markdown": "# Mon titre",
  "show_date_page": 0
}

Modifier une page

PATCH /api/pages

{
  "slug_page": "ma-page",
  "markdown": "# Nouveau contenu",
  "show_date_page": 1
}

Supprimer une page

DELETE /api/pages

{
  "slug_page": "ma-page"
}

Envoyer une image par URL

POST /api/images/formData

Malgré son nom historique, cet endpoint attend désormais une URL publique d'image dans un body JSON.

{
  "image_url": "https://example.com/image.jpg",
  "slug_image": "mon-image"
}

Envoyer une image en base64

POST /api/images/base64

{
  "image": "data:image/png;base64,...",
  "slug_image": "mon-image",
  "alt_image": "Description"
}

Workflow type

GET /api/pages
POST /api/pages
POST /api/images/base64 ou /api/images/formData
PATCH /api/pages
Vérifier le rendu final