Gérez les redirections de pages avec l'API Notiondesk

Une redirection de page redirige les lecteurs qui ouvrent une ancienne URL de votre centre d'aide vers un article ou une collection. L'API Notiondesk vous permet de lister, créer, mettre à jour et supprimer des redirections de page. Vous pouvez ainsi importer des centaines d'anciennes URL après une migration au lieu de les ajouter une par une dans le tableau de bord. Les favoris, les liens partagés et les résultats des moteurs de recherche restent fonctionnels.

Pour gérer les redirections dans le tableau de bord, consultez la section « Comment gérer les redirections de page dans votre centre d’aide » .

La création et la mise à jour des redirections nécessitent un plan qui inclut les redirections de pages.

Redirections de la page de liste

Cette liste couvre toutes les langues, de la plus récente à la plus ancienne. Elle inclut les redirections que vous créez et celles que Notiondesk crée automatiquement après un changement de slug.

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

{
  "object": "list",
  "data": [
    {
      "id": "3f1c2a9e-8b7d-4c6e-9a5f-1e2d3c4b5a69",
      "locale": "en",
      "type": "article",
      "origin": "manual",
      "source_path": "/legacy/getting-started",
      "target_id": "1761580412",
      "target_title": "Getting started",
      "target_slug": "getting-started",
      "target_status": "published"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Remarque : Une redirection ne redirige les lecteurs que tant que la page cible est publiée. Une redirection vers un brouillon attend la publication de la page cible.

La liste ne contient que les 10 000 redirections les plus récentes. Si votre intégration supprime des redirections pendant l'affichage, veuillez recommencer à partir de la première page : une suppression décale l'ordre des éléments, la page suivante peut donc en ignorer un. Voir Pagination et requêtes API de version Notiondesk .

Créer une redirection de page

Tous les champs sont obligatoires :

curl -X POST "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f0d6b1e-create-getting-started" \
  -d '{"type": "article", "source_path": "/legacy/getting-started", "target_id": "1761580412", "locale": "en"}'

La route répond 201 Created avec la nouvelle redirection, dans les mêmes champs que la liste.

• Une autre redirection source_path utilise déjà les réponses 409 conflict_error, et le message nomme le chemin.

• Un target_id sans traduction dans locale répond 404 not_found, et le message nomme l'identifiant.

Envoyez une réponse Idempotency-Key à chaque création. Une nouvelle tentative avec la même clé et le même corps renvoie la même réponse 201 sans créer de seconde redirection. Voir Gestion des erreurs d'API, des limites de débit et des nouvelles tentatives Notiondesk .

Mettre à jour une redirection de page

N'indiquez que les champs à modifier. Les champs non renseignés conservent leur valeur actuelle.

Les champs respectent les règles de création. La route répond 200 OK avec la redirection mise à jour.

La redirection doit toujours pointer vers une cible existant dans son locale après la modification. Pour rediriger un article vers une collection, envoyez type et target_id ensemble.

Supprimer une redirection de page

La suppression est irréversible, le chemin d'accès nécessite donc deux protections :

curl -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects/3f1c2a9e-8b7d-4c6e-9a5f-1e2d3c4b5a69" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -d '{"source_path": "/legacy/start"}'

curl -i -X DELETE "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects/3f1c2a9e-8b7d-4c6e-9a5f-1e2d3c4b5a69" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'

• le champ d'application admin;

• le corps {"confirm": true}, avec le booléen JSON true.

La route renvoie 204 No Content. Les lecteurs qui ouvrent l'ancien chemin ne sont plus redirigés. Supprimer à nouveau la même redirection renvoie une erreur 404 not_found, sauf si vous réessayez avec la même Idempotency-Key.

Cette fonctionnalité est limitée aux clés créées par le propriétaire de l'espace de travail ou un administrateur. Un éditeur peut supprimer une redirection depuis le tableau de bord, mais pas à l'aide d'une clé API.admin

Redirections d'importation après une migration

Vous utilisez un autre outil de centre d'aide ? Associez chaque ancien chemin à son nouvel article, puis créez une redirection par ligne. Ce script lit un fichier CSV contenant les colonnes source_path,target_id,locale :

import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";

const siteId = "c74781f6-1aea-4e17-ab23-bbb8b4d174b6";
const rows = readFileSync("redirects.csv", "utf8").trim().split(/\r?\n/).slice(1);

for (const row of rows) {
  const [source_path, target_id, locale] = row.split(",");
  const idempotencyKey = createHash("sha256").update(`${source_path}|${target_id}|${locale}`).digest("hex");

  const response = await fetch(`https://api.notiondesk.so/sites/${siteId}/page-redirects`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
      "nd-version": "2026-10-16",
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify({ type: "article", source_path, target_id, locale }),
  });

  if (response.status === 429) {
    const seconds = Number(response.headers.get("Retry-After")) || 5;
    console.log(`Rate limited, waiting ${seconds}s`);
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
    rows.push(row);
    continue;
  }

  const result = await response.json();
  console.log(response.status, source_path, response.ok ? result.id : result.code);
}

• La clé est dérivée de la ligne ; exécuter le script deux fois ne produit donc rien en double. Une ligne corrigée reçoit une nouvelle clé.

• Un chemin qui possède déjà une redirection est consigné dans conflict_error. Mettez-le à jour ou laissez-le tel quel.

• Les écritures sont limitées à 20 requêtes par minute et par clé ; 500 redirections prennent donc environ 25 minutes. Le script attend lorsqu'il atteint cette limite, puis réessaie d'accéder à la ligne.

• Utilisez une clé avec les étendues read et write uniquement.

Erreurs

Consultez la section « Gérer les erreurs d’API Notiondesk, les limites de débit et les nouvelles tentatives » pour connaître l’enveloppe d’erreur et les autres codes.

Questions fréquentes

Et ensuite ?

• Automatisez les tâches courantes du centre d'assistance grâce à l'API Notiondesk

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

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