notion-api

Par mkurman · zorai

npx skills add https://github.com/mkurman/zorai --skill notion-api

name: notion-api description: > Cette compétence fournit des instructions complètes pour interagir avec l'API Notion via des appels REST. Cette compétence doit être utilisée chaque fois que l'utilisateur demande d'interagir avec Notion, y compris la lecture, la création, la mise à jour ou la suppression de pages, de bases de données, de blocs, de commentaires ou de tout autre contenu Notion. La compétence couvre l'authentification, tous les endpoints disponibles, la pagination, la gestion des erreurs et les bonnes pratiques.

tags: [productivity, agent-skills, notion-api, api, writing, notion] ---|-------| | Éléments de bloc maximum par payload | 1000 | | Taille maximale du payload | 500 KB | | Contenu texte enrichi | 2000 caractères | | URLs | 2000 caractères | | Équations | 1000 caractères | | Adresses e-mail | 200 caractères | | Numéros de téléphone | 200 caractères | | Options multi-sélection | 100 éléments | | Relations | 100 pages associées | | Mentions de personnes | 100 utilisateurs | | Tableaux de blocs par requête | 100 éléments |

Confirmation pour les opérations destructrices

IMPORTANT : Avant d'exécuter une opération qui modifie ou supprime des données, demandez la confirmation à l'utilisateur. Cela inclut :

  • La mise à jour de pages ou de blocs
  • La suppression/archivage de pages ou de blocs
  • La modification de schémas de base de données
  • La création de pages (si plusieurs ou en lot)
  • Toute opération en masse

Pour un groupe logique d'opérations connexes, une seule confirmation suffit.

Endpoints API principaux

Recherche

Rechercher dans toutes les pages et bases de données accessibles :

curl -s -X POST "https://api.notion.com/v1/search" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "search term",
    "filter": {"property": "object", "value": "page"},
    "sort": {"direction": "descending", "timestamp": "last_edited_time"},
    "page_size": 100
  }' | jq

Valeurs de filtre : "page" ou "data_source" (ou omettre pour les deux)

Pages

Récupérer une page

curl -s "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Remarque : Cela retourne les propriétés de la page, pas le contenu. Pour le contenu, utilisez « Récupérer les enfants de bloc » avec l'ID de la page.

Créer une page

curl -s -X POST "https://api.notion.com/v1/pages" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "properties": {
      "title": {
        "title": [{"text": {"content": "Page Title"}}]
      }
    },
    "children": [
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Paragraph content"}}]
        }
      }
    ]
  }' | jq

Options parent :

  • {"page_id": "..."} - Créer sous une page
  • {"database_id": "..."} - Créer dans une base de données (hérité)
  • {"data_source_id": "..."} - Créer dans une source de données (API v2025-09-03+)

Mettre à jour une page

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "title": {"title": [{"text": {"content": "Updated Title"}}]}
    },
    "icon": {"type": "emoji", "emoji": "📝"},
    "archived": false
  }' | jq

Options de mise à jour supplémentaires : cover, is_locked, in_trash

Archiver (supprimer) une page

curl -s -X PATCH "https://api.notion.com/v1/pages/{page_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}' | jq

Récupérer un élément de propriété de page

Pour les propriétés avec plus de 25 références :

curl -s "https://api.notion.com/v1/pages/{page_id}/properties/{property_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Blocs (contenu de page)

Récupérer les enfants de bloc

curl -s "https://api.notion.com/v1/blocks/{block_id}/children?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Utilisez l'ID de la page comme block_id pour obtenir le contenu de la page. Vérifiez has_children sur chaque bloc pour le contenu imbriqué.

Ajouter des enfants de bloc

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}/children" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "object": "block",
        "type": "heading_2",
        "heading_2": {
          "rich_text": [{"type": "text", "text": {"content": "New Section"}}]
        }
      },
      {
        "object": "block",
        "type": "paragraph",
        "paragraph": {
          "rich_text": [{"type": "text", "text": {"content": "Content here"}}]
        }
      }
    ]
  }' | jq

Maximum 100 blocs par requête, jusqu'à 2 niveaux d'imbrication.

Options de position dans le corps de la requête :

  • Défaut : ajoute à la fin
  • "position": {"type": "start"} - Insérer au début
  • "position": {"type": "after_block", "after_block": {"id": "block-id"}} - Insérer après un bloc spécifique

Récupérer un bloc

curl -s "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Mettre à jour un bloc

curl -s -X PATCH "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "paragraph": {
      "rich_text": [{"type": "text", "text": {"content": "Updated content"}}]
    }
  }' | jq

La mise à jour remplace la valeur entière du champ spécifié.

Supprimer un bloc

curl -s -X DELETE "https://api.notion.com/v1/blocks/{block_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Déplace le bloc à la corbeille (peut être restauré).

Bases de données

Récupérer une base de données

curl -s "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Retourne la structure de la base de données y compris les sources de données et les propriétés.

Interroger une base de données

curl -s -X POST "https://api.notion.com/v1/databases/{database_id}/query" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "property": "Status",
      "select": {"equals": "Done"}
    },
    "sorts": [
      {"property": "Created", "direction": "descending"}
    ],
    "page_size": 100
  }' | jq

Voir references/filters-and-sorts.md pour la documentation complète sur les filtres et les tris.

Créer une base de données

curl -s -X POST "https://api.notion.com/v1/databases" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "parent-page-id"},
    "title": [{"type": "text", "text": {"content": "My Database"}}],
    "is_inline": true,
    "initial_data_source": {
      "properties": {
        "Name": {"title": {}},
        "Status": {
          "select": {
            "options": [
              {"name": "To Do", "color": "red"},
              {"name": "In Progress", "color": "yellow"},
              {"name": "Done", "color": "green"}
            ]
          }
        },
        "Due Date": {"date": {}}
      }
    }
  }' | jq

Mettre à jour une base de données

curl -s -X PATCH "https://api.notion.com/v1/databases/{database_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "title": [{"text": {"content": "Updated Title"}}],
    "description": [{"text": {"content": "Database description"}}]
  }' | jq

Sources de données (API v2025-09-03+)

Les sources de données sont des tables individuelles dans une base de données. À partir de la version API 2025-09-03, les bases de données peuvent contenir plusieurs sources de données.

Créer une source de données

curl -s -X POST "https://api.notion.com/v1/data_sources" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"type": "database_id", "database_id": "database-id"},
    "title": [{"type": "text", "text": {"content": "New Data Source"}}],
    "properties": {
      "Name": {"title": {}},
      "Description": {"rich_text": {}}
    }
  }' | jq

Utilisateurs

Lister tous les utilisateurs

curl -s "https://api.notion.com/v1/users?page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Récupérer un utilisateur

curl -s "https://api.notion.com/v1/users/{user_id}" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Récupérer l'utilisateur bot (moi)

curl -s "https://api.notion.com/v1/users/me" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Commentaires

Récupérer les commentaires

curl -s "https://api.notion.com/v1/comments?block_id={block_id}&page_size=100" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" | jq

Utilisez un ID de page comme block_id pour les commentaires au niveau de la page.

Créer un commentaire

Sur une page :

curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": {"page_id": "page-id"},
    "rich_text": [{"type": "text", "text": {"content": "Comment content"}}]
  }' | jq

Répondre à une discussion :

curl -s -X POST "https://api.notion.com/v1/comments" \
  -H "Authorization: Bearer $NOTION_API_TOKEN" \
  -H "Notion-Version: 2025-09-03" \
  -H "Content-Type: application/json" \
  -d '{
    "discussion_id": "discussion-id",
    "rich_text": [{"type": "text", "text": {"content": "Reply content"}}]
  }' | jq

Remarque : L'API ne peut pas démarrer de nouveaux fils de discussion en ligne ou modifier/supprimer les commentaires existants.

Pagination

Les endpoints paginés retournent :

  • has_more : Booléen indiquant si d'autres résultats existent
  • next_cursor : Curseur pour la page suivante
  • results : Tableau d'éléments

Pour itérer sur tous les résultats :

  1. Effectuez la requête initiale (omettez start_cursor)
  2. Vérifiez has_more dans la réponse
  3. Si true, extrayez next_cursor et incluez-le comme start_cursor dans la requête suivante
  4. Répétez jusqu'à ce que has_more soit false

Exemple de requête avec curseur :

{
  "page_size": 100,
  "start_cursor": "v1%7C..."
}

Gestion des erreurs

Code HTTP Code Description
400 invalid_json Le corps de la requête n'est pas du JSON valide
400 invalid_request_url L'URL est malformée
400 invalid_request La requête n'est pas prise en charge
400 validation_error Le corps de la requête ne correspond pas au schéma attendu
400 missing_version En-tête Notion-Version manquant
401 unauthorized Jeton bearer invalide
403 restricted_resource Le jeton n'a pas les permissions nécessaires
404 object_not_found La ressource n'existe pas ou n'est pas partagée avec l'intégration
409 conflict_error Collision de données lors de la transaction
429 rate_limited Limite de débit dépassée (vérifiez l'en-tête Retry-After)
500 internal_server_error Erreur serveur inattendue
503 service_unavailable Notion indisponible ou délai d'attente de 60 s dépassé
503 database_connection_unavailable Base de données non réactive
504 gateway_timeout Délai d'attente de la requête dépassé

Bonnes pratiques

  1. Stocker les IDs : Quand vous créez des pages/bases de données, stockez les IDs retournés pour les mises à jour futures
  2. Utiliser les IDs de propriété : Référencez les propriétés par ID plutôt que par nom pour la stabilité
  3. Opérations en masse : Agrégez plusieurs petites opérations en moins de requêtes
  4. Respecter les limites de débit : Implémentez une backoff exponentielle pour les réponses 429
  5. Vérifier has_more : Gérez toujours la pagination pour les endpoints de liste
  6. Valider avant les mises à jour : Récupérez l'état actuel avant d'effectuer des mises à jour
  7. Utiliser des variables d'environnement : Ne codez jamais en dur les clés API
  8. Gérer les erreurs gracieusement : Vérifiez les codes de statut de réponse et les messages d'erreur
  9. Taille du schéma : Gardez les schémas de base de données sous 50 KB pour les performances optimales
  10. Limite des propriétés : Les propriétés avec >25 références de page nécessitent une récupération séparée

Références

Pour la documentation détaillée sur des sujets spécifiques, consultez :

  • references/block-types.md - Tous les types de blocs pris en charge et leurs structures
  • references/property-types.md - Types de propriétés de base de données et formats de valeur
  • references/filters-and-sorts.md - Syntaxe des filtres et tris de requête de base de données
  • references/rich-text.md - Structure d'objet de texte enrichi et annotations

Skills similaires

zoom-general
anthropics / knowledge-work-plugins

Classifier et chaîner les skills Zoom selon les signaux détectés dans une requête développeur.

19 276
cloudflare-email-service
cloudflare / skills

Envoyer et recevoir des emails transactionnels via la plateforme Cloudflare Workers.

1 718
neynar
bankrbot / skills

Interagir avec le protocole social Farcaster via l'API Neynar.

1 143
protocolsio-integration
mkurman / zorai

Gérer, partager et automatiser des protocoles scientifiques via l'API protocols.io.

309
notion-cli
makenotion / skills

Interagir avec l'API Notion via une interface en ligne de commande intuitive.

118