Beheer pagina-omleidingen met de Notiondesk API

Een paginadirectie stuurt lezers die een oude pagina in uw helpcentrum openen, door naar een artikel of een verzameling. Met de Notiondesk API kunt u paginadirecties weergeven, aanmaken, bijwerken en verwijderen, zodat u na een migratie honderden oude URL's kunt importeren in plaats van ze één voor één in het dashboard toe te voegen. Bladwijzers, gedeelde links en zoekresultaten blijven gewoon werken.

Om omleidingen via het dashboard te beheren, raadpleegt u 'Paginaomleidingen beheren' in uw helpcentrum .

Het aanmaken en bijwerken van redirects vereist een plan dat ook pagina-redirects omvat.

Lijstpagina-omleidingen

De lijst omvat alle talen, van meest recent naar meest recent. Hij bevat zowel de redirects die u aanmaakt als de redirects die Notiondesk automatisch aanmaakt na een slugwijziging.

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
}

Let op: een redirect stuurt lezers alleen door zolang de beoogde pagina gepubliceerd is. Een redirect naar een conceptpagina wacht totdat je de beoogde pagina publiceert.

De lijst bevat maximaal de 10.000 nieuwste redirects. Als uw integratie redirects verwijdert terwijl ze worden weergegeven, begin dan daarna opnieuw vanaf de eerste pagina: een verwijdering verschuift de volgende items, waardoor de volgende pagina er één kan overslaan. Zie Paginate en versie Notiondesk API-verzoeken .

Maak een pagina-omleiding aan.

Elk veld is verplicht:

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

De route geeft als antwoord 201 Created de nieuwe redirect, in dezelfde velden als de lijst.

• Een andere redirect gebruikt al antwoorden 409, en het bericht noemt het pad.

• Een target_id zonder vertaling in locale beantwoordt met 404 not_found, en het bericht noemt de id.

Verzend een Idempotency-Key bij elke aanmaak. Een herhaalpoging met dezelfde sleutel en body levert dezelfde 201 op zonder een tweede redirect te genereren. Zie API-fouten, snelheidslimieten en herhaalpogingen afhandelen in de sectie 'API-fouten, snelheidslimieten en herhaalpogingen afhandelen' .

Een pagina-omleiding bijwerken

Stuur alleen de velden die u wilt wijzigen. Elk veld dat u niet invult, behoudt zijn huidige waarde.

De velden volgen de aanmaakregels. De route beantwoordt 200 OK met de bijgewerkte redirect.

De redirect moet na de wijziging nog steeds verwijzen naar een doel dat bestaat in de locale. Om een ​​artikelredirect naar een collectie te laten verwijzen, verstuur je type en target_id samen.

Een pagina-omleiding verwijderen

Verwijderen kan niet ongedaan worden gemaakt, dus de route heeft twee beveiligingsmaatregelen nodig:

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

• het admin bereik;

• de body {"confirm": true}, met de JSON-boolean true.

De route geeft als antwoord 204 No Content. Lezers die het oude pad openen, worden niet langer doorgestuurd. Het opnieuw verwijderen van dezelfde redirect geeft als antwoord 404 not_found, tenzij je het opnieuw probeert met dezelfde Idempotency-Key.

De scope werkt alleen op een sleutel die is aangemaakt door een workspace-eigenaar of beheerder. Een editor kan een redirect verwijderen via het dashboard, maar niet met een API-sleutel.admin

Importeer omleidingen na een migratie

Overgestapt van een andere helpcentrumtool? Koppel elk oud pad aan het nieuwe artikel en maak vervolgens één redirect per rij. Dit script leest een CSV-bestand met de kolommen 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);
}

• De sleutel wordt afgeleid van de rij, dus het script twee keer uitvoeren zorgt ervoor dat er niets dubbel wordt aangemaakt. Een rij die je corrigeert, krijgt een nieuwe sleutel.

• Een pad dat al een omleiding heeft, registreert conflict_error. Werk het in plaats daarvan bij, of laat het zo.

• Het aantal schrijfbewerkingen is beperkt tot 20 per minuut per sleutel, dus 500 omleidingen duren ongeveer 25 minuten. Het script wacht wanneer de limiet is bereikt en probeert de rij vervolgens opnieuw te verwerken.

• Gebruik alleen een sleutel met de bereiken read en write.

Fouten

Zie 'API-fouten, snelheidslimieten en herhaalpogingen afhandelen' voor de foutomvang en de andere codes.

Veelgestelde vragen

Wat volgt?

• Automatiseer veelvoorkomende helpcentrumtaken met de Notiondesk API

• Lees artikelen, collecties en wijzigingslogboeken met de Notiondesk API

• Verwerk API-fouten, snelheidslimieten en herhaalpogingen voor Notiondesk.