📘 Guide d'utilisation de l'API Notion¶

Techniques et patterns découverts pour manipuler les pages Notion via API

Dernière mise à jour : 2026-02-03

🔑 Configuration¶

Clé API¶

La clé API Notion est stockée dans la config MCP Cursor :

~/.cursor/mcp.json

Format : ntn_xxx... ou secret_xxx...

Endpoint de base¶

https://api.notion.com/v1/

Headers requis¶

-H 'Authorization: Bearer $NOTION_API_KEY'
-H 'Content-Type: application/json'
-H 'Notion-Version: 2022-06-28'

🛠️ Opérations courantes¶

1. Ajouter du contenu à une page¶

Endpoint : PATCH /blocks/{block_id}/children

curl -X PATCH "https://api.notion.com/v1/blocks/{page_id}/children" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-06-28" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{ "type": "text", "text": { "content": "Mon texte" } }]
        }
      }
    ]
  }'

2. Supprimer un bloc¶

Endpoint : DELETE /blocks/{block_id}

Via MCP : API-delete-a-block

3. Récupérer les enfants d'une page¶

Endpoint : GET /blocks/{block_id}/children

Via MCP : API-get-block-children

🎨 Blocs avancés¶

Colonnes (column_list)¶

⚠️ Non supporté par le MCP — Utiliser l'API directe

{
  "object": "block",
  "type": "column_list",
  "column_list": {
    "children": [
      {
        "object": "block",
        "type": "column",
        "column": {
          "children": [
            {
              "object": "block",
              "type": "paragraph",
              "paragraph": {
                "rich_text": [{ "type": "text", "text": { "content": "Colonne 1" } }]
              }
            }
          ]
        }
      },
      {
        "object": "block",
        "type": "column",
        "column": {
          "children": [
            {
              "object": "block",
              "type": "paragraph",
              "paragraph": {
                "rich_text": [{ "type": "text", "text": { "content": "Colonne 2" } }]
              }
            }
          ]
        }
      }
    ]
  }
}

Callout (encadré)¶

{
  "object": "block",
  "type": "callout",
  "callout": {
    "icon": { "type": "emoji", "emoji": "⚠️" },
    "color": "yellow_background",
    "rich_text": [{ "type": "text", "text": { "content": "Mon message" } }]
  }
}

Couleurs disponibles : - default, gray_background, brown_background, orange_background - yellow_background, green_background, blue_background - purple_background, pink_background, red_background

Mention de page (lien avec emoji/titre)¶

⚠️ Affiche automatiquement l'icône et le titre de la page

{
  "type": "mention",
  "mention": {
    "type": "page",
    "page": { "id": "page-uuid-here" }
  }
}

Exemple complet (texte + mention) :

{
  "rich_text": [
    { "type": "text", "text": { "content": "Voir : " } },
    { "type": "mention", "mention": { "type": "page", "page": { "id": "2fc06a07-4f52-80a2-bb0b-c95d81341d4e" } } }
  ]
}

Heading (titres)¶

// H2
{
  "object": "block",
  "type": "heading_2",
  "heading_2": {
    "rich_text": [{ "type": "text", "text": { "content": "Mon titre H2" } }]
  }
}

// H3
{
  "object": "block",
  "type": "heading_3",
  "heading_3": {
    "rich_text": [{ "type": "text", "text": { "content": "Mon titre H3" } }]
  }
}

Divider (séparateur)¶

{
  "object": "block",
  "type": "divider",
  "divider": {}
}

Bulleted list item¶

{
  "object": "block",
  "type": "bulleted_list_item",
  "bulleted_list_item": {
    "rich_text": [{ "type": "text", "text": { "content": "Mon item" } }]
  }
}

🔗 Liens et annotations¶

Lien dans le texte¶

{
  "type": "text",
  "text": {
    "content": "Texte cliquable",
    "link": { "url": "https://example.com" }
  }
}

Annotations (gras, italique, etc.)¶

{
  "type": "text",
  "text": { "content": "Texte en gras" },
  "annotations": {
    "bold": true,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  }
}

📄 Gestion des pages¶

Mettre à jour le titre d'une page¶

Endpoint : PATCH /pages/{page_id}

{
  "properties": {
    "title": [
      {
        "text": { "content": "Nouveau titre" }
      }
    ]
  }
}

Mettre à jour l'icône d'une page¶

{
  "icon": {
    "type": "emoji",
    "emoji": "🎯"
  }
}

Créer une page enfant¶

Endpoint : POST /pages

Via MCP : API-post-page

{
  "parent": { "page_id": "parent-page-uuid" },
  "properties": {
    "title": [{ "text": { "content": "Ma nouvelle page" } }]
  }
}

🎯 Patterns utiles¶

Pattern utilisé sur le Hub des analystes :

{
  "children": [
    { "object": "block", "type": "divider", "divider": {} },
    {
      "object": "block",
      "type": "column_list",
      "column_list": {
        "children": [
          {
            "object": "block",
            "type": "column",
            "column": {
              "children": [
                {
                  "object": "block",
                  "type": "callout",
                  "callout": {
                    "icon": { "type": "emoji", "emoji": "⬅️" },
                    "color": "gray_background",
                    "rich_text": [
                      { "type": "text", "text": { "content": "Précédent : " } },
                      { "type": "mention", "mention": { "type": "page", "page": { "id": "previous-page-id" } } }
                    ]
                  }
                }
              ]
            }
          },
          {
            "object": "block",
            "type": "column",
            "column": {
              "children": [
                {
                  "object": "block",
                  "type": "callout",
                  "callout": {
                    "icon": { "type": "emoji", "emoji": "➡️" },
                    "color": "gray_background",
                    "rich_text": [
                      { "type": "text", "text": { "content": "Suivant : " } },
                      { "type": "mention", "mention": { "type": "page", "page": { "id": "next-page-id" } } }
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

Structure de document type "règles"¶

{
  "children": [
    // Intro
    { "type": "paragraph", "paragraph": { "rich_text": [{ "type": "text", "text": { "content": "Introduction..." } }] } },
    { "type": "paragraph", "paragraph": { "rich_text": [] } },

    // Section principale
    { "type": "heading_2", "heading_2": { "rich_text": [{ "type": "text", "text": { "content": "🚫 INTERDIT" } }] } },
    { "type": "paragraph", "paragraph": { "rich_text": [] } },

    // Sous-section
    { "type": "heading_3", "heading_3": { "rich_text": [{ "type": "text", "text": { "content": "Confidentialité" } }] } },
    { "type": "bulleted_list_item", "bulleted_list_item": { "rich_text": [{ "type": "text", "text": { "content": "Règle 1" } }] } },
    { "type": "bulleted_list_item", "bulleted_list_item": { "rich_text": [{ "type": "text", "text": { "content": "Règle 2" } }] } },

    // Séparateur
    { "type": "divider", "divider": {} },

    // Callout conclusion
    {
      "type": "callout",
      "callout": {
        "icon": { "type": "emoji", "emoji": "⚠️" },
        "color": "yellow_background",
        "rich_text": [{ "type": "text", "text": { "content": "Avertissement important" } }]
      }
    }
  ]
}

⚠️ Limitations et contournements¶

MCP vs API directe¶

Fonctionnalité	MCP	API directe
Paragraphes, listes	✅	✅
Callouts	✅	✅
Colonnes (column_list)	❌	✅
Mentions de page	✅	✅
Dividers	✅	✅
Headings	✅	✅

Alignement de texte¶

❌ Notion ne supporte pas l'alignement de texte (gauche/centre/droite) dans les blocs.

Contournement : Utiliser des colonnes avec des colonnes vides pour "pousser" le contenu visuellement.

Caractères spéciaux en bash¶

Échapper les apostrophes dans les commandes curl :

# Correct
"content": "Ne jamais contacter un porteur de projet en direct"

# Si apostrophe dans le texte, utiliser '\''
"content": "Ne jamais partager les documents à l'\''extérieur"

🔍 Debugging¶

Erreurs courantes¶

Code	Message	Solution
404	`object_not_found`	Page non partagée avec l'intégration
400	`validation_error`	Format JSON invalide ou propriété incorrecte
401	`unauthorized`	Clé API invalide ou expirée

Vérifier le partage¶

Une page doit être explicitement partagée avec l'intégration Notion pour être accessible via API.

Process : 1. Ouvrir la page dans Notion 2. Cliquer sur "..." → "Add connections" 3. Sélectionner l'intégration (ex: "Cursor")

📚 Ressources¶

Guide maintenu par l'équipe technique Bricks

Sources¶

Project associé
Source migrée : bricks-os