TechArticle · REST v1

Documentation de l'API Foliade

API découverte : 5 conversions réussies sur 30 jours, une à la fois ; 50 Mo et 100 pages par PDF, 250 Mo de paquets API conservés.

Le MCP est inclus dès le gratuit. L’API complète, les statistiques, le dépôt en masse et les webhooks sont inclus dès Pro. L’export HTML autonome est inclus dès Business.

Ouvrir la référence interactive Télécharger OpenAPI

Authentification Bearer

Créez une clé dans Foliade → API, puis envoyez-la dans l'en-tête Authorization. La clé donne accès aux catalogues de son compte : conservez-la dans un gestionnaire de secrets et jamais dans le code source.

export FOLIADE_API_KEY="fl_live_your_key"
curl https://foliade.gekkode.com/v1/me \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}"

Cycle de vie d'une clé

créez une clé dédiée à chaque intégration ;
copiez sa valeur lors de sa création ;
surveillez son dernier appel ;
révoquez-la dès qu'elle n'est plus utilisée.

Une clé absente, inconnue ou révoquée reçoit une réponse 401.

Endpoints v1

Méthode	Chemin	Résultat
`POST`	`/v1/catalogs`	Convertit un PDF, en brouillon ou publié.
`POST`	`/v1/catalogs/bulk`	Accepte une source publique et démarre un lot.
`GET`	`/v1/catalogs`	Liste les catalogues du compte.
`GET`	`/v1/catalogs/{id}`	Retourne le catalogue et l'état de sa dernière conversion.
`POST`	`/v1/catalogs/{id}/publish`	Publie un brouillon existant sans reconversion ni changement de lien.
`GET`	`/v1/catalogs/{id}/stats?days=30`	Retourne lectures, lecteurs, contacts et pages vues.
`DELETE`	`/v1/catalogs/{id}`	Dépublie le catalogue sans effacer les données du compte.
`GET`	`/v1/me`	Vérifie la clé, l'offre et le nombre de catalogues.

Publier un PDF

Envoyez un corps multipart/form-data. Seul fichier est obligatoire. publier=0 crée un brouillon ; publier=1 rend le lien public. Avec attendre=1, la requête attend la conversion jusqu'à 300 secondes avant de rendre un 202.

curl -X POST https://foliade.gekkode.com/v1/catalogs \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}" \
  -F "[email protected];type=application/pdf" \
  -F "titre=Catalogue été 2026" \
  -F "langue=fr" \
  -F "publier=1" \
  -F "attendre=1"

Champ	Défaut	Description
`fichier`	—	API découverte : 50 Mo et 100 pages par PDF. API complète : 300 Mo par PDF.
`remplace`	—	Identifiant d'un catalogue du compte à remplacer, sans changer son lien ni sa protection. Une conversion réussie consomme une unité du quota découverte.
`titre`	nom du fichier	Titre visible du catalogue.
`langue`	langue du compte	Code de langue pris en charge par le lecteur.
`publier`	`0`	`1` pour ouvrir immédiatement le lien public.
`attendre`	`1`	`0` pour recevoir immédiatement un travail asynchrone.

{
  "id": "abc123",
  "url": "https://foliade.gekkode.com/c/abc123",
  "etat": "public",
  "pages": 24,
  "duree_s": 8.4,
  "texte_indexe": true
}

Traitement en masse

L'API complète est incluse dès Pro.

Le point d'entrée de masse reçoit une URL HTTP(S) publique dans un corps JSON. Le webhook est facultatif. La réponse 202 contient l'identifiant du lot accepté.

curl -X POST https://foliade.gekkode.com/v1/catalogs/bulk \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://exemple.fr/catalogues.zip",
    "webhook": "https://exemple.fr/webhooks/foliade"
  }'

La source est une archive ZIP de 2 Go maximum, avec au plus 500 PDF de 300 Mo chacun. Les notifications utilisent une file persistante : après un échec HTTP, cinq nouvelles tentatives sont prévues après 1 minute, 5 minutes, 15 minutes, 1 heure et 6 heures.

Chaque notification inclut un identifiant stable et une signature HMAC-SHA256. Récupérez le secret de signature de votre espace via l'API d'identité. Vérifiez la signature du corps HTTP brut, refusez les horodatages de plus de cinq minutes et dédupliquez les événements déjà traités. Une rotation de la clé de l'application renouvelle les secrets.

GET /v1/me → webhook_signing_secret
X-Foliade-Event-Id: event_id
X-Foliade-Signature: t=timestamp,v1=signature
signature = HMAC-SHA256(webhook_signing_secret, timestamp + "." + raw_body)

Statistiques

Les statistiques nécessitent Pro.

La période est transmise avec days. L'API REST et le serveur MCP hébergé acceptent un entier de 1 à 3650 jours. Les valeurs hors limites sont refusées.

curl "https://foliade.gekkode.com/v1/catalogs/abc123/stats?days=30" \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}"

Réponses et erreurs

Statut	Signification	Action
`201`	Conversion terminée.	Utilisez `url` et `id`.
`202`	Conversion ou lot accepté, encore en cours.	Conservez l'identifiant renvoyé.
`400`	La source de masse n'est pas une URL publique acceptée.	Fournissez une URL HTTP(S) accessible.
`401`	Clé absente, inconnue ou révoquée.	Vérifiez l'en-tête ou créez une clé.
`403`	Fonction réservée à une offre supérieure ou espace suspendu.	Vérifiez les droits du compte.
`404`	Catalogue absent du compte authentifié.	Vérifiez l'identifiant et la clé.
`409`	Conversion en cours, places occupées ou stockage plein.	Attendez ou libérez une place dans votre espace.
`413`	Le PDF dépasse la limite de taille ou de pages de votre offre.	Réduisez ou divisez le document.
`422`	PDF protégé, corrompu ou conversion en échec.	Réexportez un PDF lisible sans mot de passe.
`429`	Quota API ou limite de protection atteint.	Consultez vos quotas avant de réessayer.

Protection anti-abus : 60 appels API par minute et 10 tentatives de dépôt sur 24 heures, partagées avec le site et le MCP. Les échecs comptent dans cette limite quotidienne, pas dans le quota mensuel.

La suppression ou la dépublication ne rembourse pas une conversion réussie. Les 5 places de publication sont partagées avec les dépôts web. Les brouillons et archives API comptent dans les 5 catalogues API conservés et les 250 Mo de stockage.

Après une réponse 202, consultez le catalogue pour suivre la conversion. La réponse de l'identité du compte indique les quotas découverte restants ; le secret de webhook n'est fourni qu'aux offres Pro et supérieures.

API ou serveur MCP ?

L'API convient à une application, un backend ou une chaîne éditoriale. Le serveur MCP enveloppe les mêmes opérations avec des outils que Codex et Claude Code peuvent appeler sous le contrôle de l'utilisateur.

Comprendre la différence entre MCP et API

Référence exécutable

La documentation Swagger et le schéma OpenAPI sont générés depuis les routes réellement déployées.

Tester dans Swagger UI

Changelog

Version	Date	Changements
v1	28 août 2026	Documentation publique de la conversion, des lots, des statistiques, de la dépublication et de l'identité du compte.