Seitenweiterleitungen mit der Notiondesk API verwalten

Eine Seitenweiterleitung leitet Leser, die einen alten Pfad in Ihrem Hilfecenter aufrufen, zu einem Artikel oder einer Sammlung. Mit der Notiondesk API können Sie Seitenweiterleitungen auflisten, erstellen, aktualisieren und löschen. So können Sie nach einer Migration Hunderte alter URLs importieren, anstatt sie einzeln im Dashboard hinzuzufügen. Lesezeichen, geteilte Links und Suchmaschinenergebnisse funktionieren weiterhin.

Informationen zur Verwaltung von Weiterleitungen im Dashboard finden Sie unter „So verwalten Sie Seitenweiterleitungen in Ihrem Hilfecenter“ .

Das Erstellen und Aktualisieren von Weiterleitungen erfordert einen Plan, der auch Seitenweiterleitungen beinhaltet.

Weiterleitungen auf der Listenseite

Die Liste umfasst alle Sprachen, die neuesten zuerst. Sie enthält sowohl die von Ihnen erstellten Weiterleitungen als auch diejenigen, die Notiondesk nach einer Slug-Änderung automatisch erstellt.

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
}

Hinweis: Eine Weiterleitung sendet Leser nur, solange das Ziel veröffentlicht ist. Eine Weiterleitung zu einem Entwurf wartet, bis Sie das Ziel veröffentlichen.

Die Liste umfasst maximal die 10.000 neuesten Weiterleitungen. Falls Ihre Integration Weiterleitungen während der Auflistung löscht, beginnen Sie anschließend wieder auf der ersten Seite: Durch das Löschen verschieben sich die nachfolgenden Einträge, sodass die nächste Seite einen Eintrag überspringen kann. Siehe Paginate und Versions-API-Anfragen .

Seitenweiterleitung erstellen

Alle Felder sind Pflichtfelder:

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"}'

Die Route antwortet 201 Created mit der neuen Umleitung in den gleichen Feldern wie die Liste.

• Ein anderer Redirect verwendet bereits die Antwort 409 conflict_error, und die Meldung nennt den Pfad.

• Ein target_id ohne Übersetzung in locale antwortet mit 404 not_found, und die Meldung nennt die ID.

Senden Sie bei jeder Erstellung eine Idempotency-Key-Nachricht. Ein erneuter Versuch mit demselben Schlüssel und Body beantwortet dieselbe 201-Nachricht, ohne eine zweite Weiterleitung zu erzeugen. Siehe „Behandlung von Notiondesk-API-Fehlern, Ratenbegrenzungen und Wiederholungsversuchen“ .

Seitenweiterleitung aktualisieren

Senden Sie nur die zu ändernden Felder. Alle ausgelassenen Felder behalten ihren aktuellen Wert.

Die Felder folgen den Erstellungsregeln. Die Route antwortet 200 OK mit der aktualisierten Weiterleitung.

Die Weiterleitung muss nach der Änderung weiterhin auf ein Ziel verweisen, das in locale vorhanden ist. Um eine Artikelweiterleitung auf eine Sammlung zu verweisen, senden Sie type und target_id zusammen.

Seitenweiterleitung löschen

Das Löschen kann nicht rückgängig gemacht werden, daher benötigt die Route zwei Sicherheitsvorkehrungen:

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}'

• der admin-Bereich;

• der Body {"confirm": true}, mit dem JSON-Booleschen Wert true.

Die Route antwortet mit 204 No Content. Leser, die den alten Pfad öffnen, werden nicht mehr weitergeleitet. Das erneute Löschen derselben Weiterleitung führt zu einem 404-Fehler not_found, es sei denn, Sie versuchen es erneut mit demselben Idempotency-Key.

Der Bereich funktioniert nur mit einem Schlüssel, der vom Workspace-Inhaber oder Administrator erstellt wurde. Ein Redakteur kann eine Weiterleitung im Dashboard löschen, jedoch nicht mit einem API-Schlüssel.admin

Importweiterleitungen nach einer Migration

Wechseln Sie von einem anderen Hilfecenter-Tool? Ordnen Sie jeden alten Pfad dem entsprechenden neuen Artikel zu und erstellen Sie dann für jede Zeile eine Weiterleitung. Dieses Skript liest eine CSV-Datei mit den Spalten 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);
}

• Der Schlüssel wird aus der Zeile abgeleitet, daher erzeugt die zweimalige Ausführung des Skripts nichts doppelt. Jede korrigierte Zeile erhält einen neuen Schlüssel.

• Ein Pfad, der bereits eine Umleitung enthält, protokolliert conflict_error. Aktualisieren Sie ihn stattdessen oder lassen Sie ihn unverändert.

• Schreibvorgänge sind auf 20 Anfragen pro Minute und Schlüssel begrenzt, daher dauern 500 Weiterleitungen etwa 25 Minuten. Das Skript wartet, bis die Ratenbegrenzung erreicht ist, und versucht dann, die Zeile erneut zu verarbeiten.

• Verwenden Sie ausschließlich einen Schlüssel mit den Bereichen read und write.

Fehler

Siehe Handle Notiondesk API errors, rate limits, and retries für den Fehlerumschlag und die anderen Codes.

Häufig gestellte Fragen

Was kommt als Nächstes?

• Automatisieren Sie häufige Aufgaben im Hilfecenter mit der Notiondesk API

• Lesen Sie Artikel, Sammlungen und Änderungsprotokolleinträge mit der Notiondesk API.

• Behandelt API-Fehler, Ratenbegrenzungen und Wiederholungsversuche der Klasse Notiondesk