API JSON

Authentification

Générez une clé personnelle depuis Mon espace → Clés API et envoyez-la dans l’en-tête Authorization de chaque appel :

curl -H "Authorization: Bearer cpk_…" https://www.creationdeperso.com/api/v1/me

La clé porte les droits de votre compte : un joueur lit le catalogue et gère ses personnages, un MJ forge en plus des monstres et des objets et rédige ses campagnes et quêtes.

Droits d’une clé

Chaque clé porte une liste de droits choisie à sa création (et modifiable ensuite) : des entrées <code>famille.action</code>, ou une famille entière <code>famille.*</code>. Un droit ne dépasse jamais les rôles du compte : une clé avec <code>monsters.create</code> sur un compte sans rôle MJ reste refusée. <code>GET /me</code> renvoie les droits de la clé.

Un appel hors des droits de la clé répond <code>403 insufficient_scope</code> avec le droit manquant dans <code>requiredScope</code>.

Conventions

• Les éléments de catalogue sont désignés par leur slug (<code>key</code>), jamais par un identifiant numérique. Seuls les personnages, campagnes et quêtes, et les ressources que vous créez, portent un <code>id</code>.
• Une liste est enveloppée dans <code>{ items, total }</code> (paginée : <code>{ items, page, perPage, total }</code>, <code>perPage</code> ≤ 100).
• L’en-tête <code>Accept-Language</code> (fr par défaut, en, de, es) choisit la langue des noms du catalogue et des messages d’erreur.
• Chaque compte dispose de 1 000 appels par heure (en-têtes <code>X-RateLimit-*</code>).

Toute erreur répond avec une enveloppe unique :

{
  "error": {
    "code": "validation_failed",
    "message": "…",
    "violations": [ { "path": "hitPoints", "message": "…" } ]
  }
}

Les longueurs maximales et les bornes de chaque champ (maxLength, minimum, maximum) sont déclarées dans le schéma OpenAPI : ce sont les règles du site, un dépassement répond 422. Un corps relu par GET peut être renvoyé tel quel en PUT, ses champs en lecture seule inclus.

Lecture du catalogue

Commencez par lire le catalogue pour connaître les slugs à envoyer. Les tables « homebrew » (armes, armures, équipement, attaques, monstres) sont filtrées à ce que votre compte peut voir : contenu intégré, contenu public validé et vos propres créations (champ <code>origin</code>).

Forge : objets et monstres (MJ)

Mêmes règles que la forge du site : chaque création débite son coût en crédits (rien n’est écrit si le solde est insuffisant), le contenu naît privé et passe par la modération pour devenir public, le facteur de puissance d’un monstre ne peut pas descendre sous l’estimation de ses statistiques. Les modifications et suppressions sont gratuites.

curl -X POST -H "Authorization: Bearer cpk_…" -H "Content-Type: application/json" \
     -d '{"name":"Gobelin des cendres","challengeRating":"1/4","armorClass":15,"hitPoints":7,
          "abilities":{"str":8,"dex":14,"con":10,"int":10,"wis":8,"cha":8},
          "skills":{"stealth":2},"attacks":[{"weapon":"scimitar"}]}' \
     https://www.creationdeperso.com/api/v1/monsters

Campagnes et quêtes (MJ)

Le MJ est toujours le compte appelant. Les personnages sont désignés par leur <code>id</code> : un membre du groupe doit être public et réclamé, un PNJ lié doit être une de vos fiches, un invité doit être public, réclamé et hors du groupe. Une campagne ou une quête publique retouchée repasse en attente de validation.

Personnages

La création suit exactement les règles du formulaire du site : les six scores sont une permutation du tirage émis par le serveur (obtenu par l’endpoint de tirage, renvoyé sous la forme du jeton <code>abilityRollToken</code>, valable cinq minutes et consommé une seule fois), la lignée est requise quand l’espèce en a, la répartition d’historique doit être légale, les compétences, dons, sorts et équipement restent dans les budgets de niveau 1. Une règle enfreinte répond 422 avec le chemin du champ en cause.

Le document machine complet est servi en OpenAPI.