Easily generate D&D characters for your campaigns.

Introduction

I built this API because of my interest in Dungeons & Dragons. Using this API you can create and manage your characters, with the eventual goal to be able to play with those same characters.

The API is public, and free to use, and I will be expanding upon it to add new features, and improve upon the existing ones.

About the API

About the API

At the moment the API is still in its infancy, and I've only been developing it for a couple of months. So far, I've developed the following features that follow the original 5e ruleset:

  • Character creation letting you select class, race, background, stats, languages, and spells.
  • Name suggestions using a Markov chain to create names applicable to different races from human to angelic.
  • Dice rolling for any of the standard 6 D&D dice, allowing you to roll multiple different dice in one API call.
  • Random item generator, allowing you to pick the type and have a random item of that type returned. If you're lucky it might even be magic!
  • Encounter generator that can create a creature encounter applicable to the party and difficulty you specify.

Getting Started

Get started using Postman

To get started just create a user on the register endpoint. You can use any email you want, it's just for login purposes, not for spam!

You can import this Postman collection and begin using it right away.

Documentation

Users
  • POST /api/user/login

    Log in

    Params

    • email
    • password

    Response

    { "token": <JWT Token> }
  • GET /api/user

    Get user details

    Header Params

    • Authorization: Bearer <token>

    Response

    { "user": { "id": 1, "name": "test", "email": "user@example.com", "email_verified_at": null, "created_at": "2025-01-21T10:54:51.000000Z", "updated_at": "2025-01-21T10:54:51.000000Z" } }
  • POST /api/user/register

    Register user

    Params

    • name
    • email
    • password
    • password_confirmation

    Response

    { "user": { "id": 1, "name": "test", "email": "user@example.com", "created_at": "2025-01-21T10:54:51.000000Z", "updated_at": "2025-01-21T10:54:51.000000Z" }, "token": "<token>" }
  • POST /api/user/logout

    Log out

    Header Params

    • Authorization: Bearer <token>

    Response

    { "message": "Successfully logged out" }
  • DELETE /api/user

    Delete user

    Header Params

    • Authorization: Bearer <token>

    Response

    { "message": "Account successfully deleted. Sorry to see you go, good luck on your adventures." }
Characters
  • GET /api/characters

    Get characters list

    Header Params

    • Authorization: Bearer <token>
  • GET /api/characters/classes

    Get classes available for a character

    Header Params

    • Authorization: Bearer <token>
  • GET /api/characters/races

    Get races available for a character

    Header Params

    • Authorization: Bearer <token>
  • GET /api/characters/backgrounds

    Get backgrounds available for a character

    Header Params

    • Authorization: Bearer <token>
  • GET /api/characters/{guid}

    Get classes available for a character

    Header Params

    • Authorization: Bearer <token>

    Params

    • guid the guid for a character returned by the characters list endpoint.
  • GET /api/characters/{guid}/spells/available

    Get spells available for a character based on their class, race, and level

    Header Params

    • Authorization: Bearer <token>

    Params

    • guid the guid for a character returned by the characters list endpoint.
  • POST /api/characters/

    Create a new empty character

    Post body

    {"name":"Some heroic name","level":1}
  • PATCH /api/characters/{guid}

    Update a character with some partial creation details

    Header Params

    • Authorization: Bearer <token>

    Params

    • guid the guid for a character returned by the characters list endpoint.

    Post bodies

    # Update class {"updateType":"class", "charClassId":<class-id>} # Update class and class path {"updateType":"class", "charClassId":<class-id>, "classPathId":[<class-path-id>]} # Update background and background characteristics {"updateType":"background", "charBackgroundId":<background-id>, "characteristics":[<characteristic-ids>]} # Update race {"updateType":"race", "charRaceId":<race-id>} # Update abilities (requires dice rolls for each ability first # Abilities are in order 1-6, charisma, constitution, dexterity, # intelligence, strength, and wisdom {"updateType":"abilities", "abilityRolls": { {"abilityId": 1, "guid": <dice-roll-guid>}, {"abilityId": 2, "guid": <dice-roll-guid>}, {"abilityId": 3, "guid": <dice-roll-guid>}, {"abilityId": 4, "guid": <dice-roll-guid>}, {"abilityId": 5, "guid": <dice-roll-guid>}, {"abilityId": 6, "guid": <dice-roll-guid>}, } } # Update languages {"updateType":"languages", "languages": [<language-ids>]} # Update spells {"updateType":"spells", "spells": [<spell-ids>]}
Languages
  • GET /api/game/languages

    Get a list of all languages available for characters

    Header Params

    • Authorization: Bearer <token>
Names
  • GET /api/names

    Get some random generic generated names

    Header Params

    • Authorization: Bearer <token>

    Response

    { "style": "generic", "names": [ "Span aladran axos", "Ayeniaspavadralia", "Ivore", "Iuzan axos", "Llica", "Niazator" ] }
  • GET /api/names/{nameType}

    Get some random generic generated names

    Header Params

    • Authorization: Bearer <token>

    Params

    • nameType a racial type for the suggested names:
      • goblin
      • orc
      • ogre
      • dwarf
      • halfling
      • gnome
      • elf
      • fey
      • demon
      • angel
      • human
      • tiefling

    Response

    { "style": "generic", "names": [ "Span aladran axos", "Ayeniaspavadralia", "Ivore", "Iuzan axos", "Llica", "Niazator" ] }
Items
  • GET /api/game/items/{itemType}

    Get a list of all items by type

    Header Params

    • Authorization: Bearer <token>

    Params

    • itemType should be one of:
      • armor
      • book
      • clothing
      • food
      • other
      • pack
      • potion
      • projectile
      • weapon
      • gemstone
      • art object
  • GET /api/game/items/{itemType}/random

    Get a random item by type (can generate new items for some types, like books, armor, and weapons.

    Header Params

    • Authorization: Bearer <token>

    Params

    • itemType should be one of:
      • armor
      • book
      • clothing
      • food
      • other
      • potion
      • projectile
      • weapon
      • gemstone
      • art object
Spells
  • GET /api/game/spells/level/{level}

    Get all spells by spell level.

    Header Params

    • Authorization: Bearer <token>

    Params

    • level the spell level, 0 is for cantrips
  • GET /api/game/spells

    Get all spells.

    Header Params

    • Authorization: Bearer <token>
  • GET /api/game/spells/school/{school}

    Get all spells by spell school.

    Header Params

    • Authorization: Bearer <token>

    Params

    • school the spell school, one of:
      • abjuration
      • conjuration
      • divination
      • enchantment
      • evocation
      • illusion
      • necromancy
      • transmutation
  • GET /api/game/spells/class/{classId}

    Get all spells available for a specific class.

    Header Params

    • Authorization: Bearer <token>

    Params

    • classId the character class, such as 12 for wizard
  • GET /api/game/spells/class/{classId}/level/{level}

    Get all spells available for a specific class.

    Header Params

    • Authorization: Bearer <token>

    Params

    • classId the character class, such as 12 for wizard
    • level the spell level, 0 is for cantrips
  • GET /api/game/spells/school/{school}/level/{level}

    Get all spells by spell school.

    Header Params

    • Authorization: Bearer <token>

    Params

    • school the spell school, one of:
      • abjuration
      • conjuration
      • divination
      • enchantment
      • evocation
      • illusion
      • necromancy
      • transmutation
    • level the spell level, 0 is for cantrips
Creatures
  • GET /api/creatures/{creatureType}

    Get all creatures by type.

    Header Params

    • Authorization: Bearer <token>

    Params

    • creatureType the type of creature, one of:
      • aberration
      • beast
      • celestial
      • construct
      • demon
      • devil
      • dragon
      • elemental
      • fey
      • giant
      • humanoid
      • monstrosity
      • ooze
      • plant
      • undead
Dice
  • POST /api/game/dice

    Roll one or more dice of different types. Rolls are stored in the database against a guid which you can use later.

    Header Params

    • Authorization: Bearer <token>

    Post body

    { "dice":{ "d6":4, "d20":2 } }

    You can specify any of the standard D&D dice:

    • d4
    • d6
    • d8
    • d10
    • d12
    • d20

    Response

    { "rolls": { "d6": [ 1, 6, 4, 3 ], "d20": [ 17, 1 ] }, "guid": "<roll-guid>" }
Encounters
  • POST /api/encounters

    Creates an encounter appropriate for the party of characters and difficulty level

    Header Params

    • Authorization: Bearer <token>

    Post body

    { "characters": [<character-guids>], "difficulty": <1-4>, "environment": <environment> }

    Post body params:

    • difficulty 1 = easy, 2 = medium, 3 = hard, 4 = deadly
    • environment one of the following:
      • arctic
      • coast
      • desert
      • forest
      • grassland
      • hill
      • mountain
      • swamp
      • underdark
      • underwater
      • urban

Troubleshooting

If you run into trouble, please contact me by email and I will endeavour to respond as soon as I'm able. Over time I will populate this with recurring troubleshooting issues (those that can't be fixed).