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": "…" } ]
  }
}

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 d’un tirage lié à une graine (obtenue par l’API), la lignée est obligatoire quand l’espèce en a, le bonus d’historique 2024 se répartit sur ses trois options, les compétences, l’expertise, les sorts et l’or de départ restent dans les budgets de niveau 1 de la classe. Le don d’origine et les tours de magie d’espèce sont accordés en plus.

Le document machine complet est servi en OpenAPI.