Ferndesk

Artikel

Artikel erstellen

Erstellt einen neuen Help-Center-Artikel als offenen Entwurf. Der Artikel ist erst live, wenn Sie ihn veröffentlichen (POST /articles/:id/publish), oder wenn Sie publish: true übergeben, um ihn in einem Aufruf zu veröffentlichen (Legacy-Verhalten).

Geben Sie den Inhalt entweder als content (Tiptap-JSON) oder als markdown an.

Erfordert den Bereich content:write. Ratenlimit: 60 Anfragen pro Stunde und API-Schlüssel.

Erforderlicher Bereich: content:write

POST /articles

Artikel erstellen

curl --request POST \
  --url 'https://api.ferndesk.com/v1/articles' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "key": "value"
}'
{
  "id": "<string>",
  "title": "<string>",
  "slug": "<string>",
  "contentHtml": "<string>",
  "contentMarkdown": "<string>",
  "contentJson": "<string>",
  "url": "<url>",
  "sectionId": "<string>",
  "collectionId": "<string>",
  "status": "<string>",
  "publishedAt": "<string>",
  "createdAt": "<string>"
}

Erstellter Artikel (Entwurf oder bei `publish=true` veröffentlicht)

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 Bereiche beschränkt werden (jeder Endpunkt listet den erforderlichen Bereich ü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, deren 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 Bereichszuordnung erstellte Schlüssel haben null Bereiche = vollständiger Zugriff (Legacy-Modus).

Request Body

application/json
  • title string erforderlich

    Artikeltitel.

  • content any

    Artikelinhalt als Tiptap-/ProseMirror-JSON-Dokument. Nicht zusammen mit markdown verwendbar.

  • markdown string

    Artikelinhalt als Markdown. Wird beim Schreiben in Rich Text umgewandelt. Nicht zusammen mit content verwendbar.

  • publish boolean default

    Wenn true, wird der Artikel unmittelbar nach der Erstellung veröffentlicht (Legacy-Verhalten in einem Aufruf). Standardmäßig false: Bei der Erstellung bleibt ein offener Entwurf zurück, den Sie separat veröffentlichen. Default: false.

  • sectionId string erforderlich

    Abschnitts-ID, in dem der Artikel erstellt werden soll.

  • collectionId string | null

    Optionale Sammlungs-ID zum Gruppieren dieses Artikels.

  • keywords string

    SEO-Schlüsselwörter.

  • metaDescription string

    SEO-Meta-Beschreibung.

  • ogImage string

    URL des Open-Graph-Bildes.

  • slug string

    Benutzerdefinierter URL-Slug. Durch die Angabe eines neuen Slugs wird automatisch der Modus für benutzerdefinierte Slugs aktiviert.

Response

application/json
  • 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) verwendet wird.

  • contentMarkdown string

    Als Markdown gerenderter Artikelinhalt. Vorhanden, wenn format=markdown verwendet wird.

  • contentJson any | null

    Unverarbeitetes gespeichertes ProseMirror-/Tiptap-Dokument. Vorhanden, wenn format=json verwendet wird. 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 Sammlungsgruppierungs-ID für den Artikel.

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

  • draft_id string | null

    Für diesen Artikel erstellter offener Entwurf oder null, wenn er mit publish: true erstellt wurde.