Uniquement lors d’une suppression. Préparez la suppression d’un article ou d’une collection dans une demande de revue avec redirect_to, et les lecteurs de l’ancienne URL y seront redirigés une fois la demande publiée.
Présentation de l’API
L’API REST Ferndesk permet à vos propres systèmes de lire et d’écrire dans votre centre d’aide, de travailler dans la boîte de réception Support, de consulter les rapports et de modifier les paramètres. Chaque requête est envoyée à https://api.ferndesk.com/v1 avec une clé API. La liste complète des endpoints, avec des exemples de requêtes et de réponses, se trouve dans la référence de l’API de cette section.
Effectuez votre première requête
Un propriétaire ou un administrateur crée une clé dans Settings > Workspace > Developers, voir Accorder l’accès à un développeur. Lister les articles nécessite le scope content:read.
curl "https://api.ferndesk.com/v1/articles?page_size=5" \
-H "Authorization: Bearer $FERNDESK_API_KEY"Les clés, les scopes et les codes d’erreur d’authentification se trouvent dans Authentification.
Ce que vous pouvez faire
Zone | Ressources |
|---|---|
Centre d’aide | Articles, brouillons, révisions, traductions, collections, sections, journaux des modifications, utilisateurs du centre d’aide, demandes de revue |
Fern | Tâches : en lancez une et lisez son résultat |
Support | Conversations, notes et réponses, clients, coéquipiers, étiquettes, réponses enregistrées, playbooks, boîtes de réception e-mail |
Rapports | Rapports du helpdesk et du centre d’aide, retours sur les articles, conversations de l’Assistant IA |
Paramètres | Lire et modifier les paramètres du centre d’aide, du widget, de l’agent IA et de la boîte de réception, inviter des coéquipiers |
Webhooks | Endpoints qui reçoivent des événements, voir Webhooks |
Rédiger le contenu d’un article
Envoyez le corps d’un article sous forme de markdown ou de content, le document JSON de l’éditeur, jamais les deux. Le HTML n’est pas accepté pour les écritures d’articles.
curl -X POST https://api.ferndesk.com/v1/articles \
-H "Authorization: Bearer $FERNDESK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title": "Export your invoices", "sectionId": "SECTION_ID", "markdown": "Go to **Billing** and choose **Export**."}'POST /articlescrée un brouillon. Passez"publish": truepour publier immédiatement, ce qui nécessite le scopecontent:publish.PATCH /articles/:idapplique à la fois les métadonnées et l’emplacement et enregistre les modifications du corps dans un brouillon. Publiez-le avecPOST /articles/:id/publish.Les images dans le corps sont téléversées pour vous, voir Téléversements d’images. Ce n’est pas le cas des fichiers : un bloc de fichier nécessite un chemin déjà hébergé par Ferndesk.
Pour lire un corps, passez ?format=html (la valeur par défaut), markdown ou json. La réponse contient contentHtml, contentMarkdown ou contentJson. Les types de blocs dans le JSON incluent paragraph, heading, image, callout, codeBlock, multiCode, steps, card, faq, table, file et videoEmbed. Lisez un article existant au format JSON pour voir la structure de chacun.
Listes et pagination
Les listes du centre d’aide prennent page_size (de 1 à 100, 20 par défaut) et start_cursor, et renvoient results, has_more et next_cursor. Les listes du helpdesk, des demandes de revue, des rapports et des paramètres prennent limit (de 1 à 100, 25 par défaut) et cursor, et renvoient data, has_more et next_cursor. Renvoyez le curseur sans le modifier, avec les mêmes filtres.
Limites de débit
Limite | Valeur |
|---|---|
Chaque clé | 1 000 requêtes par minute |
Chaque espace de travail, toutes les clés et les connexions MCP ensemble | 3 000 requêtes par minute |
| 60 par heure |
| 10 par heure |
| 300 par heure |
Les réponses incluent X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Au-delà de la limite, vous recevez une réponse 429 avec Retry-After en secondes.
Erreurs
Les endpoints du centre d’aide renvoient {"error": "message", "code": "code"}. Les endpoints du helpdesk, des demandes de revue, des rapports et des paramètres renvoient un objet error avec type, code, message et request_id, et acceptent un en-tête Idempotency-Key afin qu’une écriture relancée ne s’exécute qu’une seule fois. Ils acceptent des corps de requête jusqu’à 4 Mio.
Versions
Envoyez Ferndesk-Version: 2026-11-17 pour figer la version de l’API. C’est la seule version, donc c’est aussi la version par défaut. Chaque réponse inclut cet en-tête.
Puis-je ajouter des redirections via l’API ?
La clé d’un contributeur peut-elle publier ?
Non. Une clé agit comme le coéquipier qui l’a créée, donc la clé d’un contributeur enregistre les brouillons et un propriétaire ou un administrateur les publie.
Où se trouvent les endpoints de paramètres ?
GET /settings/{area} et PATCH /settings/{area} pour le centre d’aide, le widget, l’agent IA et la boîte de réception, ainsi que /playbooks, /labels, /saved_replies, /email_inboxes et /teammates/invites. Les modifications nécessitent la clé d’un propriétaire ou d’un administrateur avec settings:write, et l’invitation de coéquipiers nécessite team:write.