Ferndesk

Artikel

Artikel suchen

Volltextsuche über Ihre veröffentlichten Help-Center-Artikel, nach Relevanz sortiert.

Die Suche ist nach Relevanz sortiert und nicht per Keyset paginiert: Es werden höchstens 100 Ergebnisse in Relevanzreihenfolge zurückgegeben. has_more zeigt an, dass das Maximum erreicht wurde; next_cursor ist immer null.

format=markdown gibt contentMarkdown anstelle von contentHtml zurück.

Erforderlicher Scope: content:read

GET /articles/search

Artikel suchen

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

Antwort der nach Relevanz sortierten Artikelsuche

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 Entwicklereinstellungen erstellen und verwalten.

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

    • content:read: Help-Center-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, die Veröffentlichung aufheben, wiederherstellen und in den Papierkorb verschieben (Änderungen live schalten)
    • analytics:read: Help-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 erstellte 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

    Maximale Anzahl der zurückzugebenden, nach Relevanz sortierten Ergebnisse (1–100). Beispiel: 20

  • query string erforderlich

    Freitext-Suchabfrage. Beispiel: authentication

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 des Artikels.

    • contentHtml string

      Als HTML dargestellter Artikelinhalt. Wird bei format=html (Standard) zurückgegeben.

    • contentMarkdown string

      Als Markdown dargestellter Artikelinhalt. Wird bei format=markdown zurückgegeben.

    • contentJson any | null

      Unverändertes gespeichertes ProseMirror/Tiptap-Dokument. Wird bei format=json zurückgegeben. Verwendet das ProseMirror-Schema von Ferndesk (benutzerdefinierte Knoten wie callout, steps und 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 übergeben wird, oder null auf der letzten Seite.