<aside> ❗ Astuce de Notion : Utilisez cette page comme exemple de la façon dont vous pouvez structurer votre guide de référence API et l’héberger sur Notion. La base de données Points de terminaison (endpoints) comprend également un modèle de point de terminaison pour une documentation supplémentaire.

</aside>

Général

Introduction

Ce guide de référence est votre point d’entrée pour comprendre l’API Notion.

<aside> ❗ Vous avez besoin d'un jeton d'intégration pour interagir avec l’API Notion. Vous pouvez trouver un jeton d’intégration après avoir créé une intégration sur la page des paramètres d’intégration. S’il s'agit de votre premier aperçu de l’API Notion, nous vous recommandons de commencer par le Guide de démarrage pour savoir comment créer une intégration.

</aside>

Conventions

L’URL de base pour envoyer toutes les requêtes API est https://api.notion.com. Le HTTPS est requis pour toutes les requêtes API.

L’API Notion suit les conventions RESTful lorsque cela est possible, la plupart des opérations étant effectuées via des requêtes GET, POST, PATCH et DELETE sur les ressources de page et de base de données. Les corps de requête et de réponse sont encodés au format JSON.

CONVENTIONS JSON

• Les ressources de niveau supérieur ont une propriété "objet". Cette propriété peut être utilisée pour déterminer le type de la ressource (par exemple base de données", "utilisateur", etc.).
• Les ressources de niveau supérieur sont adressables par une propriété "id" UUIDv4. Vous pouvez omettre les tirets de l’ID lorsque vous faites des demandes à l’API, par exemple lors de la copie de l’ID à partir d'une URL de Notion.
• Les noms de propriétés sont écrits en snake_case (pas camelCase ou kebab-case).
• Les valeurs temporelles (dates et datetimes) sont encodées dans des chaînes ISO 8601. Les datetimes incluront la valeur de l’heure (2020-08-12T02:12:33.231Z) tandis que les dates incluront uniquement la date (2020-08-12).
• L’API Notion ne prend pas en charge les chaînes vides. Pour effacer la valeur des propriétés de type chaînes de caractères (par exemple : pour un objet valeur de propriété avec un type url), utilisez une valeur null au lieu de "".

Exemples de code et SDKs

Des exemples de requêtes et de réponses sont affichés pour chaque point de terminaison. Les requêtes sont affichées à l’aide du SDK JavaScript Notion et de cURL. Vous pouvez copier-coller ces exemples, et les modifier pour les adapter à votre intégration.

Les SDKs Notion sont des projets open source que vous pouvez installer pour commencer rapidement votre projet. Vous pouvez également choisir un autre langage ou bibliothèque qui vous permet de faire des requêtes HTTP.

Pagination

Les points de terminaison qui renvoient des listes d’objets prennent en charge les demandes de pagination basées sur le curseur (cursor-based pagination). Par défaut, Notion renvoie dix éléments par appel API. Si le nombre d’éléments dans une réponse d'un point de terminaison de support dépasse la valeur par défaut, une intégration peut utiliser la pagination pour demander un ensemble spécifique de résultats et/ou pour limiter le nombre d'éléments renvoyés.

POINTS DE TERMINAISON PRIS EN CHARGE

RÉPONSES

Limites de requêtes

Pour garantir une expérience de développement cohérente pour tous les utilisateurs de l’API, l’API Notion est limitée en débit et des limites de taille de base s’appliquent aux paramètres de requêtes.

Limites de débit

Les requêtes qui ont été limitées en débit renverront un code d'erreur "rate_limited" (statut de réponse HTTP 429). La limite de débit pour les requêtes entrantes par intégration est en moyenne de trois demandes par seconde. Certaines rafales au-delà du débit moyen sont autorisées.

<aside> ❗ Les limites de débit peuvent changer

Nous prévoyons à l’avenir d’ajuster les limites tarifaires pour équilibrer la demande et la fiabilité. Nous pouvons également introduire des limites tarifaires distinctes pour les espaces de travail dans différents plans tarifaires.

</aside>

Limites de taille

Notion limite la taille de certains paramètres et le niveau de hiérarchie des pages enfant renvoyées dans les requêtes. Une requête qui dépasse l'une de ces limites renverra "validation_error" code d'erreur (état de réponse HTTP 400) et contiendra des détails plus spécifiques dans la propriété "message".

Codes de statut

Les codes de réponse HTTP sont utilisés pour indiquer les classes générales de réussite et d’erreur.

Code de réussite

Codes d’erreur

Les réponses d’erreur contiennent plus de détails sur l’erreur dans le corps de la réponse, dans les propriétés "code" et "message".

Gestion des versions

Nos versions d’API sont nommées d’après la date de publication de la version. Par exemple, notre dernière version est 2022-06-28.

Vous définissez la version en incluant un en-tête Notion-Version. La définition de l’en-tête Notion-Version est obligatoire.

curl <https://api.notion.com/v1/users/01da9b00-e400-4959-91ce-af55307647e5> \\
  -H "Authorization: Bearer secret_t1CdN9S8yicG5eWLUOfhcWaOscVnFXns"
  -H "Notion-Version: 2022-06-28"

Objets

Utilisateurs

Utilisation des objets « utilisateur » dans l’API

Les objets « utilisateur » apparaissent dans presque tous les objets renvoyés par l’API, y compris :

• L’objet bloc sous created_by et last_edited_by.
• L’objet page sous created_by et last_edited_by et dans les éléments de la propriété people.
• L’objet base de données sous created_by et last_edited_by.
• L’objet de texte riche, comme des mentions d’utilisateurs.
• L’objet propriété quand la propriété est de type people.

Les objets « utilisateur » contiennent toujours les clés object et id, comme décrit ci-dessous. Les autres propriétés peuvent apparaître si l’utilisateur est renvoyé dans un contexte de texte riche ou de propriété de page, et si le bot possède les autorisations requises pour accéder à ces propriétés. Pour en savoir plus sur les autorisations, consultez les guides Capacités et Autorisation.

Tous les utilisateurs

Ces champs sont partagés par tous les utilisateurs, y compris les personnes et les robots. Les champs marqués d'un * sont toujours présents.

Fichier

Les objets fichiers contiennent des données sur un fichier qui est téléchargé dans Notion, ou des données sur un fichier externe lié à Notion.

{
  "type": "file",
  "file": {
    "url": "<https://s3.us-west-2.amazonaws.com/secure.notion-static.com/7b8b0713-dbd4-4962-b38b-955b6c49a573/My_test_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20221024%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221024T205211Z&X-Amz-Expires=3600&X-Amz-Signature=208aa971577ff05e75e68354e8a9488697288ff3fb3879c2d599433a7625bf90&X-Amz-SignedHeaders=host&x-id=GetObject>",
    "expiry_time": "2022-10-24T22:49:22.765Z"
  }
}

Les types de blocs page, embed (intégration), image, video, file (fichier), pdf et bookmark (signet) contiennent tous des objets fichiers. Les valeurs des objets « page » de type icône et couverture contiennent également des objets de type fichier.

Chaque objet fichier contient les champs suivants :

Points de terminaison

Points de terminaison