Guide API v1

This is for the documentation of current v1 guide API currently available. If you wish to help its development join us in Discord in the #orna-guide-api-dev channel.

The API uses the POST HTTP method. The request must be a JSON object sent in the body. If you are using python requests you must use the post method and the json argument instead of data.

Overview

Requests are a JSON object with keys referring to an aspect of the object being queried, for instance magic on an item, and their values being the search parameter. For the examples below, I will use the Item API to generate example requests.

A simple request to the item API can be: {"magic":150}. More keys can be added to the query like so: {"magic":150,"attack":150}. Valid keys and their value type can be found in the related API sections below.

A query can be modified by using combinators and comparators. By default all requests use the and combinator. This means a request to the item API like this: { "magic": 150, "attack": 150 }, will look for items matching 150 Magic and 150 Attack (the only item returned for this query is Arisen Ankh). You can alter the search by adding a combinator key like so: {"or":{"magic":150,"attack":150}} (this returns 4 items: Arisen Ankh, Lunar Dagger, Moon Staff, and Titan Axe). There are only two combinators: and and or. These can be nested within each other to make advanced queries, which will be detailed more below.

All keys have a comparator default, which can be found in the API reference below. Using the first example request above, the query would look for items matching exactly 150 Magic. You may want to search for items with values less than or greater than a given value though, which is where the comparator keys work. If you wanted to search for items with magic greater than or equal to 150, you would add a comparator key like so: {"gte":{"magic":150}} (this returns ~29 items).

Combining the combinators and comparators to create advanced queries is also possible. Let’s say you wanted to search for items with magic greater than or equal to 150, or attack greater than or equal to 150. The request would be: {"or":{"gte":{"magic":150,"attack":150}}} (this returns ~76 items). The way queries are generated allows you to swap the or and gte in this case, and you will get the same result.

In a special case, a list may be passed as a value. This is useful for the combinators when keys of the same name are being used, but it can also be used on the field keys themselves. For instance, if you wanted to search for items that contain the word Staff or the word Sword you have the option to pass a list to or like so: {"contains":{"or":[{"name":"Staff"},{"name":"Sword"}]}}. By the nature of combinators and comparators you may switch them as well: {"or":{"contains":[{"name":"Staff"},{"name":"Sword"}]}}.

Finally, you may want to order the results. To do this you can add a top-level key named order and pass a list of keys to order by. Default order is ascending, you can prefix the field with a - to signify you want descending order. Using the previous request example: {"or":{"gte":{"magic":150,"attack":150}},"order":["-tier","name"]}.

Combinators

key value description
and list or object Default Combine portion of subquery with AND
or list or object Combine portion of subquery with OR

Comparators

Numeric

key value description
eq list or object Integer keys must match their value exactly
ne list or object Integer keys must not match their value exactly
gt list or object Integer keys must match greater than their value
gte list or object Integer keys must match greater than or equal to their value
lt list or object Integer keys must match less than their value
lte list or object Integer keys must match less than or equal to their value

String

All string comparators are case-sensitive, but have a matching i prefix available to turn on case-insensitive matching (iexact for example).

key value description
exact list or object String keys must match their value exactly
contains list or object String keys must contain their value as a substring
startswith list or object String keys must start with their value
endswith list or object String keys must end with their value

API Actions

Item

URI: /api/v1/item

Field key Value type Default lookup Description
id Integer eq Internal Orna.Guide ID
name String iexact Item name
tier Integer eq Item tier
type String iexact Item type (Curative, Weapon, Head, Armor, Legs, Accessory, Material, Item, Other)
boss Boolean - Item boss flag (True or False)
hp Integer eq Item HP (HP) stat
mana Integer eq Item Mana (Mana) stat
attack Integer eq Item Attack (Att) stat
magic Integer eq Item Magic (Mag) stat
defense Integer eq Item Defense (Def) stat
resistance Integer eq Item Resistance (Res) stat
dexterity Integer eq Item Dexterity (Dex) stat
element String iexact Item element (Arcane, Dark, Dragon, Earthen, Fire, Holy, Lightning, Water)
equipped_by String iexact Item can be equipped by type of class (Mage, Thief, Warrior)

Assess

URI: /api/v1/assess

id or name are required, if both are supplied id takes precedence. At least one stat is required. If none or multiple items are found, an error is returned. If level is not between 1 and 10, an error is returned.

Field key Value type Default lookup Description
id Integer eq Internal Orna.Guide ID
name String iexact Item name
level Integer eq Item level ([1,10])
hp Integer eq Item HP (HP) stat
mana Integer eq Item Mana (Mana) stat
attack Integer eq Item Attack (Att) stat
magic Integer eq Item Magic (Mag) stat
defense Integer eq Item Defense (Def) stat
resistance Integer eq Item Resistance (Res) stat
dexterity Integer eq Item Dexterity (Dex) stat

Class

URI: /api/v1/class

Field key Value type Default lookup Description
id Integer eq Internal Orna.Guide ID
name String iexact Class name
female_name String iexact Class female name
tier Integer eq Class tier
slots Integer eq Class skill slots
cost String iexact Class cost (orn or real money, hence string)

Specialization

URI: /api/v1/specialization

Field key Value type Default lookup Description
id Integer eq Internal Orna.Guide ID
name String iexact Class name
female_name String iexact Class female name
tier Integer eq Class tier
cost String iexact Class cost (orn or real money, hence string)

Skill

URI: /api/v1/skill

Field key Value type Default lookup Description
id Integer eq Internal Orna.Guide ID
name String iexact Skill name
tier Integer eq Skill tier
mana_cost Integer eq Skill mana cost
type String iexact Skill type (Attack, Buff, D.O.T., Debuff, Magic, Multi-round Attack, Multi-round Magic, Passive)
element String iexact Skill element (Arcane, Dark, Dragon, Earthen, Fire, Holy, Lightning, Physical, Water)

Pet

URI: /api/v1/pet

Field key Value type Default lookup Description
id Integer eq Internal Orna.Guide ID
name String iexact Pet name
tier Integer eq Pet tier
attack Integer eq Pet attack %
spell Integer eq Pet spell %
heal Integer eq Pet heal %
buff Integer eq Pet buff %
debuff Integer eq Pet debuff %

Monster

URI: /api/v1/monster

Field key Value type Default lookup Description
id Integer eq Internal Orna.Guide ID
name String iexact Monster name
tier Integer eq Monster tier
boss Boolean - Monster boss flag (True or False)
spawn String iexact Monster spawn (Day Only, Gauntlet Only, Night Only, Raid, Water Only)
weak_to String iexact Monster element weakness (Arcane, Dark, Dragon, Earthen, Fire, Holy, Lightning, Physical, Water)
resistant_to String iexact Monster element resistance (Arcane, Dark, Dragon, Earthen, Fire, Holy, Lightning, Physical, Water)
immune_to String iexact Monster element immunity (Arcane, Dark, Dragon, Earthen, Fire, Holy, Lightning, Physical, Water)

Quest

URI: /api/v1/quest

Field key Value type Default lookup Description
id Integer eq Internal Orna.Guide ID
name String iexact Quest name
tier Integer eq Quest tier
story Boolean - Quest story flag, False is NPC quests (True or False)

Achievement

URI: /api/v1/achievement

Field key Value type Default lookup Description
id Integer eq Internal Orna.Guide ID
name String iexact Achievement name
tier Integer eq Achievement tier ([1,5])

NPC

URI: /api/v1/npc

Field key Value type Default lookup Description
id Integer eq Internal Orna.Guide ID
name String iexact NPC name
tier Integer eq NPC tier

Errors

error field gives more details about exact nature of error.

HTTP Code Error Code Details
404 255 Invalid API action given
400 254 Request JSON invalid, unable to parse
400 1 Bad type for value (e.g. String passed where Integer expected)
400 2 Invalid key given to query
400 4 Invalid key given to order
400 17 No id or name given to assess action
400 18 Invalid level (out of range [1,10]) given to assess action
400 20 No stats were given to assess action
404 24 No item found in assess action
409 31 Multiple items found in assess action

Examples

curl -X POST -d '{"name":"Adamantine Staff"}' https://orna.guide/api/v1/item

{
  "name": "Adamantine Staff",
  "type": "Weapon",
  "materials": [
    {
      "name": "Adamantine",
      "id": 247
    }
  ],
  "id": 100,
  "stats": {
    "attack": {
      "grows_with_quality": true,
      "base": 30
    },
    "magic": {
      "grows_with_quality": true,
      "base": 105
    }
  },
  "description": "A staff crafted with adamantine.  Surely, it will never break.",
  "boss": false,
  "tier": 5
}

curl -X POST -d '{"id":100,"attack":114,"magic":407,"level":10}' https://orna.guide/api/v1/assess

{
  "tier": 5,
  "type": "Weapon",
  "description": "A staff crafted with adamantine.  Surely, it will never break.",
  "id": 100,
  "quality": "1.89",
  "name": "Adamantine Staff",
  "boss": false,
  "stats": {
    "magic": {
      "base": 105,
      "values": [
        199,
        241,
        261,
        282,
        303,
        324,
        344,
        365,
        386,
        407
      ],
      "grows_with_quality": true
    },
    "attack": {
      "base": 30,
      "values": [
        57,
        69,
        74,
        80,
        86,
        91,
        97,
        103,
        108,
        114
      ],
      "grows_with_quality": true
    }
  },
  "materials": [
    {
      "id": 247,
      "name": "Adamantine"
    }
  ]
}