Requêtes API de pagination et de version Notiondesk

Chaque liste d'API Notiondesk utilise la même pagination par curseur, et chaque requête peut spécifier la version d'API utilisée pour votre intégration grâce à l'en-tête nd-version. Cet article explique le fonctionnement de la pagination de l'API Notiondesk, comment lire chaque page d'une liste, le fonctionnement du versionnage de l'API et les règles de nommage des champs et des paramètres.

Fonctionnement de la pagination de l'API Notiondesk

Chaque itinéraire de liste répond à la même enveloppe :

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Contrôlez la page avec deux paramètres de requête :

Les listes ne comportent ni numéros de page ni nombre total.

Lisez chaque page d'une liste

Répétez la requête avec cursor défini sur la valeur de next_cursor de la réponse précédente jusqu'à ce que has_more soit false.

La première page :

La page suivante, avec NEXT_CURSOR remplacé par l'URL encodée next_cursor de la première page :

La même boucle en JavaScript :

Et en Python :

Règles du curseur

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles?page_size=100" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles?page_size=100&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

async function listAll(path) {
  const items = [];
  let cursor = null;

  do {
    const url = new URL(`https://api.notiondesk.so${path}`);
    url.searchParams.set("page_size", "100");
    if (cursor) {
      url.searchParams.set("cursor", cursor);
    }

    const response = await fetch(url, {
      headers: {
        Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
        "nd-version": "2026-10-16",
      },
    });
    const page = await response.json();

    items.push(...page.data);
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);

  return items;
}

const articles = await listAll("/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles");

import os
import requests

def list_all(path):
    items, cursor = [], None
    while True:
        params = {"page_size": 100}
        if cursor:
            params["cursor"] = cursor
        page = requests.get(
            f"https://api.notiondesk.so{path}",
            params=params,
            headers={
                "Authorization": f"Bearer {os.environ['NOTIONDESK_API_KEY']}",
                "nd-version": "2026-10-16",
            },
        ).json()
        items.extend(page["data"])
        if not page["has_more"]:
            return items
        cursor = page["next_cursor"]

• Le curseur est opaque. Ne l'analysez pas et n'en créez pas vous-même. Renvoyez-le tel quel.

• Vous pouvez modifier page_size entre les pages. La page suivante commence là où la précédente s'est terminée.

• Le curseur indique une position, pas une image. L'ajout ou la suppression d'un élément pendant le défilement peut décaler les éléments suivants ; une page peut donc répéter ou ignorer un élément. Si votre intégration supprime des éléments pendant leur affichage, vous devrez recommencer à partir de la première page.

• Certaines listes s'arrêtent prématurément. La liste des modifications ne contient que les 1 000 entrées les plus récentes. Les redirections de pages et les commentaires ne contiennent que les 10 000 entrées les plus récentes. Au-delà de cette limite, has_more devient false.

• Certaines listes ne sont jamais paginées. Les thèmes et les intégrations renvoient toujours tout dans une seule réponse, avec has_more: false.

Un curseur malformé, ou un curseur qui pointe au-delà de la fin de la liste, répond 400 validation_error.

Version de votre intégration API Notiondesk

Envoyez l'en-tête facultatif nd-version pour spécifier la version du contrat sur laquelle votre intégration a été écrite :

nd-version: 2026-10-16

• Sans l'en-tête, la requête utilise la version actuelle.

• Chaque réponse indique la version qui y a répondu dans son propre en-tête nd-version.

• Une valeur inconnue répond 400 invalid_version.

Les nouvelles routes, les nouveaux paramètres optionnels et les nouveaux champs de réponse sont intégrés sans mise à jour de version. Votre intégration doit ignorer les champs qu'elle ne reconnaît pas ; ainsi, un nouveau champ ne risque pas de la perturber.

Remarque : Épinglez-le dans le code de production. Votre intégration conservera ainsi le comportement testé lors d’une modification de la réponse dans une version ultérieure.nd-version

Règles de dénomination

• Les noms de champs sont en snake_case dans les requêtes et les réponses : page_size, next_cursor, default_locale.

• Les paramètres de requête n'ont qu'une seule orthographe. ?page_size=10 fonctionne. ?pageSize=10 est rejeté comme paramètre inconnu avec le code d'erreur 400. validation_error.

• Les paramètres et champs de corps inconnus sont rejetés avec le code 400 validation_error, de sorte qu'une faute de frappe ne passe jamais inaperçue.

• L'API utilise ses propres noms. Un centre d'aide est un site, et une collection est un category. Les chemins d'accès ressemblent à /sites/{site_id}/categories.

• Les dates sont au format ISO 8601 , par exemple 2026-10-18T14:39:03+00:00.

Questions fréquentes

Et ensuite ?

• Gérer les erreurs, les limites de débit et les nouvelles tentatives de l'API Notiondesk

• Lisez les articles, les collections et les entrées du journal des modifications avec l'API Notiondesk

• Commencez à utiliser l'API REST Notiondesk