JSON API

Authentication

Generate a personal key from My space → API keys and send it in the Authorization header of every call:

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

The key carries your account’s rights: a player reads the catalog and manages their characters, a DM additionally forges monsters and items and writes campaigns and quests.

Rights of a key

Each key carries a list of rights chosen at creation (and editable later): <code>family.action</code> entries, or a whole family <code>family.*</code>. A right never exceeds the account’s roles: a key with <code>monsters.create</code> on an account without the DM role is still refused. <code>GET /me</code> returns the key’s rights.

A call outside the key’s rights answers <code>403 insufficient_scope</code> with the missing right in <code>requiredScope</code>.

Conventions

• Catalog rows are designated by their slug (<code>key</code>), never by a numeric id. Only characters, campaigns and quests, and the resources you create, carry an <code>id</code>.
• A list is wrapped in <code>{ items, total }</code> (paginated: <code>{ items, page, perPage, total }</code>, <code>perPage</code> ≤ 100).
• The <code>Accept-Language</code> header (fr by default, en, de, es) selects the language of catalog names and error messages.
• Each account gets 1,000 calls per hour (<code>X-RateLimit-*</code> headers).

Every error answers with a single envelope:

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

Maximum lengths and bounds of every field (maxLength, minimum, maximum) are declared in the OpenAPI schema: they are the site’s own rules, exceeding one answers 422. A body read with GET can be sent back as is with PUT, read-only fields included.

Catalog reads

Start by reading the catalog to learn which slugs to send. Homebrew tables (weapons, armors, equipment, attacks, monsters) are scoped to what your account may see: built-in content, approved public content and your own creations (<code>origin</code> field).

Forge: items and monsters (DM)

Same rules as the site’s forge: every creation debits its cost in credits (nothing is written when the balance is insufficient), content is born private and goes through moderation to become public, a monster’s challenge rating cannot sit below the estimate of its stats. Edits and deletions are free.

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

Campaigns and quests (DM)

The DM is always the calling account. Characters are designated by <code>id</code>: a party member must be public and claimed, a bound NPC must be one of your sheets, a guest must be public, claimed and outside the party. An edited public campaign or quest goes back to pending approval.

Characters

Creation follows the site form's rules exactly: the six scores must be a permutation of the server-issued roll (obtained from the roll endpoint and handed back as the <code>abilityRollToken</code> ticket, valid five minutes and consumed once), a lineage is required when the species has some, the background allocation must be legal, and skills, feats, spells and gear stay within the level-1 budgets. A broken rule answers 422 with the path of the offending field.

The complete machine-readable document is served as OpenAPI.