Ferndesk

Articles

Exporter les articles de manière incrémentielle

Flux de synchronisation de chaque article de votre centre d’aide, trié du plus ancien updated_at au plus récent et paginé par curseur.

Contrairement à GET /articles, ce flux constitue le contrat de miroir complet :

  • Il inclut tous les statuts — articles en brouillon, publiés, non publiés et mis à la corbeille — chacun portant son status actuel. Un article mis à la corbeille apparaît ici avec status: "trashed" afin qu’un miroir en aval puisse le supprimer. C’est intentionnel : les consommateurs voient les suppressions et les dépublications comme des transitions de statut plutôt que comme des lignes disparaissant silencieusement.
  • since (ISO 8601) est obligatoire lors de la première requête et limite le flux aux articles mis à jour à cette date ou ultérieurement.
  • Lors des pages suivantes, omettez since et transmettez le next_cursor de la réponse précédente comme start_cursor ; le curseur contient la position exacte (updated_at, id).
  • format=markdown renvoie contentMarkdown au lieu de contentHtml.

Nécessite le scope content:write (le flux inclut des statuts non publiés).

Scope requis : content:write

GET /articles/incremental

Exporter les articles de manière incrémentielle

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>"
}

Page d’articles incrémentiels paginée par curseur

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 scopes (chaque endpoint indique le scope requis 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 les brouillons d’articles, les utilisateurs et les 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

    Accorder content:write ou content:publish implique content:read. Les clés créées avant la mise en place des scopes ont des scopes null = accès complet (mode hérité).

Query Parameters

  • format string enum

    Format de rendu du contenu. html (par défaut) renvoie contentHtml ; markdown renvoie contentMarkdown ; json renvoie contentJson — le document ProseMirror/Tiptap brut stocké. Le JSON utilise le schéma ProseMirror de Ferndesk (nœuds personnalisés tels que callout, steps et cards) et constitue la représentation sans perte du corps de l’article. Exemple: markdown

  • page_size integer

    Nombre d’éléments à renvoyer par page (1-100). Exemple: 20

  • since string (date-time)

    Limite inférieure (inclusive) de l’horodatage ISO 8601 de updated_at. Obligatoire lors de la première requête ; omettez-la et transmettez start_cursor lors des pages suivantes. Exemple: 2026-01-15T18:25:43.511Z

  • start_cursor string

    Curseur de pagination opaque. Transmettez le next_cursor d’une réponse précédente pour récupérer la page suivante. Exemple: eyJ2IjoxLCJrIjpbIjIwMjYtMDEtMDEiLCJhcnRfMSJdfQ

Response

application/json
  • results[] object array

    Éléments de cette page. Données d’article renvoyées par les endpoints d’articles.

    + Show Child Attributes
    • id string

      ID d’article Ferndesk (art_...).

    • title string

      Titre principal de l’article.

    • slug string | null

      Slug d’URL de l’article.

    • contentHtml string

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

    • contentMarkdown string

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

    • contentJson any | null

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

    • url string (uri) | null

      URL publique canonique de cet article.

    • sectionId string | null

      ID de la section contenant l’article.

    • collectionId string | null

      ID de regroupement de collection facultatif pour l’article.

    • status string | null

      Statut de publication de l’article.

    • publishedAt string | null

      Horodatage de publication de l’article.

    • createdAt string

      Horodatage ISO 8601 en UTC.

    • updatedAt string

      Horodatage ISO 8601 en UTC.

  • has_more boolean

    Indique si d’autres éléments sont disponibles après cette page.

  • next_cursor string | null

    Curseur à transmettre comme start_cursor pour la page suivante, ou null sur la dernière page.