D&D 5e API

These details have not been verified by PyPI

Project links

GitHub Statistics

View statistics for this project via Libraries.io, or by using our public dataset on Google BigQuery

Project description

openapi-client

Introduction

Welcome to the dnd5eapi, the Dungeons & Dragons 5th Edition API! This documentation should help you familiarize yourself with the resources available and how to consume them with HTTP requests. Read through the getting started section before you dive in. Most of your problems should be solved just by reading through it.

Getting Started

Let's make our first API request to the D&D 5th Edition API!

Open up a terminal and use curl or httpie to make an API request for a resource. You can also scroll through the definitions below and send requests directly from the endpoint documentation!

For example, if you paste and run this curl command:

curl -X GET \"https://www.dnd5eapi.co/api/ability-scores/cha\" -H \"Accept: application/json\"

We should see a result containing details about the Charisma ability score:

{
  \"index\": \"cha\",
  \"name\": \"CHA\",
  \"full_name\": \"Charisma\",
  \"desc\": [
    \"Charisma measures your ability to interact effectively with others. It
      includes such factors as confidence and eloquence, and it can represent
      a charming or commanding personality.\",
    \"A Charisma check might arise when you try to influence or entertain
      others, when you try to make an impression or tell a convincing lie,
      or when you are navigating a tricky social situation. The Deception,
      Intimidation, Performance, and Persuasion skills reflect aptitude in
      certain kinds of Charisma checks.\"
  ],
  \"skills\": [
    {
      \"name\": \"Deception\",
      \"index\": \"deception\",
      \"url\": \"/api/skills/deception\"
    },
    {
      \"name\": \"Intimidation\",
      \"index\": \"intimidation\",
      \"url\": \"/api/skills/intimidation\"
    },
    {
      \"name\": \"Performance\",
      \"index\": \"performance\",
      \"url\": \"/api/skills/performance\"
    },
    {
      \"name\": \"Persuasion\",
      \"index\": \"persuasion\",
      \"url\": \"/api/skills/persuasion\"
    }
  ],
  \"url\": \"/api/ability-scores/cha\"
}

Authentication

The dnd5eapi is a completely open API. No authentication is required to query and get data. This also means that we've limited what you can do to just GET-ing the data. If you find a mistake in the data, feel free to message us.

GraphQL

This API supports GraphQL. The GraphQL URL for this API is https://www.dnd5eapi.co/graphql. Most of your questions regarding the GraphQL schema can be answered by querying the endpoint with the Apollo sandbox explorer.

Schemas

Definitions of all schemas will be accessible in a future update. Two of the most common schemas are described here.

`APIReference`

Represents a minimal representation of a resource. The detailed representation of the referenced resource can be retrieved by making a request to the referenced URL.

APIReference {
  index     string
  name      string
  url       string
}

`DC`

Represents a difficulty check.

DC {
  dc_type       APIReference
  dc_value      number
  success_type  \"none\" | \"half\" | \"other\"
}

`Damage`

Represents damage.

Damage {
  damage_type     APIReference
  damage_dice     string
}

`Choice`

Represents a choice made by a player. Commonly seen related to decisions made during character creation or combat (e.g.: the description of the cleric class, under Proficiencies, states "Skills: Choose two from History, Insight, Medicine, Persuasion, and Religion" [SRD p15])

Choice {
  desc      string
  choose    number
  type      string
  from      OptionSet
}

`OptionSet`

The OptionSet structure provides the options to be chosen from, or sufficient data to fetch and interpret the options. All OptionSets have an option_set_type attribute that indicates the structure of the object that contains the options. The possible values are options_array, equipment_category, and reference_list. Other attributes on the OptionSet depend on the value of this attribute.

options_array
- options (array): An array of Option objects. Each item in the array represents an option that can be chosen.
equipment_category
- equipment_category (APIReference): A reference to an EquipmentCategory. Each item in the EquipmentCategory's equipment array represents one option that can be chosen.
resource_list
- resource_list_url (string): A reference (by URL) to a collection in the database. The URL may include query parameters. Each item in the resulting ResourceList's results array represents one option that can be chosen.

`Option`

When the options are given in an options_array, each item in the array inherits from the Option structure. All Options have an option_type attribute that indicates the structure of the option. The value of this attribute indicates how the option should be handled, and each type has different attributes. The possible values and their corresponding attributes are listed below.

reference - A terminal option. Contains a reference to a Document that can be added to the list of options chosen.
- item (APIReference): A reference to the chosen item.
action - A terminal option. Contains information describing an action, for use within Multiattack actions.
- action_name (string): The name of the action, according to its name attribute.
- count (number | string): The number of times this action can be repeated if this option is chosen.
- type (string = \"melee\" | \"ranged\" | \"ability\" | \"magic\", optional): For attack actions that can be either melee, ranged, abilities, or magic.
multiple - When this option is chosen, all of its child options are chosen, and must be resolved the same way as a normal option.
- items (array): An array of Option objects. All of them must be taken if the option is chosen.
choice - A nested choice. If this option is chosen, the Choice structure contained within must be resolved like a normal Choice structure, and the results are the chosen options.
- choice (Choice): The Choice to resolve.
string - A terminal option. Contains a reference to a string.
- string (string): The string.
ideal - A terminal option. Contains information about an ideal.
- desc (string): A description of the ideal.
- alignments (ApiReference[]): A list of alignments of those who might follow the ideal.
counted_reference - A terminal option. Contains a reference to something else in the API along with a count.
- count (number): Count.
- of (ApiReference): Thing being referenced.
score_prerequisite - A terminal option. Contains a reference to an ability score and a minimum score.
- ability_score (ApiReference): Ability score being referenced.
- minimum_score (number): The minimum score required to satisfy the prerequisite.
ability_bonus - A terminal option. Contains a reference to an ability score and a bonus
- ability_score (ApiReference): Ability score being referenced
- bonus (number): The bonus being applied to the ability score
breath - A terminal option: Contains a reference to information about a breath attack.
- name (string): Name of the breath.
- dc (DC): Difficulty check of the breath attack.
- damage ([Damage]): Damage dealt by the breath attack, if any.
damage - A terminal option. Contains information about damage.
- damage_type (ApiReference): Reference to type of damage.
- damage_dice (string): Damage expressed in dice (e.g. "13d6").
- notes (string): Information regarding the damage.

FAQ

What is the SRD?

The SRD, or Systems Reference Document, contains guidelines for publishing content under the OGL. This allows for some of the data for D&D 5e to be open source. The API only covers data that can be found in the SRD. Here's a link to the full text of the SRD.

What is the OGL?

The Open Game License (OGL) is a public copyright license by Wizards of the Coast that may be used by tabletop role-playing game developers to grant permission to modify, copy, and redistribute some of the content designed for their games, notably game mechanics. However, they must share-alike copies and derivative works. More information about the OGL can be found here.

A monster, spell, subclass, etc. is missing from the API / Database. Can I add it?

Please check if the data is within the SRD. If it is, feel free to open an issue or PR to add it yourself. Otherwise, due to legal reasons, we cannot add it.

Can this API be self hosted?

Yes it can! You can also host the data yourself if you don't want to use the API at all. You can also make changes and add extra data if you like. However, it is up to you to merge in new changes to the data and API.

Can I publish is on ? Is this free use?

Yes, you can. The API itself is under the MIT license, and the underlying data accessible via the API is supported under the SRD and OGL.

Status Page

The status page for the API can be found here: https://5e-bits.github.io/dnd-uptime/

Chat

Come hang out with us on Discord!

Contribute

This API is built from two repositories.

The repo containing the data lives here: https://github.com/bagelbits/5e-database
The repo with the API implementation lives here: https://github.com/bagelbits/5e-srd-api

This is a evolving API and having fresh ideas are always welcome! You can open an issue in either repo, open a PR for changes, or just discuss with other users in this discord.

This Python package is automatically generated by the OpenAPI Generator project:

API version: 0.1
Package version: 1.0.0
Build package: org.openapitools.codegen.languages.PythonClientCodegen For more information, please visit https://github.com/5e-bits

Requirements.

Python 3.7+

Installation & Usage

pip install

If the python package is hosted on a repository, you can install directly using:

pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git

(you may need to run pip with root permission: sudo pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git)

Then import the package:

import dnd5epy

Setuptools

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Then import the package:

import dnd5epy

Tests

Execute pytest to run the tests.

Getting Started

Please follow the installation procedure and then run the following:

import time
import dnd5epy
from dnd5epy.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://www.dnd5eapi.co
# See configuration.py for a list of all supported configuration parameters.
configuration = dnd5epy.Configuration(
    host = "https://www.dnd5eapi.co"
)



# Enter a context with an instance of the API client
with dnd5epy.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = dnd5epy.CharacterDataApi(api_client)
    index = 'cha' # str | The `index` of the ability score to get. 

    try:
        # Get an ability score by index.
        api_response = api_instance.api_ability_scores_index_get(index)
        print("The response of CharacterDataApi->api_ability_scores_index_get:\n")
        pprint(api_response)
    except ApiException as e:
        print("Exception when calling CharacterDataApi->api_ability_scores_index_get: %s\n" % e)

Documentation for API Endpoints

All URIs are relative to https://www.dnd5eapi.co

Class	Method	HTTP request	Description
CharacterDataApi	api_ability_scores_index_get	GET /api/ability-scores/{index}	Get an ability score by index.
CharacterDataApi	api_alignments_index_get	GET /api/alignments/{index}	Get an alignment by index.
CharacterDataApi	api_backgrounds_index_get	GET /api/backgrounds/{index}	Get a background by index.
CharacterDataApi	api_languages_index_get	GET /api/languages/{index}	Get a language by index.
CharacterDataApi	api_proficiencies_index_get	GET /api/proficiencies/{index}	Get a proficiency by index.
CharacterDataApi	api_skills_index_get	GET /api/skills/{index}	Get a skill by index.
ClassApi	api_classes_index_get	GET /api/classes/{index}	Get a class by index.
ClassApi	api_classes_index_multi_classing_get	GET /api/classes/{index}/multi-classing	Get multiclassing resource for a class.
ClassApi	api_classes_index_spellcasting_get	GET /api/classes/{index}/spellcasting	Get spellcasting info for a class.
ClassLevelsApi	api_classes_index_levels_class_level_features_get	GET /api/classes/{index}/levels/{class_level}/features	Get features available to a class at the requested level.
ClassLevelsApi	api_classes_index_levels_class_level_get	GET /api/classes/{index}/levels/{class_level}	Get level resource for a class and level.
ClassLevelsApi	api_classes_index_levels_get	GET /api/classes/{index}/levels	Get all level resources for a class.
ClassLevelsApi	api_classes_index_levels_spell_level_spells_get	GET /api/classes/{index}/levels/{spell_level}/spells	Get spells of the requested level available to the class.
ClassResourceListsApi	api_classes_index_features_get	GET /api/classes/{index}/features	Get features available for a class.
ClassResourceListsApi	api_classes_index_proficiencies_get	GET /api/classes/{index}/proficiencies	Get proficiencies available for a class.
ClassResourceListsApi	api_classes_index_spells_get	GET /api/classes/{index}/spells	Get spells available for a class.
ClassResourceListsApi	api_classes_index_subclasses_get	GET /api/classes/{index}/subclasses	Get subclasses available for a class.
CommonApi	api_endpoint_get	GET /api/{endpoint}	Get list of all available resources for an endpoint.
CommonApi	api_get	GET /api	Get all resource URLs.
EquipmentApi	api_equipment_categories_index_get	GET /api/equipment-categories/{index}	Get an equipment category by index.
EquipmentApi	api_equipment_index_get	GET /api/equipment/{index}	Get an equipment item by index.
EquipmentApi	api_magic_items_index_get	GET /api/magic-items/{index}	Get a magic item by index.
EquipmentApi	api_weapon_properties_index_get	GET /api/weapon-properties/{index}	Get a weapon property by index.
FeatsApi	api_feats_index_get	GET /api/feats/{index}	Get a feat by index.
FeaturesApi	api_features_index_get	GET /api/features/{index}	Get a feature by index.
GameMechanicsApi	api_conditions_index_get	GET /api/conditions/{index}	Get a condition by index.
GameMechanicsApi	api_damage_types_index_get	GET /api/damage-types/{index}	Get a damage type by index.
GameMechanicsApi	api_magic_schools_index_get	GET /api/magic-schools/{index}	Get a magic school by index.
MonstersApi	api_monsters_get	GET /api/monsters	Get list of monsters with optional filtering
MonstersApi	api_monsters_index_get	GET /api/monsters/{index}	Get monster by index.
RacesApi	api_races_index_get	GET /api/races/{index}	Get a race by index.
RacesApi	api_races_index_proficiencies_get	GET /api/races/{index}/proficiencies	Get proficiencies available for a race.
RacesApi	api_races_index_subraces_get	GET /api/races/{index}/subraces	Get subraces available for a race.
RacesApi	api_races_index_traits_get	GET /api/races/{index}/traits	Get traits available for a race.
RulesApi	api_rule_sections_index_get	GET /api/rule-sections/{index}	Get a rule section by index.
RulesApi	api_rules_index_get	GET /api/rules/{index}	Get a rule by index.
SpellsApi	api_spells_get	GET /api/spells	Get list of spells with optional filtering.
SpellsApi	api_spells_index_get	GET /api/spells/{index}	Get a spell by index.
SubclassesApi	api_subclasses_index_features_get	GET /api/subclasses/{index}/features	Get features available for a subclass.
SubclassesApi	api_subclasses_index_get	GET /api/subclasses/{index}	Get a subclass by index.
SubclassesApi	api_subclasses_index_levels_get	GET /api/subclasses/{index}/levels	Get all level resources for a subclass.
SubclassesApi	api_subclasses_index_levels_subclass_level_features_get	GET /api/subclasses/{index}/levels/{subclass_level}/features	Get features of the requested spell level available to the class.
SubclassesApi	api_subclasses_index_levels_subclass_level_get	GET /api/subclasses/{index}/levels/{subclass_level}	Get level resources for a subclass and level.
SubracesApi	api_subraces_index_get	GET /api/subraces/{index}	Get a subrace by index.
SubracesApi	api_subraces_index_proficiencies_get	GET /api/subraces/{index}/proficiencies	Get proficiences available for a subrace.
SubracesApi	api_subraces_index_traits_get	GET /api/subraces/{index}/traits	Get traits available for a subrace.
TraitsApi	api_traits_index_get	GET /api/traits/{index}	Get a trait by index.

Documentation For Models

Documentation For Authorization

Endpoints do not require authorization.

Author

Project details

These details have not been verified by PyPI

Project links

GitHub Statistics

View statistics for this project via Libraries.io, or by using our public dataset on Google BigQuery

Release history Release notifications | RSS feed

This version

1.0.7

Jun 24, 2023

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dnd5epy-1.0.7.tar.gz (120.8 kB view hashes)

Uploaded Jun 24, 2023 Source

Built Distribution

dnd5epy-1.0.7-py3-none-any.whl (723.0 kB view hashes)

Uploaded Jun 24, 2023 Python 3

Hashes for dnd5epy-1.0.7.tar.gz

Hashes for dnd5epy-1.0.7.tar.gz
Algorithm	Hash digest
SHA256	`047faa3d2c813da2a3976c4799da3b328ec448037366f0e4871b0865f58bfef8`
MD5	`d7bbd649b20376b9e31ae63ceaddd146`
BLAKE2b-256	`c07000f0b4b1d0fb3dc7c0a476a3d7bb3d6268e5322c020680e5092045626707`

Hashes for dnd5epy-1.0.7-py3-none-any.whl

Hashes for dnd5epy-1.0.7-py3-none-any.whl
Algorithm	Hash digest
SHA256	`f90f58965f650fc8f654e5aeb6935f69ba3aa14854fc1c60fd4f9bcb2fb6ab11`
MD5	`2058899a4f272e0e0b551bed9221a002`
BLAKE2b-256	`dd1a6ae76f378028d7c6d8e6f0301ce0bf0f3f235edf96f901993d4cf9281717`

dnd5epy 1.0.7

Navigation

Verified details

Maintainers

Unverified details

Project links

GitHub Statistics

Meta

Classifiers

Project description

openapi-client

Introduction

Getting Started

Authentication

GraphQL

Schemas

APIReference

DC

Damage

Choice

OptionSet

Option

FAQ

What is the SRD?

What is the OGL?

A monster, spell, subclass, etc. is missing from the API / Database. Can I add it?

Can this API be self hosted?

Can I publish is on ? Is this free use?

Status Page

Chat

Contribute

Requirements.

Installation & Usage

pip install

Setuptools

Tests

Getting Started

Documentation for API Endpoints

Documentation For Models

Documentation For Authorization

Author

Project details

Verified details

Maintainers

Unverified details

Project links

GitHub Statistics

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

`APIReference`

`DC`

`Damage`

`Choice`

`OptionSet`

`Option`