MapleStory: Develop α (unstable)

Intro

Welcome to MapleStory: Develop, an API For MapleStory's game data and characters. This is the same API that backs the MapleStory Network and we are making it public for developers to craft their own ideas and apps.

Base URL https://api.maplestory.net

GET/version/default

Get the API's default game version

Returns the default game version the API fetches data from when the user does not specify (or fully specify) one in a request

Responseapplication/json

{
  "version": 220,
  "subversion": 3,
  "locale": 2
}

Schema

versionnumberrequired

Version of the game

subversionnumberrequired

Subversion of the game (for a given version)

localenumberrequired

Code representing which region the game version is from (and which language its text is in). See the 'Locale Codes' docs for more info (TODO)

GET/items

List the game's items

List the game's items, specifying the result using supported filter parameters and a supplied game version. Result is paginated.

Parameters

Name	In	Type	Description
`page`default 0	query	`integer`	The page of the search result to retrieve
`maxEntries`default 100	query	`integer`	The maximum number of entries to return per page of the search result
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code
`sortBy`	query	`string`	The order to sort the retrieved items in. Can specify one of a given number of fields with a '+' or '-' in front of it for ascending or descending sorting, respectively `+name-name+level-level`
`name`	query	`string`	Filter for items with this name
`nameText`	query	`string`	Filter for items with names containing this string
`overallCategory`	query	`string`	Filter for items with a specific overall category
`overallCategoryText`	query	`string`	Filter for items with an overall category containing this string
`category`	query	`string`	Filter for items with a specific category
`categoryText`	query	`string`	Filter for items with an category containing this string
`subcategory`	query	`string`	Filter for items with a specific subcategory
`subcategoryText`	query	`string`	Filter for items with a subcategory containing this string
`minLevel`	query	`integer`	Filter for items that have a required level greater than this minimum value
`maxLevel`	query	`integer`	Filter for items that have a required level below maximum value
`cash`	query	`boolean`	Filter for items that are or are not cash items
`gender`default male	query	`string`	Filter for items that require this gender to be used or worn `malefemaleany`

Responseapplication/json

{
  "version": {
    "version": 220,
    "subversion": 3,
    "locale": 2
  },
  "metadata": {
    "page": 5,
    "nextPage": null,
    "prevPage": 4
  },
  "result": [
    {
      "itemId": 2070006,
      "name": "Ilbi Throwing-Stars",
      "description": "Throwing stars made of steel. Once they run out, they need to be recharged.",
      "overallCategory": "Use",
      "category": "Projectile",
      "subcategory": "Thrown",
      "availability": {
        "cash": false,
        "tradeable": false,
        "exclusive": false,
        "superior": false,
        "bossDrop": false,
        "durability": false,
        "shopPrice": 20000
      },
      "requiredStats": {
        "level": 10,
        "gender": "any"
      },
      "stats": {
        "attack": 27
      }
    }
  ]
}

Schema

versionobject

Specification of a specific version of MapleStory containing a version number, sub-version number, and locale code (also a number) representing the region of the version (for example, Global MapleStory or Korean MapleStory).

Default value for our services is always the most recent GMS version.

versionnumberrequired

Version of the game

subversionnumberrequired

Subversion of the game (for a given version)

localenumberrequired

Code representing which region the game version is from (and which language its text is in). See the 'Locale Codes' docs for more info (TODO)

metadataobject

Object containing metadata (such as pagination) for a search result

pageintegerrequired

The page returned by the search

nextPageintegerrequired

The next page of search results (null if it doesn't exist)

prevPageintegerrequired

The previous page of searc results (null if it doesn't exist)

resultobject[]

Array of found items' data

itemIdintegerrequired

The item's ID in the game data

namestring

The item's name

descriptionstring

A description of the item. Note that not all items in the game data have description text

overallCategorystringrequired

A string representing the high level category of the item

categorystringrequired

The item's category

subcategorystringrequired

The item's sub-category within its category

availabilityobjectrequired

How the item can be found or exchanged

requiredStatsobjectrequired

Stats a player must have to use or wear the item

statsobjectrequired

The stat bonuses the item confers to the user when worn or used

GET/item/{id}

Get an item

Get data and version information for a particular item with the given ID (if it exists).

Parameters

Name	In	Type	Description
`id`required	path	`integer`	The item's numeric identifier
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code

Responseapplication/json

{
  "itemId": 2070006,
  "name": "Ilbi Throwing-Stars",
  "description": "Throwing stars made of steel. Once they run out, they need to be recharged.",
  "overallCategory": "Use",
  "category": "Projectile",
  "subcategory": "Thrown",
  "availability": {
    "cash": false,
    "tradeable": false,
    "exclusive": false,
    "superior": false,
    "bossDrop": false,
    "durability": false,
    "shopPrice": 20000
  },
  "requiredStats": {
    "level": 10,
    "gender": "any"
  },
  "stats": {
    "attack": 27
  },
  "version": {
    "version": 216,
    "subversion": 0,
    "locale": 0
  }
}

Schema

itemIdintegerrequired

The item's ID in the game data

namestring

The item's name

descriptionstring

A description of the item. Note that not all items in the game data have description text

overallCategorystringrequired

A string representing the high level category of the item

categorystringrequired

The item's category

subcategorystringrequired

The item's sub-category within its category

availabilityobjectrequired

How the item can be found or exchanged

cashboolean

Whether the item is obtainable from the cash shop

tradeableboolean

Whether the item can be traded with other players

tradesAvailableinteger

The number of times the item can be traded with other players before it cannot be traded anymore

exclusiveboolean

Whether the item is exclusive (TODO what does this mean?)

superiorboolean

Whether the item is superior (TODO what does this mean?)

bossDropboolean

Whether the item is dropped by a boss monster

shopPriceinteger

The amount a non-player character (NPC) shopkeeper is willing to pay a player for the item

durabilityboolean

Whether the item 'breaks' or is 'used up' over time

requiredStatsobjectrequired

Stats a player must have to use or wear the item

levelinteger

The minimum level a player

genderstringdefault male

A character's gender

malefemaleany

jobTreesstring[]

The base jobs a player is required to be

magicianthiefwarriorbowman

strinteger

The minimum amount of the strength stat

dexinteger

The minimum amount of the dexterity stat

intinteger

The minimum amount of the intelligence stat

lukinteger

The minimum amount of the luck stat

fameinteger

The minimum amount of fame

statsobjectrequired

The stat bonuses the item confers to the user when worn or used

strinteger

The strength stat

dexinteger

The dexterity stat

intinteger

The intelligence stat

lukinteger

The luck stat

hpinteger

The number of hit points

mpinteger

The number of mana points

defenseinteger

The amount of defense against physical attacks

magicDefenseinteger

The amount of defense against magic attacks

speedinteger

The player's movement speed

jumpinteger

How much a player can jump in the air

attackinteger

The power of the player's physical attacks

magicAttackinteger

The power of the player's magic attacks

attackSpeedinteger

How quickly the player can make successive attacks

bossRateinteger

The power of the player's attacks against boss monsters

accuracyinteger

How accurate the player's attacks are (how rarely an attack misses the enemy)

avoidabilityinteger

How well the player can evade enemy attacks

ignoreDefenseinteger

Whether a player's attack will ignore the enemy's defense stats

charminteger

The charm stat

charismainteger

The charisma stat

willpowerinteger

The willpower stat

diligenceinteger

The diligence stat

insightinteger

The insight stat

upgradeSlotsinteger

The number of times a user can attempt to upgrade the item with scrolls

versionobjectrequired

Default value for our services is always the most recent GMS version.

versionnumberrequired

Version of the game

subversionnumberrequired

Subversion of the game (for a given version)

localenumberrequired

Code representing which region the game version is from (and which language its text is in). See the 'Locale Codes' docs for more info (TODO)

GET/item/{id}/icon

Get an item's icon

Returns an item's icon if it exists. The icon is an image of the item, usually with a shadow and possibly with special effects

Parameters

Name	In	Type	Description
`id`required	path	`integer`	The item's numeric identifier
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code

GET/item/{id}/iconRaw

Get an item's raw icon

Returns an item's 'raw' icon if it exists. The raw icon is an image of the item without a shadow and without any special effects

Parameters

Name	In	Type	Description
`id`required	path	`integer`	The item's numeric identifier
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code

GET/item/{id}/rawData

Get an item's unprocessed game data

Returns an item's data from the game's files in json format with no additional processing. This can have an arbitrary format and is subject to future breaking changes, so use of this API is recommended only for advanced users. If you have found a use case for this data that isn't possible with other APIs, please let a staff member know and we will consider the creation of a stable and specific API if the use case has sufficient demand.

Parameters

Name	In	Type	Description
`id`required	path	`integer`	The item's numeric identifier
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code

GET/monsters

List the game's monsters

List the game's monsters, specifying the result using supported filter parameters and a supplied game version. Result is paginated.

Parameters

Name	In	Type	Description
`page`default 0	query	`integer`	The page of the search result to retrieve
`maxEntries`default 100	query	`integer`	The maximum number of entries to return per page of the search result
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code
`sortBy`	query	`string`	The order to sort the retrieved monsters in. Can specify one of a given set of fields with a '+' or '-' in front of it for ascending or descending sorting, respectively `+name-name+level-level`
`name`	query	`string`	Filter for monsters with this name
`nameText`	query	`string`	Filter for monsters with names containing this string
`minLevel`	query	`integer`	Filter for monsters that have a level greater than this minimum value
`maxLevel`	query	`integer`	Filter for monsters that have a level below this maximum value
`boss`	query	`boolean`	Filter for monsters that are or are not bosses

Responseapplication/json

{
  "version": {
    "version": 220,
    "subversion": 3,
    "locale": 2
  },
  "metadata": {
    "page": 5,
    "nextPage": null,
    "prevPage": 4
  },
  "result": [
    {
      "monsterId": 100100,
      "name": "Snail",
      "boss": false,
      "stats": {
        "level": 1,
        "maxHp": 15,
        "speed": -65,
        "attack": 2,
        "defense": 10,
        "magicAttack": 1,
        "magicDefense": 10,
        "accuracy": 10,
        "minPushDamage": 5
      },
      "behavior": {
        "bodyAttack": true,
        "aggressive": false
      },
      "rewards": {
        "exp": 3,
        "publicDrops": false,
        "explosiveDrops": false
      }
    }
  ]
}

Schema

versionobject

Default value for our services is always the most recent GMS version.

versionnumberrequired

Version of the game

subversionnumberrequired

Subversion of the game (for a given version)

localenumberrequired

Code representing which region the game version is from (and which language its text is in). See the 'Locale Codes' docs for more info (TODO)

metadataobject

Object containing metadata (such as pagination) for a search result

pageintegerrequired

The page returned by the search

nextPageintegerrequired

The next page of search results (null if it doesn't exist)

prevPageintegerrequired

The previous page of searc results (null if it doesn't exist)

resultobject[]

Array of found monsters' data

monsterIdintegerrequired

The monster's ID in the game data

namestring

The monster's name

bossbooleanrequired

Whether the monster is a boss

statsobjectrequired

The monster's stats

behaviorobjectrequired

The monster's behaviors

rewardsobjectrequired

How the monster rewards players that kill it

GET/monster/{id}

Get a monster

Get data and version information for a particular monster with the given ID (if it exists).

Parameters

Name	In	Type	Description
`id`required	path	`integer`	The monster's numeric identifier
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code

Responseapplication/json

{
  "monsterId": 100100,
  "name": "Snail",
  "boss": false,
  "stats": {
    "level": 1,
    "maxHp": 15,
    "speed": -65,
    "attack": 2,
    "defense": 10,
    "magicAttack": 1,
    "magicDefense": 10,
    "accuracy": 10,
    "minPushDamage": 5
  },
  "behavior": {
    "bodyAttack": true,
    "aggressive": false
  },
  "rewards": {
    "exp": 3,
    "publicDrops": false,
    "explosiveDrops": false
  },
  "version": {
    "version": 216,
    "subversion": 0,
    "locale": 0
  }
}

Schema

monsterIdintegerrequired

The monster's ID in the game data

namestring

The monster's name

bossbooleanrequired

Whether the monster is a boss

statsobjectrequired

The monster's stats

levelinteger

The monster's level

maxHpinteger

The monster's maximum hit points

maxMpinteger

The monster's maximum mana points

speedinteger

The monster's movement speed

attackinteger

The power of the monster's physical attacks

defenseinteger

The monster's resistence to physical damage

magicAttackinteger

The power of the monster's magic attacks

magicDefenseinteger

The monster's resistence to magic damage

accuracyinteger

How accurate the monster's attacks are

evasioninteger

How hard it is for a player to hit the monster

minPushDamageinteger

Minimum damage a player must deal to the monster to push it backward, staggering it

hpRecoverinteger

The amount of hit points the monster recovers over time

mpRecoverinteger

The amount of mana points the monster recovers over time

elementAttributesobject[]

A list of elements the monster is resistent or vulnerable to

behaviorobjectrequired

The monster's behaviors

bodyAttackboolean

Whether the monster can attack a player by physically touching them

aggressiveboolean

Whether the monster goes after players without being attacked first

revivesAsIdinteger

The monster ID that the monster revives as when killed

summonIdinteger

The ID of the monster that the monster can summon

rewardsobjectrequired

How the monster rewards players that kill it

expinteger

The amount of experience points a player gains by killing the monster

publicDropsboolean

Whether the items dropped by the monster on death can be picked up immediately by anyone (and not just the player that killed it)

explosiveDropsboolean

Whether drops scatter across the map when the monster dies

versionobjectrequired

Default value for our services is always the most recent GMS version.

versionnumberrequired

Version of the game

subversionnumberrequired

Subversion of the game (for a given version)

localenumberrequired

Code representing which region the game version is from (and which language its text is in). See the 'Locale Codes' docs for more info (TODO)

GET/monster/{id}/icon

Get a monster's icon

Get an image of the monster. This is usually the first frame of its default animation

Parameters

Name	In	Type	Description
`id`required	path	`integer`	The monster's numeric identifier
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code

GET/monster/{id}/rawData

Get an monster's unprocessed game data

Returns a monster's data from the game's files in json format with no additional processing. This can have an arbitrary format and is subject to future breaking changes, so use of this API is recommended only for advanced users. If you have found a use case for this data that isn't possible with other APIs, please let a staff member know and we will consider the creation of a stable and specific API if the use case has sufficient demand.

Parameters

Name	In	Type	Description
`id`required	path	`integer`	The monster's numeric identifier
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code

GET/faces

List faces a Character can have

List the game's character faces, specifying the result using supported filter parameters and a supplied game version. Result is paginated.

Parameters

Name	In	Type	Description
`page`default 0	query	`integer`	The page of the search result to retrieve
`maxEntries`default 100	query	`integer`	The maximum number of entries to return per page of the search result
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code
`sortBy`	query	`string`	The order to sort the retrieved faces in. Can specify one of a given set of fields with a '+' or '-' in front of it for ascending or descending sorting, respectively `+name-name`
`name`	query	`string`	Filter for faces with this name
`nameText`	query	`string`	Filter for faces with names containing this string
`cash`	query	`boolean`	Filter for faces that are or are not cash items
`gender`default male	query	`string`	Filter for faces that require this gender `malefemaleany`

Responseapplication/json

{
  "version": {
    "version": 220,
    "subversion": 3,
    "locale": 2
  },
  "metadata": {
    "page": 5,
    "nextPage": null,
    "prevPage": 4
  }
}

Schema

versionobject

Default value for our services is always the most recent GMS version.

versionnumberrequired

Version of the game

subversionnumberrequired

Subversion of the game (for a given version)

localenumberrequired

Code representing which region the game version is from (and which language its text is in). See the 'Locale Codes' docs for more info (TODO)

metadataobject

Object containing metadata (such as pagination) for a search result

pageintegerrequired

The page returned by the search

nextPageintegerrequired

The next page of search results (null if it doesn't exist)

prevPageintegerrequired

The previous page of searc results (null if it doesn't exist)

resultobject[]

Array of found faces'

faceIdintegerrequired

Numeric ID for the face in the game

nameinteger

The name of the hairstyle

availabilityobjectrequired

Properties describing how the hairstyle is obtainable

requiredStatsobjectrequired

Character stats required to have the hairstyle

GET/face/{id}

Get a face

Get data and version information for a particular face with the given ID (if it exists).

Parameters

Name	In	Type	Description
`id`required	path	`integer`	The face's numeric identifier
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code

Responseapplication/json

No example is included for this response.

Schema

faceIdintegerrequired

Numeric ID for the face in the game

nameinteger

The name of the hairstyle

availabilityobjectrequired

Properties describing how the hairstyle is obtainable

cashboolean

Whether the hair is obtainable through the cash shop

requiredStatsobjectrequired

Character stats required to have the hairstyle

genderstring

The gender the character needs to be

versionobjectrequired

Default value for our services is always the most recent GMS version.

versionnumberrequired

Version of the game

subversionnumberrequired

Subversion of the game (for a given version)

localenumberrequired

Code representing which region the game version is from (and which language its text is in). See the 'Locale Codes' docs for more info (TODO)

GET/face/{id}/icon

Get a face's icon

Get an image of the face. This is usually the first frame of its default animation

Parameters

Name	In	Type	Description
`id`required	path	`integer`	The face's numeric identifier
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code

GET/hairs

List hairstyles a Character can have

List the game's hairstyles, specifying the result using supported filter parameters and a supplied game version. Result is paginated.

Parameters

Name	In	Type	Description
`page`default 0	query	`integer`	The page of the search result to retrieve
`maxEntries`default 100	query	`integer`	The maximum number of entries to return per page of the search result
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code
`sortBy`	query	`string`	The order to sort the retrieved hairs in. Can specify one of a given set of fields with a '+' or '-' in front of it for ascending or descending sorting, respectively `+name-name`
`name`	query	`string`	Filter for hairs with this name
`nameText`	query	`string`	Filter for hairs with names containing this string
`cash`	query	`boolean`	Filter for hairs that are or are not cash items
`gender`default male	query	`string`	Filter for hairs that require this gender `malefemaleany`

Responseapplication/json

{
  "version": {
    "version": 220,
    "subversion": 3,
    "locale": 2
  },
  "metadata": {
    "page": 5,
    "nextPage": null,
    "prevPage": 4
  }
}

Schema

versionobject

Default value for our services is always the most recent GMS version.

versionnumberrequired

Version of the game

subversionnumberrequired

Subversion of the game (for a given version)

localenumberrequired

Code representing which region the game version is from (and which language its text is in). See the 'Locale Codes' docs for more info (TODO)

metadataobject

Object containing metadata (such as pagination) for a search result

pageintegerrequired

The page returned by the search

nextPageintegerrequired

The next page of search results (null if it doesn't exist)

prevPageintegerrequired

The previous page of searc results (null if it doesn't exist)

resultobject[]

Array of found hairstyles

hairIdintegerrequired

Numeric ID for the hairstyle in the game

nameinteger

The name of the hairstyle

availabilityobjectrequired

Properties describing how the hairstyle is obtainable

requiredStatsobjectrequired

Character stats required to have the hairstyle

GET/hair/{id}

Get a hair

Get data and version information for a particular hair with the given ID (if it exists).

Parameters

Name	In	Type	Description
`id`required	path	`integer`	The hair's numeric identifier
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code

Responseapplication/json

No example is included for this response.

Schema

hairIdintegerrequired

Numeric ID for the hairstyle in the game

nameinteger

The name of the hairstyle

availabilityobjectrequired

Properties describing how the hairstyle is obtainable

cashboolean

Whether the hair is obtainable through the cash shop

requiredStatsobjectrequired

Character stats required to have the hairstyle

genderstring

The gender the character needs to be

versionobjectrequired

Default value for our services is always the most recent GMS version.

versionnumberrequired

Version of the game

subversionnumberrequired

Subversion of the game (for a given version)

localenumberrequired

Code representing which region the game version is from (and which language its text is in). See the 'Locale Codes' docs for more info (TODO)

GET/hair/{id}/icon

Get a hair's icon

Get an image of the hair. This is usually the first frame of its default animation

Parameters

Name	In	Type	Description
`id`required	path	`integer`	The hair's numeric identifier
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code

POST/character/render

Render a character given a character specification

Convenience route for directly rendering an image of a character based on items, body parts, etc. provided in the input. Everything is provided in the body parameters so no character is loaded or saved.

Parameters

Name	In	Type	Description
`version`default 220	query	`integer`	Game version
`subversion`default 0	query	`integer`	Game subversion
`locale`default 0	query	`integer`	Game locale code

Request body required

Specification of a character, gear, pose, and frames to render

skinstring

A character's skin tone

lightashenpalePinktannedpalegreenghostlydarkclaywhitemercedessoftPetalblushingPetal

faceIdinteger

The ID of the character's face

hairIdinteger

The ID of the character's hair

posestring

A pose a character can be in

standingOneHandedstandingTwoHandedwalkingOneHandedwalkingTwoHandedalertflyingjumpinglyingDownlyingDownStabbingfiringBowfiringCrossbowfiringBigBowsittingstabbingOneHandedthrustingOneHandedlungingOneHandedstabbingTwoHandedthrustingTwoHandedlungingTwoHandedthrowingBackhandedthrowingDownwardthrowingForehandedspinningThrowsmashingbashingjumpingSmashslashingBehindslashingFrontslashingUpwardspinningSlash

poseFrameinteger

Which frame of the character's pose to render

faceEmotestring

An emotion a character's face can make

defaultsmilecrybewilderedangryhittroubledstunnedvomitoopscheerschuwinkpainglitterdespairloveshineblazehumbowinghotdamqBlue

faceFramevalue

Which frame of the character's face emote to render

earsstringdefault humanEars

Type of ears a character's head can have

humanEarsbigEarslefEarshighlefEars

itemIdsinteger[]

The list of IDs of items the character is wearing

effectFrameinteger

The frame to use for an item's effect animation (if present)

chairItemIdinteger

Item ID for a character's chair

chairFrameinteger

The frame to use for a chair item's effect animation (if present)

Requestapplication/json

{
  "skin": "light",
  "faceId": 20000,
  "hairId": 30000,
  "pose": "walkingOneHanded",
  "poseFrame": 1,
  "faceEmote": "smile",
  "faceFrame": 0,
  "ears": "humanEars",
  "itemIds": [
    1060002,
    1040193
  ],
  "effectFrame": 0
}

Responseimage/png

Binary response (image/png).