Comment obtenir une clé ?

Le titulaire du compte la crée dans l'application : Compte, onglet Clés d'API. Elle s'affiche une seule fois à la création et n'est stockée nulle part en clair. Elle se révoque depuis le même onglet, et l'accès tombe au premier appel suivant.

Quels comptes peuvent appeler l'API ?

Ceux du tiers Pro et au-delà, ainsi que les membres d'une équipe. Le contrôle a lieu à chaque appel, pas seulement à la création de la clé : si l'abonnement redescend, l'API répond plan_required (403) jusqu'au retour à un plan éligible.

Que coûte une analyse lancée par l'API ?

Le même nombre de crédits que la même analyse lancée depuis l'application, de 200 à 600 selon le format. Le champ credits_charged de la réponse fait foi. Un échec est remboursé automatiquement, au lancement comme en cours d'analyse.

Y a-t-il des webhooks ?

Pas en version 1 : il faut interroger GET /analyses/{id} jusqu'au statut completed ou failed. Les notifications sont le chantier suivant. En revanche, le dépôt de document existe déjà (POST /analyses).

Quelle est la limite de débit ?

120 requêtes par minute et par clé. Au-delà, l'API répond rate_limited (429).

Paple Connect

Paple Connect · référence v1

Documentation développeur.

Cette page s'adresse à une équipe technique. Si vous cherchez plutôt ce que Paple Connect change dans votre façon de travailler, ou si vous préférez qu'on prenne la connexion en charge, la présentation de Paple Connect est ici.

· REST et JSON· Sept routes· 120 requêtes/min par clé· Accès dès le tiers Pro

Authentification

Une clé Bearer, et c'est tout.

La clé se crée dans l'application (Compte, onglet Clés d'API) et ne s'affiche qu'une fois : seul son hachage est conservé. Elle porte le compte qui l'a créée, voit ses projets et ceux de son équipe le cas échéant, et dépense ses crédits. Une clé révoquée est refusée au premier appel suivant.

Lister les projets

curl "https://api.paplestory.com/functions/v1/api-v1/v1/projects?limit=20" \
  -H "Authorization: Bearer pk_live_votre_cle"

Lancer une analyse sur un projet

curl -X POST "https://api.paplestory.com/functions/v1/api-v1/v1/projects/{id}/analyses" \
  -H "Authorization: Bearer pk_live_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{"persona":"producteur"}'

# 202 Accepted
{ "id": "…", "project_id": "…", "status": "queued",
  "persona": "producteur", "credits_charged": 300 }

L'analyse part en tâche de fond. Interroger ensuite GET /analyses/{id} jusqu'à ce que le statut passe à completed : le champ resultporte alors l'analyse complète.

Routes

Sept routes, toutes en JSON.

L'adresse de base est https://api.paplestory.com/functions/v1/api-v1/v1. Chaque requête porte l'en-tête Authorization: Bearer pk_live_…. La limite est de 120 requêtes par minute et par clé.

Méthode	Chemin	Ce qu'elle rend
POST	/analyses	Dépose un document (multipart) et lance son analyse. Crée le projet.
GET	/projects	La liste des projets, paginée (limite 100, 50 par défaut).
GET	/projects/{id}	Un projet et son analyse la plus récente.
GET	/projects/{id}/characters	Le dépouillement des personnages de la dernière version analysée.
POST	/projects/{id}/analyses	Lance une analyse sur un projet existant. Corps : persona, version_id, analyze_characters.
GET	/analyses/{id}	Statut de l'analyse, puis son résultat complet.
GET	/credits	Le solde de crédits du compte porteur de la clé.

Personas

Le paramètre persona choisit le regard porté sur le texte. La liste dépend du type de projet, et une valeur hors liste est refusée (invalid_request) plutôt que repliée sur un défaut silencieux.

roman : neutre (lecture littéraire) ou adaptation(potentiel d'adaptation).
tous les autres types : neutre, auteur ou producteur.
Paramètre absent : neutre.

Statuts d'analyse

queued: En attente de départ. C'est aussi l'état d'une version jamais analysée.
processing: En cours. Interroger de nouveau, compter quelques minutes.
completed: Terminée. Le champ result porte l'analyse complète.
failed: Échouée. Le champ error_type dit pourquoi, et les crédits sont rendus.

Crédits

Débit au lancement, remboursement sur échec.

Une analyse débite le compte au lancement, et le champ credits_chargedde la réponse fait foi. Le montant dépend du type de projet, de 200 à 600 crédits. Un échec est remboursé automatiquement, au lancement comme en cours d'analyse : credits_consumed vaut false sur une analyse failed. GET /creditsrend la même poche que celle que le débit touchera : le compte, ou le pool de l'équipe avec son plafond mensuel par membre.

Une seule analyse tourne à la fois par projet : la suivante reçoit analysis_in_progress (409). Deux POSTsimultanés sur la même version n'en lancent qu'une et ne débitent qu'une fois.

Erreurs

Un code stable, un message qui bouge.

Toute erreur revient sous la même forme. Router sur code, jamais sur message : le premier est un contrat, le second peut être reformulé.

{ "error": { "code": "insufficient_credits", "message": "…" } }

Code	HTTP	Quand
unauthorized	401	Clé absente, mal formée ou inconnue.
revoked_key	401	La clé a été révoquée dans l'application.
plan_required	403	Le compte porteur n'est plus sur un plan éligible.
read_only_access	403	Projet visible mais rôle en lecture seule : lancement refusé.
invalid_request	400	Paramètre manquant ou hors des valeurs admises.
unsupported_file_type	415	Document déposé dans un format non pris en charge.
file_too_large	413	Document déposé au-delà de 30 Mo.
insufficient_credits	402	Solde insuffisant pour lancer l'analyse.
not_found	404	Identifiant inconnu, ou hors de la portée de la clé.
analysis_in_progress	409	Une analyse tourne déjà sur ce projet.
rate_limited	429	Plus de 120 requêtes sur la minute écoulée.
internal_error	500	Incident côté serveur. Réessayer, puis nous écrire.

Un identifiant hors de la portée de la clé rend not_found, jamais 403 : rien ne fuit sur ce qui existe ailleurs. La pagination passe par un curseur opaque. Tant que has_more vaut true, rappeler la route avec cursor=next_cursor, sans jamais fabriquer un curseur soi-même : sa forme est interne et peut changer.

Limites de la version 1

Deux façons de lancer une analyse : déposer un document (POST /analyses, qui crée le projet) ou la lancer sur un projet déjà présent dans Paple Story. Le dépôt crée toujours un projet neuf : pas d'ajout de version à un projet existant. Pas de webhook : il faut interroger GET /analyses/{id}. Pas d'écriture au-delà du lancement : ni projet, ni personnage, ni tâche ne se modifie par l'API.

Les champs de premier niveau d'une analyse sont structurés et se filtrent ; l'objet prose contient du texte long, à lire et non à trier. genres, main_themes et secondary_themessortent tels que l'analyse les produit, en texte libre souvent composé : c'est au consommateur de les normaliser vers son propre vocabulaire.

Questions fréquentes.

Comment obtenir une clé ?: Le titulaire du compte la crée dans l'application : Compte, onglet Clés d'API. Elle s'affiche une seule fois à la création et n'est stockée nulle part en clair. Elle se révoque depuis le même onglet, et l'accès tombe au premier appel suivant.
Quelle est la portée d'une clé ?: Une clé porte le compte qui l'a créée : elle voit ses projets, plus ceux de son équipe le cas échéant, et dépense ses crédits. Un identifiant hors de cette portée rend not_found, jamais 403.
Quels comptes peuvent appeler l'API ?: Ceux du tiers Pro et au-delà, ainsi que les membres d'une équipe. Le contrôle a lieu à chaque appel, pas seulement à la création de la clé : si l'abonnement redescend, l'API répond plan_required (403) jusqu'au retour à un plan éligible.
Que coûte une analyse lancée par l'API ?: Le même nombre de crédits que la même analyse lancée depuis l'application, de 200 à 600 selon le format. Le champ credits_charged de la réponse fait foi. Un échec est remboursé automatiquement, au lancement comme en cours d'analyse.
Y a-t-il des webhooks ?: Pas en version 1 : il faut interroger GET /analyses/{id} jusqu'au statut completed ou failed. Les notifications sont le chantier suivant. En revanche, le dépôt de document existe déjà (POST /analyses).
Quelle est la limite de débit ?: 120 requêtes par minute et par clé. Au-delà, l'API répond rate_limited (429).

Une question d'intégration précise ? info@paplestory.com. Le pas-à-pas pour créer une clé est dans le centre d'aide.

Une clé, et vous êtes parti.

Paple Connect est incluse à partir de Paple Pro. La clé se crée dans l’onglet Clés d’API du compte. Et si personne chez vous ne veut s’en occuper, on prend la connexion en charge.

Créer une clé Nous écrire