Centre d’aide

Gérez les articles du centre d’aide d’un projet et leurs catégories. Nécessite que le centre d’aide soit activé pour le projet — s’il est désactivé, tous les endpoints ci-dessous renvoient 404.

Le corps des articles est du Markdown, pas du HTML. Le portail les rend via une visionneuse qui n’évalue jamais le HTML brut : tout HTML que vous envoyez est donc affiché aux lecteurs comme du texte littéral.

GET/v1/articles

Parameter	Type	Description
`status`	`string`	Filtrer par statut : draft, published ou archived.
`category_id`	`string`	Uniquement les articles de cette catégorie.
`limit`	`integer`	Taille de page. 25 par défaut, 100 au maximum.
`offset`	`integer`	Nombre d'éléments à ignorer. 0 par défaut.

GET/v1/articles/search

Parameter	Type	Description
`q`required	`string`	Requête de recherche. Accepte les phrases entre guillemets, OR et la -négation.
`limit`	`integer`	Nombre de résultats. 25 par défaut, 100 au maximum.

GET/v1/articles/:id

POST/v1/articles

Parameter	Type	Description
`title`required	`string`	Jusqu'à 200 caractères.
`body`	`string`	Markdown. Jusqu'à 50 000 caractères.
`excerpt`	`string`	Résumé d'une ligne, jusqu'à 300 caractères. Dérivé du corps si omis.
`slug`	`string`	Segment d'URL, jusqu'à 80 caractères. Dérivé du titre si omis.
`category_id`	`string`	Catégorie sous laquelle classer l'article.

PATCH/v1/articles/:id

Parameter	Type	Description
`title`	`string`	Nouveau titre.
`body`	`string`	Nouveau corps en Markdown.
`excerpt`	`string`	Nouveau résumé ; null l'efface.
`slug`	`string`	Nouveau segment d'URL.
`category_id`	`string`	Nouvelle catégorie ; null retire le classement.
`status`	`string`	draft, published ou archived.

DELETE/v1/articles/:id

Les articles sont toujours créés en brouillon — publier est un PATCH distinct, pour que rien n’atteigne votre portail par accident. Créer un article exige un accès en écriture d’une formule payante, comme toute autre méthode modifiante ici.

Lister les articles


curl "https://api.supdesk.app/v1/articles?status=published&limit=10" \
  -H "Authorization: Bearer sd_live_..."


{
  "data": [
    {
      "id": "8f7a...",
      "title": "Comment réinitialiser mon mot de passe ?",
      "slug": "comment-reinitialiser-mon-mot-de-passe",
      "body": "Ouvrez **Réglages**, puis choisissez *Réinitialiser le mot de passe*.",
      "excerpt": "Ouvrez Réglages, puis choisissez Réinitialiser le mot de passe.",
      "status": "published",
      "category_id": "3c2b...",
      "published_at": "2026-07-01T09:12:00Z",
      "helpful_count": 12,
      "not_helpful_count": 1,
      "created_at": "2026-06-28T14:03:00Z",
      "updated_at": "2026-07-01T09:12:00Z"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "has_more": false }
}

Sans filtre, cela renvoie aussi les brouillons et les articles archivés, la modification la plus récente d’abord. Passez status=published pour ce que les clients voient réellement.

Rechercher des articles


curl "https://api.supdesk.app/v1/articles/search?q=réinitialiser+mot+de+passe&limit=5" \
  -H "Authorization: Bearer sd_live_..."


{
  "data": [
    {
      "id": "8f7a...",
      "title": "Comment réinitialiser mon mot de passe ?",
      "slug": "comment-reinitialiser-mon-mot-de-passe",
      "category_slug": "prise-en-main",
      "category_name": "Prise en main",
      "snippet": "Ouvrez Réglages, puis choisissez Réinitialiser le mot de passe.",
      "rank": 0.6079
    }
  ]
}

Recherche plein texte uniquement sur les articles publiés, classée par pertinence, avec un extrait en texte brut autour de la correspondance. Les titres pèsent plus que les résumés, et les résumés plus que le corps. Une requête vide ou impossible à analyser renvoie une liste vide plutôt qu’une erreur.

Récupérer un article


curl "https://api.supdesk.app/v1/articles/8f7a..." \
  -H "Authorization: Bearer sd_live_..."

Renvoie un article unique, dans la même forme que dans la liste, ou 404 si l’id est inconnu dans votre projet.

Créer un article


curl -X POST https://api.supdesk.app/v1/articles \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Comment réinitialiser mon mot de passe ?",
    "body": "Ouvrez **Réglages**, puis choisissez *Réinitialiser le mot de passe*.",
    "category_id": "3c2b..."
  }'


{
  "data": {
    "id": "8f7a...",
    "title": "Comment réinitialiser mon mot de passe ?",
    "slug": "comment-reinitialiser-mon-mot-de-passe",
    "body": "Ouvrez **Réglages**, puis choisissez *Réinitialiser le mot de passe*.",
    "excerpt": "Ouvrez Réglages, puis choisissez Réinitialiser le mot de passe.",
    "status": "draft",
    "category_id": "3c2b...",
    "published_at": null,
    "helpful_count": 0,
    "not_helpful_count": 0,
    "created_at": "2026-07-01T09:12:00Z",
    "updated_at": "2026-07-01T09:12:00Z"
  }
}

Renvoie 201. Sans slug, il est dérivé du titre, avec un suffixe -2, -3… si cette adresse est prise. Sans excerpt, il est dérivé du corps.

Votre formule plafonne le nombre d’articles qu’un projet peut conserver — Free 5, Pro 50, Team illimité. Au-delà, cela renvoie limit_reached (429). Les articles archivés ne comptent pas : en archiver un libère donc une place.

Mettre à jour un article


curl -X PATCH https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "published" }'

Seuls les champs envoyés sont écrits : un PATCH ne vide donc jamais un champ que vous avez omis. Passer status à published horodate published_at la première fois et le conserve ensuite — corriger une faute de frappe ne fait pas passer un vieil article pour un nouveau. Le passer à archived retire l’article sans le supprimer.

Désarchiver un article revérifie le plafond de la formule, et peut renvoyer limit_reached.

Supprimer un article


curl -X DELETE https://api.supdesk.app/v1/articles/8f7a... \
  -H "Authorization: Bearer sd_live_..."

Supprime définitivement l’article et le retour de ses lecteurs, et renvoie 204. Pour retirer un article tout en le conservant, passez plutôt son statut à archived.

Catégories

GET/v1/article-categories

Parameter	Type	Description
`limit`	`integer`	Taille de page. 25 par défaut, 100 au maximum.
`offset`	`integer`	Nombre d'éléments à ignorer. 0 par défaut.

GET/v1/article-categories/:id

POST/v1/article-categories

Parameter	Type	Description
`name`required	`string`	Jusqu'à 80 caractères.
`description`	`string`	Affichée sur le portail, jusqu'à 300 caractères.
`sort_order`	`integer`	Position d'affichage. 0 par défaut.

PATCH/v1/article-categories/:id

Parameter	Type	Description
`name`	`string`	Nouveau nom.
`description`	`string`	Nouvelle description ; null l'efface.
`sort_order`	`integer`	Nouvelle position d'affichage.

DELETE/v1/article-categories/:id


curl -X POST https://api.supdesk.app/v1/article-categories \
  -H "Authorization: Bearer sd_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Prise en main", "sort_order": 1 }'


{
  "data": {
    "id": "3c2b...",
    "name": "Prise en main",
    "slug": "prise-en-main",
    "description": null,
    "sort_order": 1,
    "created_at": "2026-07-01T09:12:00Z"
  }
}

Les catégories sont listées par sort_order, puis par nom. Les slugs sont dérivés du nom de la même façon que les slugs d’article sont dérivés du titre.

Supprimer une catégorie renvoie 204 et ne supprime pas ses articles — ils deviennent sans catégorie et restent accessibles par la recherche et depuis la page d’accueil du centre d’aide.

Erreurs

En plus des codes standard :

Code	Statut	Quand
`not_found`	404	Id inconnu — ou centre d’aide désactivé pour ce projet.
`forbidden`	403	Une écriture sur une formule sans accès en écriture à l’API.
`limit_reached`	429	Le quota d’articles de la formule est épuisé.