tl;dr - if you want to skip some background, usage instructions, and tips, then jump to the bottom of the post to find the “Endpoints” section.

When I built the Dark Souls 3 MugenMonkey planner I put together an API just for my purposes. This is used for the regular MugenMonkey frontend and for the mobile app. I was talking with some people over Twitter last week and learned that there was some potential interest in others being able to use this API. As such, I’ve decided to provide some simple documentation on it.

Disclaimers

  • I’m not going to require authentication to hit the API. (Obviously this doesn’t mean that you’ll be able to do anything screwy with it like mess with other people’s builds – these endpoints are informational only.) So please don’t do anything mean like hit the API every second for 24 hours. I don’t want to be forced to add ratelimiting to it!
  • This was built entirely for the usage of MugenMonkey, which means it may not have the type of data you’re looking for. Non shields don’t have the correct defense numbers for example, because I don’t use those on the site.
  • Right now this is mainly useful for DS3. The other planners do actually have some undocumented endpoints as well that you could try figuring out, but they won’t have any sort of weapon information. Sorry.

Usage

Each endpoint is located at /api/v0/<something>. Since we’re not dealing with authentication, you can access the data for anything with a simple GET request to that endpoint. All data is returned as JSON.

You can use any HTTP library or even just hit them using your browser. Try it out by opening https://mugenmonkey.com/api/v0/ds3_weapons. (You may want to install something like this [JSON formatter Chrome extension] to make it easy to read.)

Response Structure

The basic response will be a JSON object with 3 keys:

  • count - the total number of server results (useful for paginating)
  • The name of the object being fetched, e.g., ds3_weapons. This will be a nested object where the key is the ID of the object and the value contains the objects attributes.
  • results - this is an array that just contains the IDs and object names. You can probably ignore this.

Here’s an example of what /api/v0/ds3_spells would look like if there was only one spell:

{
  "count": 1,
  "ds3_spells": {
    "1": {
      "name": "Acid Surge",
      "faith_req": 13,
      "int_req": 0,
      "slots": 1,
      "spell_type": "pyromancy",
      "id": "1"
    }
  }
}

Pagination

By default each endpoint will return 20 results per page. You can specify more by using the per_page query param. Builds will limit that to a max of 100, while equipment (spells, weapons, etc) should let you do 500 per page, so you can get all the data in one chunk.

For going through builds you can use the page query param. e.g., https://mugenmonkey.com/api/v0/ds3_builds?per_page=100&page=100

Associations

Associations between objects are defined by their IDs. So when you load up a build, you’ll see, for example, a build’s “lh1_id”. This is the ID of that build’s LH1 weapon. If you wanted to know what that weapoin actually was you could hit the weapons endpoint to find out. However, a more efficient way is to use the include query param. This will include that object in your response in another top level key. An example will be more helpful:

https://mugenmonkey.com/api/v0/ds3_builds?per_page=1&include=lh1,rh1

The response would look like:

{
  "count": 77245,
  "ds3_builds": {
    "163697": {
      -- snip --
      "lh1_id": "234",
      "lh2_id": null,
      "lh3_id": null,
      "rh1_id": "168",
      "rh2_id": null,
      "rh3_id": null
      -- snip --
    }
  },
  "results": [],
  "ds3_weapons": {
    "168": {
      "name": "Anri's Straight Sword"
      -- snip --
    },
    "234": {
      "name": "Ancient Dragon Greatshield"
      -- snip --
    }
  }
}

As you can see, there’s now a new top level key called ds3_weapons. So if I look at the build, the lh1_id is 234. I then find the 234 key in the ds3_weapons object and discover it’s the Ancient Dragon Greatshield.

See the specific endpoint for available associations.

Endpoints

Dark Souls 3 Builds

  • Route: https://mugenmonkey.com/api/v0/ds3_builds
  • Available associations: head, body, arms, legs, ring1, ring2, ring3, ring4, lh1, lh2, lh3, rh1, rh2, rh3, spell1, spell2, spell3, spell4, spell5, spell6, spell7, spell8, spell9, spell10
  • Optional Filters:
    • by_user_name - find a particular user’s public builds. e.g., /api/v0/ds3_builds?by_user_name=naiyt
    • level_from - builds will be greater than this value
    • level_to - builds will be less than this value
    • by_title - search for builds with this string in their title

Dark Souls 3 Weapons

Dark Souls 3 Spells

Dark Souls 3 Rings

Dark Souls 3 Armor

Misc Data

Right now this endpoint only has the saturation curves used to calculate scaling. (Although I could add more info to it if it’s helpful.) See this blog post from last year if you want help calculating scaling.