Home Original page

Monster Hunter World API

Introduction

Welcome to the API docs for https://mhw-db.com.

We are currently looking for help with data entry and validation. We also always welcome feedback and suggestions. Interesting in contributing to the project? Join us on Discord!

Accessing the API

All data in the API can be accessed using the base URL https://mhw-db.com. You may optionally include a language tag as the prefix to any route in the API, in order to retrieve results that have been translated to a specific language. For a list of supported language tags, see the section on Localization below.

Example code and URLs in the rest of this documentation will not include any language tag prefixes for the sake of readability.

Localization

Currently, the API supports the following languages.

Language Tag
English —
French fr
German de
Chinese (simplified) zh
Chinese (traditional) zh-Hant

The default language is English, and does not require a language tag prefix on any route. To switch to any other language, simply prefix the route with the tag, e.g. https://mhw-db.com/zh-Hant/weapons/1.

Please be aware that not all supported languages will contain localized data, and may return null values for string fields. Localization requires manual data entry, and we're working through getting localized names into the API as quickly as possible. If you would like to help with localization, please reach out to me at tyler@lartonoix.com, or contact us via the Discord server linked in the sidebar.

Ailments

Get All Ailments

curl "https://mhw-db.com/ailments"

fetch('https://mhw-db.com/ailments')
    .then(response => response.json())
    .then(ailments => {
        // your code here
    });

The above command returns an array of Ailment objects. Some fields have been truncated for brevity.

[
    {
        "id": 1,
        "name": "Blastblight",
        "description": "Blastblight will cause a ...",
        "recovery": {
            "actions": [...],
            "items": [...]
        },
        "protection": {
            "items": [...],
            "skills": [...]
        }
    }
]

This endpoint retrieves all ailments.

HTTP Request

GET https://mhw-db.com/ailments

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of ailments. For field information, see the Ailment Fields section.

Get a Specific Ailment

curl "https://mhw-db.com/ailments/1"

fetch('https://mhw-db.com/ailments/1')
    .then(response => response.json())
    .then(ailment => {
        // your code here
    });

The above command returns a single Ailment object. Some fields have been truncated for brevity.

{
    "id": 1,
    "name": "Blastblight",
    "description": "Blastblight will cause a ...",
    "recovery": {
        "actions": [...],
        "items": [...]
    },
    "protection": {
        "items": [...],
        "skills": [...]
    }
}

This endpoint retrieves a specific ailment.

HTTP Request

GET https://mhw-db.com/ailments/<id>

Path Parameters

Parameter Type Description
id Integer The ID of the ailment to retrieve

Query Parameters

Parameter Required Description
p No See the Projecting Results section

Response

This endpoint returns a single ailment. For field information, see the Ailment Fields section.

Ailment Fields

{
    "id": 2,
    "name": "Bleeding",
    "description": "Bleeding causes damage when performing certain actions, such as running, ...",
    "recovery": {
        "actions": [
            "crouch"
        ],
        "items": [
            {
                "id": 11,
                "name": "Well-done Steak",
                "description": "Provides a moderate boost to your stamina and keeps it at max for a ...",
                "rarity": 2,
                "value": 48,
                "carryLimit": 10
            }
        ]
    },
    "protection": {
        "items": [],
        "skills": [
            {
                "id": 7,
                "name": "Bleeding Resistance",
                "description": "Grants protection against bleeding."
            }
        ]
    }
}

A sample Ailment object.

Field Type Description
id Integer The ID of the ailment
name String The name of the ailment
description String A short description of the ailment
recovery Recovery An object describing methods to recover from the ailment
protection Protection An object describing methods for mitigating or preventing the ailment

Recovery Fields

Field Type Description
actions Array<RecoveryAction> An array of actions that can be taken to remove the ailment
items Array<Item> An array of items that can remove the ailment

Recovery Actions

  • crouch
  • dodge

Protection Fields

Field Type Description
items Array<Item> An array of items that can prevent the ailment
skills Array<Skill> An array of skills that can prevent the ailment

Armor

Get All Armor Pieces

curl "https://mhw-db.com/armor"

fetch('https://mhw-db.com/armor')
    .then(response => response.json())
    .then(armorPieces => {
        // your code here
    });

The above command returns an array of Armor objects. Some fields have been truncated for brevity.

[
  {
    "id": 1,
    "name": "Leather Headgear",
    "type": "head",
    "rank": "low",
    "rarity": 1,
    "defense": {
      "base": 2,
      "max": 38,
      "augmented": 68
    },
    "resistances": {
      "fire": 2,
      "water": 0,
      "ice": 0,
      "thunder": 0,
      "dragon": 0
    },
    "slots": [...],
    "attributes": {...},
    "skills": [...],
    "armorSet": {
      "id": 1,
      "name": "Leather",
      "rank": "low",
      "pieces": [...]
    },
    "assets": {
      "imageMale": "https://assets.mhw-db.com/armor/...",
      "imageFemale": "https://assets.mhw-db.com/armor/..."
    },
    "crafting": {
      "materials": [...]
    }
  }
]

This endpoint retrieves all armor pieces.

HTTP Request

GET https://mhw-db.com/armor

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of armor pieces. For field information, see the Armor Fields section.

Get a Specific Armor Piece

curl "https://mhw-db.com/armor/1"

fetch('https://mhw-db.com/armor/1')
    .then(response => response.json())
    .then(armor => {
        // your code here
    });

The above command returns a single Armor object. Some fields have been truncated for brevity.

{
  "id": 1,
  "name": "Leather Headgear",
  "type": "head",
  "rank": "low",
  "rarity": 1,
  "defense": {
    "base": 2,
    "max": 38,
    "augmented": 68
  },
  "resistances": {
    "fire": 2,
    "water": 0,
    "ice": 0,
    "thunder": 0,
    "dragon": 0
  },
  "slots": [...],
  "attributes": {...},
  "skills": [...],
  "armorSet": {
    "id": 1,
    "name": "Leather",
    "rank": "low",
    "pieces": [...]
  },
  "assets": {
    "imageMale": "https://assets.mhw-db.com/armor/...",
    "imageFemale": "https://assets.mhw-db.com/armor/..."
  },
  "crafting": {
    "materials": [...]
  }
}

This endpoint retrieves an armor piece by it's ID.

HTTP Request

GET https://mhw-db.com/armor/<id>

Path Parameters

Parameter Type Description
id Integer The ID of the armor piece to retrieve

Query Parameters

Parameter Required Description
p No See the Projecting Results section

Response

This endpoint returns a single armor piece. For field information, see the Armor Fields section.

Armor Fields

{
  "id": 159,
  "name": "Leather Headgear Beta",
  "type": "head",
  "rank": "high",
  "rarity": 5,
  "defense": {
    "base": 32,
    "max": 54,
    "augmented": 70
  },
  "resistances": {
    "fire": 2,
    "water": 0,
    "ice": 0,
    "thunder": 0,
    "dragon": 0
  },
  "slots": [
    {
      "rank": 1
    }
  ],
  "attributes": {},
  "skills": [
    {
      "id": 207,
      "level": 1,
      "description": "Extends the time until ...",
      "modifiers": [],
      "skill": 67,
      "skillName": "Hunger Resistance"
    }
  ],
  "armorSet": {
    "id": 35,
    "name": "Leather Beta",
    "rank": "high",
    "pieces": [
      159,
      160,
      161,
      162,
      163
    ]
  },
  "assets": {
    "imageMale": "https://assets.mhw-db.com/armor/...",
    "imageFemale": "https://assets.mhw-db.com/armor/..."
  },
  "crafting": {
    "materials": [
      {
        "quantity": 2,
        "item": {
          "id": 119,
          "name": "Carbalite Ore",
          "description": "Ore obtained from mining outcrops. Still ...",
          "rarity": 0,
          "carryLimit": 0,
          "sellPrice": 0,
          "buyPrice": 0
        }
      }
    ]
  }
}

A sample Armor object.

Field Type Description
id Integer The ID of the armor piece
name String The name of the armor piece
type ArmorType The slot the armor piece fits in
rank Rank The rank of the armor piece
rarity Integer The rarity of the armor piece
defense Defense Contains information about the defense values of the armor piece
resistances Resistances Contains information about elemental resistances
slots Array<Slot> An array decoration slot information, containing between 0 and 3 items
skills Array<SkillRank> An array of skill ranks granted by the armor
armorSet SetInfo Contains information about the set that the armor piece belongs to
assets ArmorAssets Contains information about armor UI assets (such as preview images)
crafting ArmorCraftingInfo Contains crafting information for the armor piece
attributes ArmorAttributes See ArmorAttributes for more information

Armor Ranks

An armor's rank can be one of the following values:

  • low
  • high

Armor Types

An armor's type is one of the following values:

  • head
  • chest
  • gloves
  • waist
  • legs

Defense Objects

Field Type Description
base Integer The armor's base defense value
max Integer The armor's defense value at max level
augmented Integer The armor's defense value when augmented\

Armor Resistances

Field Type Description
fire Integer The armor's fire resistance
water Integer The armor's water resistance
ice Integer The armor's ice resistance
thunder Integer The armor's thunder resistance
dragon Integer The armor's dragon resistance

Set Info

Field Type Description
id Integer The ID of the armor set
name String The name of the armor set
rank ArmorRank The rank of the armor set
pieces Array<Integer> An array of IDs of all armor pieces in the set

Armor Assets

Please note that some assets may be missing or incorrect. This is due to some sources (such as Kiranico or the Fextralife wiki) also having incomplete information. Please verify that the asset is not also incorrect on those two sites before reporting issues with image assets.

Field Type Description
imageMale String URL to the male preview image, or null if one does not exist
imageFemale String URL to the female preview image, or null if one does not exist

Armor Crafting Info

Field Type Description
materials Array<CraftingCost> An array of crafting material costs

Armor Attributes

The ArmorAttributes is a dictionary of attribute modifiers attached to the armor piece. These fields are planned to be slowly phased out over several releases, and instead provided by specialized fields (such as resistances).

Possible attribute keys are listed below.

Name Type Description
requiredGender Enum("male", "female") If present, identifies the only gender that may equip the armor piece

Armor Sets

Get All Armor Sets

curl "https://mhw-db.com/armor/sets"

fetch('https://mhw-db.com/armor/sets')
    .then(response => response.json())
    .then(sets => {
        // your code here
    });

The command above returns an array of ArmorSet object. Some fields have been truncated for brevity.

[
  {
    "id": 1,
    "name": "Leather",
    "rank": "low",
    "pieces": [
      {
        "id": 1,
        "name": "Leather Headgear",
        "type": "head",
        "rank": "low",
        "rarity": 1,
        "armorSet": 1,
        "attributes": {...},
        "skills": [...],
        "assets": {
          "imageMale": "https://assets.mhw-db.com/armor/...",
          "imageFemale": "https://assets.mhw-db.com/armor/..."
        }
      }
    ],
    "bonus": null
  }
]

This endpoint retrieves all armor sets.

HTTP Request

GET https://mhw-db.com/armor/sets

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of armor sets. For field information, see the ArmorSet Fields section.

Get a Specific Armor Set

curl https://mhw-db.com/armor/sets/20

fetch('https://mhw-db.com/armor/sets/20')
    .then(response => response.json())
    .then(set => {
        // your code here
    });

The command above returns a single ArmorSet object. Some fields have been truncated for brevity.

{
  "id": 20,
  "name": "Anja",
  "rank": "low",
  "pieces": [
    {
      "id": 84,
      "name": "Anja Helm",
      "type": "head",
      "rank": "low",
      "rarity": 3,
      "armorSet": 20,
      "attributes": {...},
      "skills": [...],
      "assets": {
        "imageMale": "https://assets.mhw-db.com/armor/...",
        "imageFemale": "https://assets.mhw-db.com/armor/..."
      }
    }
  ],
  "bonus": {
    "id": 1,
    "name": "Anjanath Power",
    "ranks": [
      {
        "pieces": 3,
        "skill": {
          "id": 311,
          "level": 1,
          "description": "Temporarily reduces stamina ...",
          "modifiers": [...],
          "skill": 112,
          "skillName": "Adrenaline"
        }
      }
    ]
  }
}

This endpoint retrieves a specific armor set by it's ID.

HTTP Request

GET https://mhw-db.com/armor/sets/<id>

Path Parameters

Parameter Type Description
id Integer The ID of the armor set to retrieve

Query Parameters

Parameter Required Description
p No See the Projecting Results section

Response

This endpoint returns a single armor set. For field information, see the ArmorSet Fields section.

ArmorSet Fields

{
  "id": 20,
  "name": "Anja",
  "rank": "low",
  "pieces": [
    {
      "id": 84,
      "name": "Anja Helm",
      "type": "head",
      "rank": "low",
      "rarity": 3,
      "armorSet": 20,
      "attributes": {
        "defense": 20,
        "resistFire": 3,
        "resistWater": -3,
        "resistThunder": -1,
        "resistIce": -1
      },
      "skills": [
        {
          "id": 80,
          "level": 1,
          "description": "Fire attack +30",
          "modifiers": {
            "damageFire": 30
          },
          "skill": 26,
          "skillName": "Fire Attack"
        }
      ],
      "assets": {
        "imageMale": "https://assets.mhw-db.com/armor/...",
        "imageFemale": "https://assets.mhw-db.com/armor/..."
      }
    }
  ],
  "bonus": {
    "id": 1,
    "name": "Anjanath Power",
    "ranks": [
      {
        "pieces": 3,
        "skill": {
          "id": 311,
          "level": 1,
          "description": "Temporarily reduces stamina depletion ...",
          "modifiers": [],
          "skill": 112,
          "skillName": "Adrenaline"
        }
      }
    ]
  }
}

A sample ArmorSet object. Some fields have been truncated for brevity.

Field Type Description
id Integer The ID of the armor set
name String The name of the armor set
rank Rank The rank of the armor set
pieces Array<Armor> An array of armor pieces that are part of the set
bonus ArmorSetBonus Either an object describing armor set bonus information, or null

ArmorSet Bonus

Field Type Description
id Integer The ID of the bonus
name String The name of the bonus
ranks Array<ArmorSetBonusRank> An array of the different ranks of the bonus

ArmorSet Bonus Rank

Field Type Description
pieces Integer The minium number of armor pieces that must be equipped to trigger this level of the bonus
skill SkillRank The skill rank provided by this tier of the armor set bonus

Charms

The API splits charms up into two different objects. The Charm object, which is essentially a group of the different levels a charm can be, and the CharmRank object, which represents a charm at a particular step in it's upgrade tree. All charms are represented this way, even charms that can't be upgraded.

Get All Charms

curl "https://mhw-db.com/charms"

fetch('https://mhw-db.com/charms')
    .then(response => response.json())
    .then(charms => {
        // your code here
    });

The command above returns an array of Charm objects. Some fields have been truncated for brevity.

[
  {
    "id": 234,
    "name": "Poison Charm",
    "ranks": [
      {
        "level": 1,
        "rarity": 3,
        "skills": [...],
        "crafting": {
          "craftable": true,
          "materials": [...]
        }
      }
    ]
  }
]

This endpoint retrieves all charms.

HTTP Request

GET https://mhw-db.com/charms

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of charms. For field information, see the Charm Fields section.

Get a Specific Charm

curl "https://mhw-db.com/charms/234

fetch('https://mhw-db.com/charms/234')
    .then(response => response.json())
    .then(charm => {
        // your code here
    });

The above command returns a single Charm object. Some fields have been truncated for brevity.

{
  "id": 234,
  "name": "Poison Charm",
  "ranks": [
    {
      "level": 1,
      "rarity": 3,
      "skills": [...],
      "crafting": {
        "craftable": true,
        "materials": [...]
      }
    }
  ]
}

This endpoint retrieves a specific charm and it's ranks.

HTTP Request

GET https://mhw-db.com/charms/<id>

Path Parameters

Parameter Type Description
id Integer The ID of the charm to retrieve

Query Parameters

Parameter Required Description
p No See the Projecting Results section

Response

This endpoint returns a single charm and all of it's ranks. For field information, see the Charm Fields section.

Charm Fields

{
  "id": 234,
  "name": "Poison Charm",
  "ranks": [
    {
      "level": 1,
      "rarity": 3,
      "skills": [
        {
          "id": 1,
          "level": 1,
          "description": "Reduces the duration of poison by 30%.",
          "skill": 1,
          "skillName": "Poison Resistance",
          "modifiers": []
        }
      ],
      "crafting": {
        "craftable": true,
        "materials": [
          {
            "quantity": 1,
            "item": {
              "id": 231,
              "name": "Pukei-Pukei Sac",
              "description": "Pukei-Pukei material. Obtained by ...",
              "rarity": 0,
              "carryLimit": 0,
              "sellPrice": 0,
              "buyPrice": 0
            }
          }
        ]
      }
    }
  ]
}

A sample Charm object. Some fields have been truncated for brevity.

Field Type Description
id Integer The ID of the charm
name String The name of the charm
ranks Array<CharmRank> An array of the different ranks of the charm

CharmRank Fields

CharmRank objects represent the actual in-game equipment. Since most charms can be upgraded to higher levels, they're represented as ranks under a Charm object, which groups them together.

Field Type Description
level Integer The level of the charm rank
rarity Integer The rarity of the charm rank
skills Array<SkillRank> An array of skill ranks provided by the charm
crafting CharmRank Crafting An object describing crafting info for the charm

CharmRank Crafting Fields

Field Type Description
craftable Boolean Indicates whether or not the charm rank is directly craftable; if false, it must be upgraded from the previous level
materials Array<CraftingCost> An array of crafting material costs

Decorations

Get All Decorations

curl "https://mhw-db.com/decorations"

fetch('https://mhw-db.com/decorations')
    .then(response => response.json())
    .then(decorations => {
        // your code here
    });

The above command returns an array of Decoration objects.

[
  {
    "id": 1,
    "name": "Antidote Jewel 1",
    "rarity": 5,
    "skills": [
      {
        "id": 1,
        "description": "Reduces the duration of poison by 30%.",
        "level": 1,
        "skill": 1,
        "skillName": "Poison Resistance",
        "modifiers": []
      }
    ],
    "slot": 1
  },

This endpoint retrieves all decorations.

HTTP Request

GET https://mhw-db.com/decorations

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of decorations. For field information, see the Decoration Fields section.

Get a Specific Decoration

curl "https://mhw-db.com/decorations/1"

fetch('https://mhw-db.com/decorations/1')
    .then(response => response.json())
    .then(decoration => {
        // your code here
    });

The above command returns a single Decoration object.

{
  "id": 1,
  "name": "Antidote Jewel 1",
  "rarity": 5,
  "skills": [
    {
      "id": 1,
      "description": "Reduces the duration of poison by 30%.",
      "level": 1,
      "skill": 1,
      "skillName": "Poison Resistance",
      "modifiers": []
    }
  ],
  "slot": 1
}

This endpoint retrieves a specific decoration.

HTTP Request

GET https://mhw-db.com/decorations/<id>

Path Parameters

Parameter Type Description
id Integer The ID of the decoration to retrieve

Query Parameters

Parameter Required Description
p No See the Projecting Results section

Response

This endpoint returns a single decoration. For field information, see the Decoration Fields section.

Decoration Fields

{
  "id": 1,
  "name": "Antidote Jewel 1",
  "rarity": 5,
  "skills": [
    {
      "id": 1,
      "description": "Reduces the duration of poison by 30%.",
      "level": 1,
      "skill": 1,
      "skillName": "Poison Resistance",
      "modifiers": []
    }
  ],
  "slot": 1
}

A sample Decoration object.

Field Type Description
id Integer The ID of the decoration
name String The name of the decoration
rarity Integer The rarity of the decoration
slot Integer The slot that the decoration fits into
skills Array<SkillRank> An array of skill ranks that the decoration provides

Events

Get All Events

curl "https://mhw-db.com/events"

fetch('https://mhw-db.com/events')
    .then(response => response.json())
    .then(events => {
        // your code here
    });

The above command returns an array of Event objects. Some fields have been truncated for brevity.

[
  {
    "id": 1,
    "name": "A Visitor from Eorzea (Extreme)",
    "platform": "console",
    "exclusive": null,
    "type": "event quest",
    "expansion": "base",
    "description": "You and your entire party will have...",
    "requirements": "HR 50 or higher",
    "questRank": 9,
    "successConditions": "Slay a Behemoth",
    "startTimestamp": "2019-07-05T00:00:00+0000",
    "endTimestamp": "2019-07-11T23:59:00+0000",
    "location": {...}
  }
]

This endpoint retrieves all ongoing and scheduled in-game events, pulled from the official Capcom event pages.

Events are updated once per day, at midnight UTC. During the daily update, newly scheduled events will be added to the system, while events that have ended will be removed.

HTTP Request

GET https://mhw-db.com/events

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of events. For field information, see the Event Fields section.

Get a Specific Event

curl "https://mhw-db.com/events/1"

fetch('https://mhw-db.com/events/1')
    .then(response > response.json())
    .then(event => {
        // your code here
    });

The above command returns a single Event object. Some fields have been truncted for brevity.

{
  "id": 1,
  "name": "A Visitor from Eorzea (Extreme)",
  "platform": "console",
  "exclusive": null,
  "type": "event quest",
  "expansion": "base",
  "description": "You and your entire party will have...",
  "requirements": "HR 50 or higher",
  "questRank": 9,
  "successConditions": "Slay a Behemoth",
  "startTimestamp": "2019-07-05T00:00:00+0000",
  "endTimestamp": "2019-07-11T23:59:00+0000",
  "location": {...}
}

This endpoint retrieves a specific event.

HTTP Request

GET https://mhw-db.com/events/<id>

Path Parameters

Parameter Type Description
id Integer The ID of the event to retrieve

Query Parameters

Parameter Required Description
p No See the Projecting Results section

Response

This endpoint returns a single event. For field information, see the Event Fields section.

Event Fields

{
  "id": 1,
  "name": "A Visitor from Eorzea (Extreme)",
  "platform": "console",
  "exclusive": null,
  "type": "event quest",
  "expansion": "base",
  "description": "You and your entire party will have...",
  "requirements": "HR 50 or higher",
  "questRank": 9,
  "successConditions": "Slay a Behemoth",
  "startTimestamp": "2019-07-05T00:00:00+0000",
  "endTimestamp": "2019-07-11T23:59:00+0000",
  "location": {
    "id": 5,
    "name": "Elder's Recess",
    "zoneCount": 16,
    "camps": [...]
  }
}

A sample Event object.

Field Type Description
id Integer The ID of the event
name String The event's title
platform EventPlatform The platform that the event is running on (if an event is running on more than one platform, each platform will have it's own event object in the API)
exclusive EventExclusivity For consoles, a value other than null indicates that the event is only running on a specific console
type EventType The event's type
expansion Expansion The expansion that's required in order to access the event
description String A text description of the event
requires String A text description of the event's entry requirements
questRank Integer The rank of the quest
successConditions String A text description of the event's success condition(s)
startTimestamp DateTime A timestamp indicating when the event started
endTimestamp DateTime A timestamp indicating when the event will end
location Location The location in which the event takes place

Expansion Types

An event's expansion field may be one of the following values.

  • base
  • iceborne

Event Types

An event's type field may be one of the following values.

  • kulve taroth siege
  • safi'jiiva siege
  • event quest
  • challenge quest

Event types correspond to the section on the event page under which the event is listed.

Event Platforms

An event's platform field may be one of the following values.

  • pc
  • console

Event Exclusivity Types

Some events (such as the Horizon Zero Dawn event) only run on specific consoles. For such events, the exclusive field will contain one of the following values.

  • ps4
  • xbox

Items

Get All Items

curl "https://mhw-db.com/items"

fetch('https://mhw-db.com/items')
    .then(response => response.json())
    .then(items => {
        // your code here
    });

The above command returns an array of Item objects. Some fields have been truncated for brevity.

[
  {
    "id": 1,
    "name": "Potion",
    "description": "Potion",
    "rarity": 1,
    "carryLimit": 10,
    "value": 8
  }
]

This endpoint retrieves all items.

HTTP Request

GET https://mhw-db.com/items

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of items. For field information, see the Item Fields section.

Get a Specific Item

curl "https://mhw-db.com/items/1"

fetch('https://mhw-db.com/items/1')
    .then(response => response.json())
    .then(item => {
        // your code here
    });

The above command returns a single Item object.

{
  "id": 1,
  "name": "Potion",
  "description": "Potion",
  "rarity": 1,
  "carryLimit": 10,
  "value": 8
}

This endpoint retrieves a specific item.

HTTP Request

GET https://mhw-db.com/items/<id>

Path Parameters

Parameter Type Description
id Integer The ID of the item to retrieve

Query Parameters

Parameter Required Description
p No See the Projecting Results section

Response

This endpoint returns a single item. For field information, see the Item Fields section.

Item Fields

{
  "id": 1,
  "name": "Potion",
  "description": "Potion",
  "rarity": 1,
  "carryLimit": 10,
  "value": 8
}

A sample Item object.

Field Type Description
id Integer The ID of the item
name String The name of the item
description String A short description of the item
rarity Integer The rarity of the item
carryLimit Integer The maximum number of the item that may be in the player's inventory; zero indicates that there is no limit, or that the limit is not yet available
value Integer The Zenny value of the item; zero indicates that value is not yet available

Locations

Get All Locations

curl "https://mhw-db.com/locations"

fetch('https://mhw-db.com/locations')
    .then(response => response.json())
    .then(locations => {
        // your code here
    });

The above command returns an array of Location objects. Some fields have been truncated for brevity.

[
    {
        "id": 1,
        "name": "Ancient Forest",
        "zoneCount": 16,
        "camps": [
            {
                "id": 1,
                "name": "Southwest Camp",
                "zone": 1
            }
        ]
    }
]

This endpoint retrieves all locations.

HTTP Request

GET https://mhw-db.com/locations

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of locations. For field information, see the Location Fields section.

Get a Specific Location

curl "https://mhw-db.com/locations/1"

fetch('https://mhw-db.com/locations/1')
    .then(response => response.json())
    .then(location => {
        // your code here
    });

The above command returns a single Location object. Some fields have been truncated for brevity.

{
    "id": 1,
    "name": "Ancient Forest",
    "zoneCount": 16,
    "camps": [
        {
            "id": 1,
            "name": "Southwest Camp",
            "zone": 1
        }
    ]
}

This endpoint retrieves a specific location.

HTTP Request

GET https://mhw-db.com/locations/<id>

Path Parameters

Parameter Type Description
id Integer The ID of the location to retrieve

Query Parameters

Parameter Required Description
p No See the Projecting Results section

Response

This endpoint returns a single location. For field information, see the Location Fields section.

Location Fields

{
    "id": 1,
    "name": "Ancient Forest",
    "zoneCount": 16,
    "camps": [
        {
            "id": 1,
            "name": "Southwest Camp",
            "zone": 1
        },
        {
            "id": 2,
            "name": "Northwest Camp",
            "zone": 8
        },
        {
            "id": 3,
            "name": "Northeast Camp",
            "zone": 11
        },
        {
            "id": 4,
            "name": "Ancient Forest Camp",
            "zone": 17
        }
    ]
}

A sample Location object.

Field Type Description
id Integer The ID of the location
name String The name of the location
zoneCount Integer The number of zones in the location
camps Array<Camp> An array of camps available in the location

Camp Fields

Field Type Description
id Integer The ID of the camp
name String The name of the camp
zone Integer Which zone the camp is located in

Monsters

Get All Monsters

curl "https://mhw-db.com/monsters"

fetch('https://mhw-db.com/monsters')
    .then(response => response.json())
    .then(monsters => {
        // your code here
    });

The above command returns an array of Monster objects. Some fields have been truncated for brevity.

[
    {
        "id": 1,
        "name": "Apceros",
        "type": "small",
        "species": "herbivore",
        "description": "Herbivores that inhabit the Wildspire Waste. They've developed...",
        "elements": [],
        "ailments": [],
        "locations": [],
        "resistances": [],
        "weaknesses": [
            {
                "element": "thunder",
                "stars": 1,
                "condition": null
            }
        ],
        "rewards": [
            {
                "id": 1,
                "item": {
                    "id": 67,
                    "name": "Raw Meat",
                    "description": "Meat carved from a monster. Can be ...",
                    "rarity": 1,
                    "carryLimit": 10,
                    "value": 5
                },
                "conditions": [
                    {
                        "type": "carve",
                        "subtype": null,
                        "rank": "low",
                        "quantity": 1,
                        "chance": 100
                    }
                ]
            }
        ]
    }
]

This endpoint retrieves all monsters.

HTTP Request

GET https://mhw-db.com/monsters

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of monsters. For field information, see the Monster Fields section.

Get a Specific Monster

curl "https://mhw-db.com/monsters/1"

fetch('https://mhw-db.com/monsters/1')
    .then(response => response.json())
    .then(ailment => {
        // your code here
    });

The above command returns a single Monster object. Some fields have been truncated for brevity.

{
    "id": 1,
    "name": "Apceros",
    "type": "small",
    "species": "herbivore",
    "description": "Herbivores that inhabit the Wildspire Waste. They've developed...",
    "elements": [],
    "ailments": [],
    "locations": [],
    "resistances": [],
    "weaknesses": [
        {
            "element": "thunder",
            "stars": 1,
            "condition": null
        }
    ],
    "rewards": [
        {
            "id": 1,
            "item": {
                "id": 67,
                "name": "Raw Meat",
                "description": "Meat carved from a monster. Can be ...",
                "rarity": 1,
                "carryLimit": 10,
                "value": 5
            },
            "conditions": [
                {
                    "type": "carve",
                    "subtype": null,
                    "rank": "low",
                    "quantity": 1,
                    "chance": 100
                }
            ]
        }
    ]
}

This endpoint retrieves a specific monster.

HTTP Request

GET https://mhw-db.com/monsters/<id>

Path Parameters

Parameter Type Description
id Integer The ID of the monster to retrieve

Query Parameters

Parameter Required Description
p No See the Projecting Results section

Response

This endpoint returns a single monster. For field information, see the Monster Fields section.

Monster Fields

{
    "id": 2,
    "name": "Vaal Hazak",
    "type": "large",
    "species": "elder dragon",
    "description": "A grotesque Elder Dragon, that inhabits the...",
    "elements": [],
    "ailments": [
        {
            "id": 1,
            "name": "Effluvia",
            "description": "A blight caused by the mists in the Rotten Vale, and by certain...",
            "recovery": {...},
            "protection": {...}
        }
    ],
    "locations": [
        {
            "id": 1,
            "name": "Rotten Vale",
            "zoneCount": 16
        }
    ],
    "resistances": [
        {
            "element": "water",
            "condition": null
        }
    ],
    "weaknesses": [
        {
            "element": "fire",
            "stars": 3,
            "condition": null
        }
    ],
    "reward": [
        {
            "id": 1,
            "item": {...},
            "conditions": [...]
        }
    ]
}

A sample Monster object.

Field Type Description
id Integer The ID of the monster
name String The name of the monster
type MonsterType The monster's category
species MonsterSpecies The monster's species
description String A brief description of the monster
elements Array<ElementType> An array of elements used by the monster
ailments Array<Ailment> An array of ailments inflicted by the monster
locations Array<Location> An array of locations where the monster can be found
resistances Array<MonsterResistance> An array of the monster's elemental resistances
weakness Array<MonsterWeakness> An array of the monster's elemental weaknesses
rewards Array<MonsterReward> An array of the possible rewards / drops from the monster

Monster Types

A monster's type is one of the following values.

  • small
  • large

Monster Species

A monster's species is one of the following values.

  • bird wyvern
  • brute wyvern
  • elder dragon
  • fanged beast
  • fanged wyvern
  • fish
  • flying wyvern
  • herbivore
  • lynian
  • neopteron
  • piscine wyvern
  • relict
  • wingdrake

Monster Resistance Fields

Field Type Description
element ElementType The element the resistance applies to
condition String A text description of the condition under which the resistance applies (i.e. "covered in mud"), or null if the resistance is always active

Monster Weakness Fields

Field Type Description
element ElementType The element the weakness applies to
stars Integer The magnitude of the weakness; corresponds directly to the number of stars shown in the hunter's log in-game
condition String A text description of the condition under which the weakness applies (i.e. "covered in mud"), or null if the weakness is always active

Monster Reward Fields

Field Type Description
id Integer The reward's ID
item Item The item granted by the reward
conditions Array<RewardCondition> An array of conditions that cause the reward to be granted

Motion Values

Get All Motion Values

curl "https://mhw-db.com/motion-values"

fetch('https://mhw-db.com/motion-values')
    .then(response => response.json())
    .then(motionValues => {
        // your code here
    });

The above command returns an array of MotionValue objects. Some fields have been truncated for brevity.

[
  {
    "id": 1,
    "name": "Charged Slash Lv1",
    "weaponType": "great-sword",
    "damageType": "sever",
    "stun": null,
    "exhaust": null,
    "values": [...]
  }
]

This endpoint retrieves all motion values in the game.

HTTP Request

GET https://mhw-db.com/motion-values

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of motion values. For field information, see the MotionValue Fields section.

Get a Specific Motion Value

curl "https://mhw-db.com/motion-values/1"

fetch('https://mhw-db.com/motion-values/1')
    .then(response => response.json())
    .then(motionValue => {
        // your code here
    });

The above command returns a single MotionValue object. Some fields have been truncated for brevity.

{
  "id": 1,
  "name": "Charged Slash Lv1",
  "weaponType": "great-sword",
  "damageType": "sever",
  "stun": null,
  "exhaust": null,
  "values": [...]
}

This endpoint retrieves a motion value by it's ID.

HTTP Request

GET https://mhw-db.com/motion-values/<id>

Path Parameters

Parameter Type Description
id Integer The ID of the motion value to retrieve

Query Parameters

Parameter Required Description
p No See the Projecting Results section

Response

This endpoint returns a single motion value. For field information, see the MotionValue Fields section.

Get Motion Values By Weapon

curl "https://mhw-db.com/motion-values/great-sword"

fetch('https://mhw-db.com/motion-values/great-sword')
    .then(response => response.json())
    .then(motionValues => {
        // your code here
    });

The above command returns an array of MotionValue objects. Some fields have been truncated for brevity.

[
  {
    "id": 30,
    "name": "Charged Rising Slash Lv1",
    "weaponType": "great-sword",
    "damageType": "sever",
    "stun": null,
    "exhaust": null,
    "values": []
  }
]

This endpoint retrieves an array of motion values that belong to the specified weapon type.

HTTP Request

GET https://mhw-db.com/motion-values/<weaponType>

Path Parameters

Parameter Type Description
weaponType WeaponType The weapon type to retrieve motion values for

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of motion values. For field information, see the MotionValue Fields section.

MotionValue Fields

{
  "id": 119,
  "name": "Charged Big Bang",
  "weaponType": "hammer",
  "damageType": "blunt",
  "stun": null,
  "exhaust": 40,
  "hits": [
    15,
    76
  ]
}

A sample MotionValue object.

Field Type Description
id Integer The ID of the motion value
name String The name of the motion value
weaponType WeaponType The weapon type that the motion value belongs to
damageType DamageType The type of damage that the motion value does
stun Integer | Null The potency of the motion value's stun damage
exhaust Integer | Null The potency of the motion value's exhaust damage
hits Array<Integer> An array of hits caused by the motion value; each hit is represented as a whole number precentage of the raw damage applied by the hit

Skills

Get All Skills

curl https://mhw-db.com/skills

fetch('https://mhw-db.com/skills')
    .then(response => response.json())
    .then(skills => {
        // your code here
    });

The above command returns an array of Skill objects. Some fields have been truncated for brevity.

[
  {
    "id": 1,
    "name": "Poison Resistance",
    "description": "Grants protection against the effects of poison.",
    "ranks": [
      {
        "id": 1,
        "skill": 1,
        "level": 1,
        "description": "Reduces the duration of poison by 30%.",
        "modifiers": []
      }
    ]
  }
]

This endpoint retrieves a list of all skills.

HTTP Request

GET https://mhw-db.com/skills

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of skills and their ranks. For field information, see the Skill Fields section.

Get a Specific Skill

curl "https://mhw-db.com/skills/1"

fetch('https://mhw-db.com/skills/1')
    .then(response => response.json())
    .then(skill => {
        // your code here
    });

The above command returns a single Skill object. Some fields have been truncated for brevity.

{
  "id": 1,
  "name": "Poison Resistance",
  "description": "Grants protection against the effects of poison.",
  "ranks": [
    {
      "id": 1,
      "skill": 1,
      "level": 1,
      "description": "Reduces the duration of poison by 30%.",
      "modifiers": []
    }
  ]
}

This endpoint retrieves a specific skill and it's ranks.

HTTP Request

GET https://mhw-db.com/skills/<id>

Path Parameters

Parameter Type Description
id Integer The ID of the skill to retrieve

Query Parameters

Parameter Required Description
p No See the Projecting Results section

Response

This endpoint returns a single skill and all of it's ranks. For field information, see the Skill Fields section.

Skill Fields

{
  "id": 15,
  "name": "Attack Boost",
  "description": "Increases attack power. Also ...",
  "ranks": [
    {
      "id": 39,
      "skill": 15,
      "level": 1,
      "description": "Attack +3",
      "modifiers": {
        "attack": 3
      }
    }
  ]
}

A sample Skill object. Some fields have been truncated for brevity.

Field Type Description
id Integer The skill's ID
name String The name of the skill
description String A short description of the skill
ranks Array<SkillRank> An array of available ranks for the skill

SkillRank Fields

Field Type Description
id Integer The ID of the skill rank
level Integer The numeric level of the skill rank (starting at 1)
description String A text description of the skill rank
skill Integer The ID of the skill that the rank belongs to
skillName String The name of the skill that the rank belongs to
modifiers SkillRank Modifiers See SkillRank Modifiers for more information

SkillRank Modifiers

These objects describe the stat modifiers granted by a skill rank. The object is a simple dictionary, mapping string keys to a value (usually an integer). All possible modifier fields can be found in the table below.

Name Type Description
affinity Percent Modifies the affinity of a weapon
attack Integer Modifies the attack value of a weapon
damageFire Integer Modifies fire damage
damageWater Integer Modifies water damage
damageIce Integer Modifies ice damage
damageThunder Integer Modifies thunder damage
damageDragon Integer Modifies dragon damage
defense Integer Modifies the character's defense
health Integer Modifies the character's maximum health
sharpnessBonus Integer Modifies the maximum sharpness of a weapon
resistAll Integer Modifies all elemental resistances
resistFire Integer Modifies fire resistance
resistWater Integer Modifies water resistance
resistIce Integer Modifies ice resistance
resistThunder Integer Modifies thunder resistance
resistDragon Integer Modifies dragon resistance

Weapons

Get All Weapons

curl "https://mhw-db.com/weapons"

fetch('https://mhw-db.com/weapons')
    .then(response => response.json())
    .then(weapons => {
        // your code here
    });

The above command returns an array of Weapon objects. Some fields have been truncated for brevity.

[
  {
    "id": 1,
    "name": "Buster Sword 1",
    "type": "great-sword",
    "rarity": 1,
    "attack": {...},
    "elderseal": null,
    "attributes": {...},
    "damageType": "sever",
    "durability": [...],
    "slots": [...],
    "elements": [...],
    "crafting": {...},
    "assets": {...}
  }
]

This endpoint retrieves a list of all weapons.

HTTP Request

GET https://mhw-db.com/weapons

Query Parameters

Parameter Required Description
p No See the Projecting Results section
q No See the Searching the API section

Response

This endpoint returns an array of weapons. For field information, see the Weapon Fields section.

Get a Specific Weapon

curl "https://mhw-db.com/weapons/1"

fetch('https://mhw-db.com/weapons/1')
    .then(response => response.json())
    .then(weapon => {
        // your code here
    });

The above command returns a single Weapon object. Some fields have been truncated for brevity.

{
  "id": 1,
  "name": "Buster Sword 1",
  "type": "great-sword",
  "rarity": 1,
  "attack": {...},
  "elderseal": null,
  "attributes": {...},
  "damageType": "sever",
  "durability": [...],
  "slots": [...],
  "elements": [...],
  "crafting": {...},
  "assets": {...}
}

This endpoint retrieves a weapon by it's ID.

HTTP Request

GET https://mhw-db.com/weapons/<id>

Path Parameters

Parameter Type Description
id Integer The ID of the weapon to retrieve

Query Parameters

Parameter Required Description
p No See the Projecting Results section

Response

This endpoint returns a single weapon. For field information, see the Weapon Fields section.

Weapon Fields

{
  "id": 94,
  "name": "Iron Grace 3",
  "type": "long-sword",
  "rarity": 5,
  "attack": {
    "display": 462,
    "raw": 140
  },
  "elderseal": null,
  "attributes": {
    "damageType": "sever"
  },
  "damageType": "sever",
  "durability": [
    {
      "red": 90,
      "orange": 50,
      "yellow": 50,
      "green": 80,
      "blue": 30,
      "white": 0,
      "purple": 0
    },
    ...
  ],
  "slots": [
    {
      "rank": 1
    }
  ],
  "elements": [
    {
      "type": "water",
      "damage": 120,
      "hidden": true
    }
  ],
  "crafting": {
    "craftable": false,
    "previous": 93,
    "branches": [
      95
    ],
    "craftingMaterials": [],
    "upgradeMaterials": [
      {
        "quantity": 8,
        "item": {
          "id": 119,
          "name": "Carbalite Ore",
          "description": "Ore obtained from mining outcrops. Still ...",
          "rarity": 6,
          "carryLimit": 99,
          "value": 680
        },
        ...
      }
    ]
  },
  "assets": {
    "icon": "https://assets.mhw-db.com/weapons/long-sword/icons/...",
    "image": "https://assets.mhw-db.com/weapons/long-sword/..."
  }
}

A sample Weapon object. Some fields have been truncated for brevity.

Field Type Description
id Integer The ID of the weapon
name String The name of the weapon
type WeaponType The weapon's type
rarity Integer The rarity of the weapon
attack Attack Contains information about the attack values of the weapon
slots Array<Slot> An array containing slot information for the weapon
elements Array<WeaponElement> An array containing element damage info for the weapon
crafting WeaponCraftingInfo Contains crafting information for the weapon
assets WeaponAssets Contains information about weapon UI assets (such as preview images)
durability Array<WeaponSharpness> An array of sharpness information, ordered by handicraft level; base sharpness can always be found at index 0
elderseal EldersealType The elderseal type attributed to the weapon
damageType DamageType The primary damage type dealt by the weapon
attributes WeaponAttributes See WeaponAttributes for more information

Additionally, some weapon types include extra fields that aren't present on all weapons. Such fields are documented below.

Weapon Type Field Type
Bow coatings BowCoatings
Charge Blade and Switch Axe phial PhialType
Gunlance shelling ShellingType
Insect Glaive boostType BoostType
Light Bowgun and Heavy Bowgun ammo AmmoCapacities
specialAmmo SpecialAmmo
deviation Deviation

Weapon Types

A weapon's type can be one of the following values:
great-sword long-sword sword-and-shield
dual-blades hammer hunting-horn
lance gunlance switch-axe
charge-blade insect-glaive light-bowgun
heavy-bowgun bow

Weapon Attack

Field Type Description
display Integer The attack value of the weapon that's displayed in game
raw Integer The true raw attack value of the weapon

Weapon Crafting Info

Field Type Description
craftable Boolean Indicates whether or not the weapon may be directly crafted
previous Integer | Null The ID of the weapon that this weapon is upgraded from, or null if nothing upgrades into this weapon
branches Array<Integer> An array of IDs that the weapon may be upgraded into
craftingMaterials Array<CraftingCost> An array containing the material cost to create the weapon; will always be empty if craftable is false
upgradeMaterials Array<CraftingCost> An array containing the material cost to upgrade the weapon identified by previous into this weapon; will always be empty if previous is null

Weapon Elements

Field Type Description
type ElementType The element's damage type
damage Integer The power of the element
hidden Boolean Indicates whether or not the element is a hidden element

Please note that the type field can be any ElementType value except for stun.

Weapon Assets

Field Type Description
icon String The weapon's icon
image String An image showing the weapon's in game model

Weapon Sharpness

Since v1.13.0, the API provides true sharpness values for weapons. For each color, sharpness is represented as an integer indicating the number of normal hits the weapon can make before sharpness degrades (that is to say, the number of hits that did not bounce off of a monster due to the body part being too hard for the weapon or sharpness level).

All fields in a sharpness object can be found in the table below.

Field Type Description
red Integer The number of normal hits the weapon can make at red sharpness
orange Integer The number of normal hits the weapon can make at orange sharpness
yellow Integer The number of normal hits the weapon can make at yellow sharpness
green Integer The number of normal hits the weapon can make at green sharpness
blue Integer The number of normal hits the weapon can make at blue sharpness
white Integer The number of normal hits the weapon can make at white sharpness
purple Integer The number of normal hits the weapon can make at purple sharpness

In previous versions, these docs provided a simple method for visually representing sharpness values, since they were represented as percetages (which could be mapped 1:1 to pixels for a 100px wide sharpness bar). You can achieve the same result by taking the new sharpness values and using the following formula to convert them into their old percetage value, then flooring the result: ⌊sharpness / 400 * 100⌋.

So, for example, the long sword "Dark Scimitar 3" has a base durability of 110 red, 30 orange, 60 yellow, 80 green, 40 blue, 30 white, and 0 purple. This converts to the old system as follows.

Red: ⌊110 / 400 * 100⌋ = 27
Orange: ⌊30 / 400 * 100⌋ = 7
Yellow: ⌊60 / 400 * 100⌋ = 15
Green: ⌊80 / 400 * 100⌋ = 20
Blue: ⌊40 / 400 * 100⌋ = 10
White: ⌊30 / 400 * 100⌋ = 7
Purple: ⌊0 / 400 * 100⌋ = 0

The resulting bar would look something like the bar below.

Weapon Attributes

The weapon attributes object is a dictionary of attribute modifiers attached to a weapon. Most of these fields are planned to be slowly phased out over several releases, and instead provided by specialized fields (such as sharpness).

Possible attribute keys are listed below.

Name Type Description
affinity Integer The affinity of the weapon
defense Integer Some weapons (namely "gunlance" types) augment player defense; such weapons indicate that with this field

Damage Types

A weapon's damage type will be one of the following values:

  • blunt
  • piercing
  • slashing

Elderseal Types

A weapon's elderseal type may be one of the following values:

  • low
  • average
  • high

Bow Coatings

{
  "coatings": [
    "close range",
    "power"
  ]
}

A sample coatings field.

Bows use their coatings field to indicate which bow coatings can be used with the weapon. The coatings field is an array of strings, where each item is a coating type allowed by the weapon.

Coating types are listed below.

  • close range
  • paralysis
  • poison
  • sleep
  • blast
  • power

Phial Type

{
  "phial": {
    "type": "impact",
    "damage": null
  }
}

A sample phial field.

Charge Blades and Switch Axes use their phial field to provide information on what phial the weapon supports.

Field Type Description
type PhialType The phial's type (see below)
damage Integer If non-null, indicates the damage of the phial element

The value of the type field is split into two categories: standard and damaging.

"Standard" types will always have a null value for damage. Such types are listed below.

  • impact
  • element
  • power
  • power element

"Damaging" types will always have a numeric value for damage, and are listed below.

  • dragon
  • exhaust
  • para
  • poison

Shelling Type

{
  "shelling": {
    "type": "normal",
    "level": 1
  }
}

A sample shelling field.

Gunlances use their shelling field to provide information on what shelling type the weapon supports.

Field | Type | Description type | ShellingType | The weapon's shelling type (see below) level | Integer | The weapon's shelling level

Possible values for the type field are listed below.

  • long
  • normal
  • wide

Boost Type

A sample boostType field.

Insect glaives use their boostType field to indicate which boost the weapon supports. The boostType field is a simple string, and will be one of the following values.

  • sever
  • speed
  • element
  • health
  • stamina
  • blunt

Ammo Capacities

{
  "ammo": [
    {
      "type": "normal",
      "capacities": [
        6,
        4,
        0
      ]
    },
    {
      "type": "piercing",
      "capacities": [
        5,
        0,
        0
      ]
    },
    {
      "type": "poison",
      "capacities": [
        5,
        1
      ]
    },
    {
      "type": "slicing",
      "capacities": [
        1
      ]
    },
  ]
}

A sample ammo field.

Light and heavy bowguns use their ammo field to specify ammo capacities for their various ammo types. The ammo field is an array of AmmoCapacity objects.

Field Type Description
type AmmoType The ammo type described by the capacity object (see table below)
capacities Array<Integer> An array of capacities, ordered by level (where index zero is level one)

The table below lists all possible values for the type field, alongside the maximum level for the given type. The level indicates the number of elements present in the capacities field. The first element in the capacities array indicates the capacity for that type at ammo type level 1, the second element indicates capacity for ammo type level 2, and so on.

If a bowgun cannot use a certain ammo type, it will not be included in the ammo array.

Type Levels Type Levels
normal 3 flaming 1
piercing 3 water 1
spread 3 freeze 1
sticky 3 thunder 1
cluster 3 dragon 1
recover 2 slicing 1
poison 2 wyvern 1
paralysis 2 demon 1
sleep 2 armor 1
exhaust 2 tranq 1

Special Ammo

{
  "specialAmmo": "wyvernheart"
}

A sample specialAmmo field.

Light and heavy bowguns use their specialAmmo field to indicate which special ammo the weapon supports. The specialAmmo field is a simple string, and will be one of the following values.

  • wyvernblast
  • wyvernheart
  • wyvernsnipe

Deviation

A sample deviation field.

Light and heavy bowguns use their deviation field to indicate the projectile deviation used by the weapon. The deviation field is a simple string, and will be one of the following values.

  • none
  • low
  • average
  • high

Data Types

Scalar Data Types

Type Description
String Text of any length
Integer A normal integer
Percent A percentage, formatted as a whole number without the trailing percent sign; may be negative
Boolean A normal boolean (either true or false)
Enum(...) One of any value listed between the parenthesis
Array<T> An array containing zero more values of type T
DateTime An ISO8601 string representing a date and time, in UTC
Null Represents an empty value (usually used when a field has no value)

Rank Types

A rank type may be one of the following values.

  • low
  • high
  • master

Element Types

An element type may be one of the following values.
fire water ice
thunder dragon blast
poison sleep paralysis
stun

Reward Condition Types

A reward condition type may be one of the following values.

  • carve
  • investigation
  • mining
  • palico
  • plunderblade
  • reward
  • siege reward
  • shiny
  • track
  • wound

CraftingCost Objects

{
  "quantity": 1,
  "item": {
    "id": 231,
    "name": "Pukei-Pukei Sac",
    "description": "Pukei-Pukei material. Obtained ...",
    "rarity": 0,
    "carryLimit": 0,
    "sellPrice": 0,
    "buyPrice": 0
  }
}

A sample CraftingCost object. Some fields have been truncated for brevity.

Field Type Description
quantity Integer The quantity of the item needed for the craft
item Item The item to be consumed during crafting

Slot Objects

A sample Slot object.

Field Type Description
rank Integer The rank of the slot

RewardCondition Objects

{
  "type": "carve",
  "subtype": "body",
  "rank": "high",
  "quantity": 1,
  "chance": 15
}

A sample RewardCondition object.

Field Type Description
type RewardConditionType The type identifier of the condition
subtype String A text description of the condition's subtype (i.e. "body" or "tail" for the carve type)
rank Rank The mission rank required to obtain the reward
quantity Integer The number of items granted if the condition is met
chance Integer The percent chance the reward will be granted if the condition is met (whole number between 1 and 100)

Searching the API

Any endpoint can be searched by passing a q parameter in the URL, i.e. /skills?q=.... The value of q should be a MongoDB-style query document. For those that are not familiar with Mongo query documents, a short explanation can be found below.

Query Document

A "query document" is simply a JSON object that defines fields and values to search by. For example, a request to /skills?q={"name":"Poison Resistance"} would return a collection containing all skills whose name matched the string "Poison Resistance" exactly.

You can enhance your searches by using operators in your document, a list of which can be found here. For example, a request to /armor?q={"defense.base":{"$gt":50}} would return any armor with a base defense that is greater than 50.

{
  "skill.ranks.modifiers.damageIce": {
    "$exists": true
  }
}

You can also search fields that are related or nested in an object. A request to /skills?q={"ranks.level":3} would return a collection containing all skills that have a rank of 3. A request to /armor?q={"defense.base":40} would return all armor that has exactly 40 base defense.

Any field in the API that is an ID of another object or a collection of API objects (for example, the skill field on Decorations or the skills field on Charms) can be searched as if it were an object, as is show in the example to the right.

{
  "crafting.branches": {
    "$size": {
      "$gte": 1
    }
  }
}

Applied to /weapons, returns any weapon that has at least one item it can be upgraded into.

{
  "crafting.branches": {
    "$size": 0
  }
}

Applied to /weapons, returns any weapon that can't be upgraded any further (i.e. is the final weapon in it's tree).

Any field whose values is an array of related objects (such as Armor.skills or Charm.ranks) can be filtered by it's length by using the $sizeoperator on the field. This will work for ANY array of objects in the API, and supports filtering using more complicated operators, such as $in or $gte.

For examples, please see the example query documents to the right.

Operators

{
  "name": {
    "$like": "Negal%"
  },
  "rank": {
    "$in": ["high", "g"]
  }
}

An operator starts with a dollar sign, and allows you to perform more than just equality checks on data.

You can find a full list of supported operators in this GitHub repository.

Projecting Results

curl -G "https://mhw-db.com/weapons" \
    -d 'p={"id":true, "name": true, "type": true, "crafting.branches": true}'

const url = new URL('https://mhw-db.com/weapons');
url.searchParams.set('p', JSON.stringify({
    id: true,
    name: true,
    type: true,
    'crafting.branches': true,
}));

fetch(uri)
    .then(response => response.json())
    .then(weapons => {
        // your code here
    });

The above command returns an array of partial Weapon objects, whose fields are defined by the p query parameter.

[
  {
    "id": 1,
    "name": "Buster Sword 1",
    "type": "great-sword",
    "crafting": {
      "branches": [
        2
      ]
    }
  }
]

You can specify which fields the API should return, called "projecting", by providing the p query parameter.

The value of p should be a JSON object, where the key is the field path to project, and the value is a boolean indicating whether or not the field should be either true if the field should be included, or false if it should be excluded. Please note that you cannot mix inclusions and exclusions in a single projection.

Field paths should be the dot-notation identifier of a field. For example, weapons have a crafting field, which in turn contains a craftingMaterials field, which contains a quantity field. It's dot-notation form would be crafting.craftingMaterials.quantity. When projecting fields, any unrecognized field name will be silently ignored.

Deprecation Schedule

Below you can find a list of deprecated API features, as well as the information on when those features will be removed from the API.

Please note that the "Planned Removal" column indicates the date or API version that will fully remove the feature from the API. Please ensure that any code using a deprecated feature is updated as soon as possible.

Feature Replaced By Deprecated In Planned Removal
CharmRank.name N/A 1.18.0 v1.19.0

Errors

Error responses will always look something like this:

{
    "error": {
        "code": "error.code_type",
        "message": "A more verbose, human-readable error message"
    }
}

Any response that does not use the 200 range of HTTP status codes will, in almost every case, include a description of the error that occurred in the response body. Every error response will follow the same format.

Error responses will ALWAYS have, at minimum, an error key, which will contain an object. The error object will always have a code key and a message key. The code key acts like an identifier; it will always be the same for the same kind of error, and may be used for error handling in your code. The message key will be a description of what happened, and may change slightly. It should be used by you, the developer, to help debug what went wrong.

Error Codes

Code Description
not_found No object could be found with the ID provided
search.malformed_query Your query object was invalid; check your syntax and try again
search.empty_params Your search query must include at least one field to search by
search.error An unhandled error occurred while executing your search