Ferndesk

Artikel

Artikel inkrementell exportieren

Ein Synchronisierungs-Feed mit jedem Artikel in Ihrem Hilfezentrum, sortiert nach updated_at aufsteigend und per Cursor paginiert.

Im Gegensatz zu GET /articles ist dieser Feed der vollständige Spiegelvertrag:

  • Er enthält jeden Status — draft, published, unpublished UND trashed articles werden angezeigt, jeweils mit ihrem aktuellen status. Ein trashed article erscheint hier mit status: "trashed", damit ein nachgelagerter Spiegel ihn löschen kann. Dies ist beabsichtigt: Verbraucher sehen Löschungen und Aufhebungen der Veröffentlichung als Statusübergänge, anstatt dass Zeilen stillschweigend verschwinden.
  • since (ISO 8601) ist bei der ersten Anfrage erforderlich und begrenzt den Feed auf Artikel, die zu diesem Zeitpunkt oder danach aktualisiert wurden.
  • Auf nachfolgenden Seiten since weglassen und den next_cursor aus der vorherigen Antwort als start_cursor übergeben; der Cursor enthält die exakte Position (updated_at, id).
  • format=markdown gibt contentMarkdown anstelle von contentHtml zurück.

Erfordert den Scope content:write (der Feed enthält nicht veröffentlichte Status).

Erforderlicher Scope: content:write

GET /articles/incremental

Artikel inkrementell exportieren

curl --request GET \
  --url 'https://api.ferndesk.com/v1/articles/incremental' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "results": [
    {
      "id": "<string>",
      "title": "<string>",
      "slug": "<string>",
      "contentHtml": "<string>",
      "contentMarkdown": "<string>",
      "contentJson": "<string>",
      "url": "<url>",
      "sectionId": "<string>",
      "collectionId": "<string>",
      "status": "<string>",
      "publishedAt": "<string>",
      "createdAt": "<string>"
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}

Inkrementelle Artikelseite mit Cursor-Paginierung

Authorizations

  • Authorization string erforderlich header

    Alle Anfragen erfordern ein Bearer-Token im Authorization-Header. API-Schlüssel tragen das Präfix fdsk_ und sollten geheim gehalten werden. Sie können Schlüssel über die Seite Developer settings erstellen und verwalten.

    Schlüssel können auf eine beliebige Teilmenge dieser Scopes beschränkt werden (jeder Endpunkt listet den erforderlichen Scope über x-required-scopes auf):

    • content:read: Hilfezentrum-Artikel, Sammlungen, Abschnitte und Übersetzungen lesen und durchsuchen
    • content:write: Artikelentwürfe, Benutzer und Aufgaben erstellen und bearbeiten; Artikel und Sammlungen verschieben
    • content:publish: Inhalte veröffentlichen, Veröffentlichung aufheben, wiederherstellen und löschen (Änderungen live schalten)
    • analytics:read: Berichte, Analysen und Artikel-Feedback des Hilfezentrums lesen
    • conversations:read: Unterhaltungen und Transkripte des KI-Assistenten lesen
    • webhooks:manage: Ausgehende Webhook-Abonnements erstellen und verwalten

    Die Vergabe von content:write oder content:publish beinhaltet content:read. Vor der Einführung von Scopes ausgestellte Schlüssel haben null Scopes = vollständiger Zugriff (Legacy-Modus).

Query Parameters

  • format string enum

    Format für die Inhaltsdarstellung. html (Standard) gibt contentHtml zurück; markdown gibt contentMarkdown zurück; json gibt contentJson zurück — das unveränderte gespeicherte ProseMirror/Tiptap-Dokument. Das JSON verwendet das ProseMirror-Schema von Ferndesk (benutzerdefinierte Knoten wie callout, steps und cards) und ist die verlustfreie Darstellung des Artikelinhalts. Beispiel: markdown

  • page_size integer

    Anzahl der pro Seite zurückzugebenden Elemente (1–100). Beispiel: 20

  • since string (date-time)

    Untere Grenze (einschließlich) des ISO-8601-Zeitstempels für updated_at. Bei der ersten Anfrage erforderlich; auf nachfolgenden Seiten weglassen und start_cursor übergeben. Beispiel: 2026-01-15T18:25:43.511Z

  • start_cursor string

    Undurchsichtiger Cursor für die Seitennavigation. Den next_cursor aus einer vorherigen Antwort übergeben, um die nächste Seite abzurufen. Beispiel: eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ

Response

application/json
  • results[] object array

    Elemente auf dieser Seite. Artikel-Payload, die von Artikel-Endpunkten zurückgegeben wird.

    + Show Child Attributes
    • id string

      Ferndesk-Artikel-ID (art_...).

    • title string

      Primärer Artikeltitel.

    • slug string | null

      URL-Slug für den Artikel.

    • contentHtml string

      Als HTML dargestellter Artikelinhalt. Vorhanden, wenn format=html (Standard).

    • contentMarkdown string

      Als Markdown dargestellter Artikelinhalt. Vorhanden, wenn format=markdown.

    • contentJson any | null

      Unverändertes gespeichertes ProseMirror/Tiptap-Dokument. Vorhanden, wenn format=json. Verwendet das ProseMirror-Schema von Ferndesk (benutzerdefinierte Knoten wie callout, steps, cards) und ist die verlustfreie Darstellung.

    • url string (uri) | null

      Kanonische öffentliche URL für diesen Artikel.

    • sectionId string | null

      Abschnitts-ID, die den Artikel enthält.

    • collectionId string | null

      Optionale ID der Sammlung, zu der der Artikel gruppiert ist.

    • status string | null

      Veröffentlichungsstatus des Artikels.

    • publishedAt string | null

      Zeitstempel der Veröffentlichung des Artikels.

    • createdAt string

      ISO-8601-Zeitstempel in UTC.

    • updatedAt string

      ISO-8601-Zeitstempel in UTC.

  • has_more boolean

    Gibt an, ob nach dieser Seite weitere Elemente verfügbar sind.

  • next_cursor string | null

    Cursor, der als start_cursor für die nächste Seite zu übergeben ist, oder null auf der letzten Seite.