Ferndesk

Artikel

Artikel auflisten

Gibt die Hilfe-Center-Artikel Ihrer Organisation zurück, neueste zuerst, mit Cursor-Paginierung.

  • status ist standardmäßig published. draft und all erfordern den Scope content:write; verworfene Artikel werden nie zurückgegeben.
  • collection_id filtert auf eine einzelne Collection.
  • updated_since (ISO 8601) gibt nur Artikel zurück, die zu diesem Zeitpunkt oder danach geändert wurden, nach ältester Änderung zuerst sortiert, für die inkrementelle Synchronisierung. Die Keyset-Sortierung ist in next_cursor enthalten. Auf nachfolgenden Seiten übergeben Sie daher nur start_cursor; updated_since wird ignoriert, wenn start_cursor vorhanden ist (der Cursor legt das Zeitfenster und seinen Modus bereits fest).
  • format=markdown gibt contentMarkdown statt contentHtml zurück.

Erforderlicher Scope: content:read

GET /articles

Artikel auflisten

curl --request GET \
  --url 'https://api.ferndesk.com/v1/articles' \
  --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>"
}

Cursor-paginierte Artikelantwort

Authorizations

  • Authorization string erforderlich header

    Alle Anfragen erfordern ein Bearer-Token im Authorization-Header. API-Schlüssel beginnen mit fdsk_ und sollten geheim gehalten werden. Sie können Schlüssel auf der Seite Developer settings erstellen und verwalten.

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

    • content:read: Hilfe-Center-Artikel, Collections, Abschnitte und Übersetzungen lesen und durchsuchen
    • content:write: Artikelentwürfe, Benutzer und Aufgaben erstellen und bearbeiten; Artikel und Collections verschieben
    • content:publish: Inhalte veröffentlichen, deren Veröffentlichung aufheben, wiederherstellen und verwerfen (Änderungen live schalten)
    • analytics:read: Hilfe-Center-Berichte, Analysen und Artikel-Feedback 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 schließt content:read ein. Vor der Einführung von Scopes ausgestellte Schlüssel haben null Scopes = vollständiger Zugriff (Legacy-Modus).

Query Parameters

  • collection_id string

    Nur Artikel aus dieser Collection zurückgeben. Beispiel: col_01JXYA6ABN52

  • format string enum

    Format der 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

  • start_cursor string

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

  • status string enum

    Nach Veröffentlichungsstatus filtern. Standardmäßig published. draft und all erfordern den Scope content:write und enthalten niemals verworfene Artikel. Beispiel: published

  • updated_since string (date-time)

    Nur Artikel zurückgeben, die zu diesem ISO-8601-Zeitstempel oder danach aktualisiert wurden. Für die inkrementelle Synchronisierung verwenden. Beispiel: 2026-01-15T18:25:43.511Z

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 gerenderter Artikelinhalt. Vorhanden, wenn format=html (Standard).

    • contentMarkdown string

      Als Markdown gerenderter 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 Collection, der der Artikel zugeordnet ist.

    • status string | null

      Veröffentlichungsstatus des Artikels.

    • publishedAt string | null

      Zeitstempel, zu dem der Artikel veröffentlicht wurde.

    • 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.