Ferndesk

Créer, lire, rechercher, mettre à jour et gérer le cycle de vie (publier, dépublier, mettre à la corbeille, restaurer) des articles du centre d’aide.

Mettre à jour un article

Met à jour un article. Le comportement varie selon le champ :

  • Métadonnées et placement (slug, keywords, meta_description, og_image, collection, section, listed, noindex) s’appliquent immédiatement.
  • Modifications du contenu (title, body via content/markdown) sont mises en attente dans un brouillon ouvert appartenant à cette clé — elles ne sont pas publiées. La réponse contient published: false et un draft_id. Publiez séparément avec POST /articles/:id/publish.

Les articles externes gérés par des intégrations ne peuvent pas être mis à jour. Nécessite la portée content:write.

Portée requise : content:write

PATCH /articles/{id}

Mettre à jour un article

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

Résultat de la mise à jour de l’article.

Authorizations

  • Authorization string requis header

    Toutes les requêtes nécessitent un jeton Bearer dans l’en-tête Authorization. Les clés API sont préfixées par fdsk_ et doivent rester secrètes. Vous pouvez générer et gérer les clés depuis la page Developer settings.

    Les clés peuvent être limitées à n’importe quel sous-ensemble de ces portées (chaque endpoint indique la portée requise via x-required-scopes) :

    • content:read : Lire et rechercher les articles, collections, sections et traductions du centre d’aide
    • content:write : Créer et modifier des brouillons d’articles, des utilisateurs et des tâches ; déplacer des articles et des collections
    • content:publish : Publier, dépublier, restaurer et mettre à la corbeille du contenu (rendre les modifications visibles)
    • analytics:read : Lire les rapports, analyses et retours sur les articles du centre d’aide
    • conversations:read : Lire les conversations et transcriptions de l’assistant IA
    • webhooks:manage : Créer et gérer les abonnements aux webhooks sortants

    L’octroi de content:write ou content:publish implique content:read. Les clés créées avant la mise en place des portées ont des portées nulles = accès complet (mode hérité).

Path Parameters

  • id string requis

    ID de ressource de l’entité demandée. Exemple: art_01JXY9AZK4KV

Request Body

application/json
  • title string

    Titre mis à jour de l’article. Modification du contenu : mise en attente dans un brouillon ouvert, non publiée.

  • content any

    Corps mis à jour de l’article (JSON Tiptap). Modification du contenu : mise en attente dans un brouillon ouvert, non publiée. Mutuellement exclusif avec markdown.

  • markdown string

    Affectation de collection mise à jour (placement, appliquée immédiatement).

  • collectionId string | null

    Affectation de section mise à jour (placement, appliquée immédiatement).

  • sectionId string

    Mots-clés SEO mis à jour.

  • keywords string

    Méta-description SEO mise à jour.

  • metaDescription string

    URL de l’image Open Graph mise à jour.

  • ogImage string

    Visibilité dans les listes : everywhere (par défaut), unlisted (accessible uniquement par lien), hidden ou assistant_only.

  • listed string enum enum

    Indique si les moteurs de recherche doivent ignorer cet article. Allowed values: everywhere, unlisted, hidden, assistant_only.

  • noindex boolean

    Slug personnalisé mis à jour. S’il diffère du slug existant, le mode slug personnalisé est activé.

  • slug string

    Production

Response

application/json
  • id string

    Titre principal de l’article.

  • title string

    Slug d’URL de l’article.

  • slug string | null

    Contenu de l’article rendu au format HTML. Présent lorsque format=html (par défaut).

  • contentHtml string

    Contenu de l’article rendu au format Markdown. Présent lorsque format=markdown.

  • contentMarkdown string

    Document ProseMirror/Tiptap brut stocké. Présent lorsque format=json. Utilise le schéma ProseMirror de Ferndesk (nœuds personnalisés comme callout, steps, cards) et constitue la représentation sans perte.

  • contentJson any | null

    Charge utile du document JSON. Pour les articles, il s’agit généralement d’un objet de texte enrichi de type ProseMirror/Tiptap. Les valeurs src des nœuds d’image peuvent être des chemins d’assets Ferndesk, des URL d’images externes ou des valeurs data:image/...;base64,... ; les URL externes et les images base64 sont téléversées et réécrites en chemins d’assets Ferndesk lors de l’écriture.

  • url string (uri) | null

    ID de la section contenant l’article.

  • sectionId string | null

    ID de section Ferndesk (sect_...).

  • collectionId string | null

    ID de collection Ferndesk (col_...).

  • status string | null

    Horodatage de publication de l’article.

  • publishedAt string | null

    Horodatage ISO 8601 en UTC.

  • createdAt string

    Horodatage ISO 8601 en UTC.

  • updatedAt string

    Indique si la modification est visible. Les modifications du contenu sont mises en attente dans un brouillon ouvert (published: false) ; les modifications des métadonnées et du placement s’appliquent immédiatement.

  • published boolean

    Brouillon ouvert contenant les modifications de contenu mises en attente, le cas échéant.

  • draft_id string | null

    Note lisible par l’utilisateur concernant les modifications mises en attente ou appliquées.

  • message string

    Non autorisé