Character

Character - API Reference

Overview

Base URL: https://api.idosgames.com

HTTP Method: POST

Route: /api/v2/{TitleTemplateId}/{TitleId}/Client/Character/{Action}/{UserID}

Actions (CharacterAction):

• GetCharacterDefinitions

• GetUserCharacters

• UpgradeStatLevel

• UpgradeCharacterLevel

• EquipItems

• UnequipItems

Authentication

Required Headers

• Authorization: Bearer <SessionTicket>

• Content-Type: application/json

Unauthorized (401)

Returned when:

• Authorization header is missing

• Bearer token is missing/invalid

• Session validation failed

Response Envelope (Server Standard)

All responses are wrapped with OperationResult<T>:

Success

{
  "Success": true,
  "Error": null,
  "Data": { }
}

Failure

{
  "Success": false,
  "Error": "Some error message",
  "Data": null
}

SuccessResponse

Used by operations like Equip/Unequip:

{
  "IsCompleted": true,
  "ServerTime": "2026-02-09T12:34:56.789Z"
}

---

Quick Reference (Action Table)

Action	Request Body Fields	Response Data Type
GetCharacterDefinitions	(none)	CharacterDefinitions
GetUserCharacters	(none)	GetCharactersResponse
UpgradeStatLevel	CharacterID, StatID	UpgradeStatLevelResponse
UpgradeCharacterLevel	CharacterID	UpgradeCharacterLevelResponse
EquipItems	CharacterID, ItemsToEquip[]	SuccessResponse
UnequipItems	CharacterID, UnequipSlotIDs[]	SuccessResponse

Request body can be {} for actions without arguments.

---

Endpoints

1) GetCharacterDefinitions

Returns CharacterDefinitions.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/Character/GetCharacterDefinitions/{UserID}

Body

{}

Response (OperationResult<CharacterDefinitions>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "AllowedCharacterIDs": ["main", "hero_1"],
    "AllowedEquipmentSlotIDs": ["Weapon", "Helmet"],

    "StatDefinitions": [
      {
        "StatID": "Power",
        "MaxLevel": 100,
        "Weight": 10,
        "BaseCostResource": {
          "Type": "VirtualCurrency",
          "CurrencyID": "CO",
          "Amount": 1
        },
        "BaseCost": 50,
        "CostScalingFactor": 1.08,
        "BaseStatValue": 10,
        "StatScalingFactor": 1.05,
        "Requirements": [
          { "RequiredStatID": "HP", "RequiredLevel": 5 }
        ],
        "DisplayName": "Power",
        "IconPath": "icons/power.png",
        "Description": "Increases damage."
      }
    ],

    "CustomStatDefinitions": {
      "hero_1": [
        {
          "StatID": "Power",
          "MaxLevel": 150,
          "BaseCost": 75
        }
      ]
    },

    "LevelDefinitions": [
      {
        "Level": 1,
        "UpgradeCost": [],
        "GlobalStatMultiplier": 1.0,
        "StatMaxLevelMultiplier": 1.0
      },
      {
        "Level": 2,
        "UpgradeCost": [
          { "Type": "Item", "ItemID": "hero_1_shard", "Amount": 10 }
        ],
        "GlobalStatMultiplier": 1.1,
        "StatMaxLevelMultiplier": 1.25
      }
    ],

    "CustomLevelDefinitions": {
      "hero_1": [
        {
          "Level": 2,
          "UpgradeCost": [
            { "Type": "VirtualCurrency", "CurrencyID": "CO", "Amount": 200 }
          ],
          "GlobalStatMultiplier": 1.15,
          "StatMaxLevelMultiplier": 1.5
        }
      ]
    }
  }
}

Common Errors

{ "Success": false, "Error": "Character definitions not found.", "Data": null }

---

2) GetUserCharacters

Returns player characters dictionary.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/Character/GetUserCharacters/{UserID}

Body

{}

Response (OperationResult<GetCharactersResponse>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "Characters": {
      "Main": {
        "CharacterID": "main",
        "Class": "Warrior",
        "Name": "Main Hero",
        "Level": 1,
        "Experience": 0,
        "Power": 120,
        "StatLevels": { "Power": 10, "HP": 5 },
        "Equipment": {
          "Weapon": {
            "SlotID": "Weapon",
            "CatalogVersion": "Items",
            "ItemID": "sword_01",
            "ItemInstanceID": "I_001",
            "EquippedAt": "2026-02-09T12:30:00Z"
          }
        },
        "UpdatedAt": "2026-02-09T12:34:56.789Z"
      }
    }
  }
}

Empty State

{
  "Success": true,
  "Error": null,
  "Data": { "Characters": {} }
}

---

3) UpgradeStatLevel

Upgrades a stat by +1 and consumes required resource.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/Character/UpgradeStatLevel/{UserID}

Body

{
  "CharacterID": "main",
  "StatID": "Power"
}

Response (OperationResult<UpgradeStatLevelResponse>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "StatID": "Power",
    "StatLevel": 11,
    "ConsumedResource": {
      "Type": "VirtualCurrency",
      "CurrencyID": "CO",
      "Amount": 120
    },
    "ConsumedResourceBalance": 880
  }
}

Common Errors

Missing StatID

{ "Success": false, "Error": "StatId is required", "Data": null }

Stat Not Found

{ "Success": false, "Error": "Stat 'Power' not found in configuration for character 'main'.", "Data": null }

Character Locked

{ "Success": false, "Error": "Character 'hero_1' is locked. Unlock it first.", "Data": null }

Requirements Not Met

{ "Success": false, "Error": "The required stat did not reach the desired level.", "Data": null }

Max Reached

{
  "Success": false,
  "Error": "Already at maximum level (100/100). Upgrade Character Rank to increase limit.",
  "Data": null
}

Fail / Not Enough Resource

{
  "Success": false,
  "Error": "Upgrade failed (not enough resource / race condition / requirements).",
  "Data": null
}

---

4) UpgradeCharacterLevel

Upgrades character rank/level by +1 (including unlock 0 → 1).

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/Character/UpgradeCharacterLevel/{UserID}

Body

{
  "CharacterID": "hero_1"
}

Response (OperationResult<UpgradeCharacterLevelResponse>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "CharacterID": "hero_1",
    "NewLevel": 1,
    "ConsumedResources": [
      { "Type": "Item", "ItemID": "hero_1_shard", "Amount": 10 }
    ]
  }
}

Common Errors

Not Allowed

{ "Success": false, "Error": "Character 'hero_1' is not allowed.", "Data": null }

Next Level Config Missing

{ "Success": false, "Error": "Max level reached or config for level 3 is missing.", "Data": null }

Not Enough Currency

{ "Success": false, "Error": "Not enough currency: CO", "Data": null }

Not Enough Items

{ "Success": false, "Error": "Not enough items: hero_1_shard", "Data": null }

Resource Revocation Failed

{ "Success": false, "Error": "Resource revocation failed.", "Data": null }

Database Error (Refunded)

{ "Success": false, "Error": "Database error. Resources refunded.", "Data": null }

---

5) EquipItems

Equips items to specified slots.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/Character/EquipItems/{UserID}

Body

{
  "CharacterID": "main",
  "ItemsToEquip": [
    { "SlotID": "Weapon", "ItemInstanceID": "I_001" },
    { "SlotID": "Helmet", "ItemInstanceID": "I_777" }
  ]
}

Response (OperationResult<SuccessResponse>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "IsCompleted": true,
    "ServerTime": "2026-02-09T12:34:56.789Z"
  }
}

---

6) UnequipItems

Unequips items from specified slots.

Request

Route POST /api/v2/{TitleTemplateId}/{TitleId}/Client/Character/UnequipItems/{UserID}

Body

{
  "CharacterID": "Main",
  "UnequipSlotIDs": ["Weapon", "Helmet"]
}

Response (OperationResult<SuccessResponse>)

{
  "Success": true,
  "Error": null,
  "Data": {
    "IsCompleted": true,
    "ServerTime": "2026-02-09T12:34:56.789Z"
  }
}

---

Models (Contracts)

CharacterRequest

{
  "CharacterID": "string",
  "StatID": "string",
  "ItemsToEquip": [
    { "SlotID": "string", "ItemInstanceID": "string" }
  ],
  "UnequipSlotIDs": ["string"]
}

EquipSlotPair

{
  "SlotID": "string",
  "ItemInstanceID": "string"
}

GetCharactersResponse

{
  "Characters": {
    "<CharacterID>": {
      "CharacterID": "string",
      "Class": "string",
      "Name": "string",
      "Level": 0,
      "Experience": 0,
      "Power": 0,
      "StatLevels": { "<StatID>": 0 },
      "Equipment": {
        "<SlotID>": {
          "SlotID": "string",
          "CatalogVersion": "string",
          "ItemID": "string",
          "ItemInstanceID": "string",
          "EquippedAt": "2026-02-09T12:34:56.789Z"
        }
      },
      "UpdatedAt": "2026-02-09T12:34:56.789Z"
    }
  }
}

CharacterModel

Represents a single owned character (stored inside GetCharactersResponse.Characters).

{
  "CharacterID": "string",
  "Class": "string",
  "Name": "string",
  "Level": 0,
  "Experience": 0,
  "Power": 0,
  "StatLevels": { "<StatID>": 0 },
  "Equipment": {
    "<SlotID>": {
      "SlotID": "string",
      "CatalogVersion": "string",
      "ItemID": "string",
      "ItemInstanceID": "string",
      "EquippedAt": "2026-02-09T12:34:56.789Z"
    }
  },
  "UpdatedAt": "2026-02-09T12:34:56.789Z"
}

EquippedItem

Equipment entry in CharacterModel.Equipment.

{
  "SlotID": "string",
  "CatalogVersion": "string",
  "ItemID": "string",
  "ItemInstanceID": "string",
  "EquippedAt": "2026-02-09T12:34:56.789Z"
}

ItemOrCurrency

Universal representation of currency or item costs/rewards.

{
  "Type": "Item",
  "Catalog": "Items", //CatalogVersion, CatalogName
  "Amount": 10,
  "ImagePath": "icons/items/hero_1_shard.png",
  "Name": "Hero Shard",
  "CurrencyID": null,
  "ItemID": "hero_1_shard"
}

ItemType

"Item" | "VirtualCurrency"

Notes

• When Type = "VirtualCurrency": use CurrencyID, Amount

• When Type = "Item": use Catalog, ItemID, Amount

• Name and ImagePath are optional UI helpers (may be null)

UpgradeStatLevelResponse

{
  "StatID": "string",
  "StatLevel": 0,
  "ConsumedResource": { /* ItemOrCurrency */ },
  "ConsumedResourceBalance": 0
}

UpgradeCharacterLevelResponse

{
  "CharacterID": "string",
  "NewLevel": 0,
  "ConsumedResources": [
    { /* ItemOrCurrency */ }
  ]
}

SuccessResponse

{
  "IsCompleted": true,
  "ServerTime": "2026-02-09T12:34:56.789Z"
}

---

Client Flow (Recommended)

A) Bootstrap (Open Character Screen)

1. GetCharacterDefinitions

2. GetUserCharacters

B) Unlock / Rank Up

1. UpgradeCharacterLevel (CharacterID)

2. GetUserCharacters

C) Upgrade Stat

1. UpgradeStatLevel (CharacterID, StatID)

2. GetUserCharacters

D) Equip / Unequip

1. EquipItems / UnequipItems

2. GetUserCharacters

---

Config Usage Guide (Client)

Stat Resolution (Custom → Global)

When rendering or calculating a stat:

1. If CustomStatDefinitions contains CharacterID and has matching StatID, use that StatDefinition.

2. Otherwise use the matching entry from StatDefinitions.

Level Resolution (Custom → Global)

When resolving upgrade cost or multipliers for a character level:

1. Try CustomLevelDefinitions[CharacterID] for the target Level.

2. Otherwise use LevelDefinitions.

Effective Max Stat Level

To display the true stat cap for a character:

• BaseMaxLevel = StatDefinition.MaxLevel

• Multiplier = CharacterLevelDefinition.StatMaxLevelMultiplier for current character Level

• EffectiveMaxLevel = floor(BaseMaxLevel * Multiplier)

---

Examples (cURL)

GetCharacterDefinitions

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/Character/GetCharacterDefinitions/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{}"

GetUserCharacters

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/Character/GetUserCharacters/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{}"

UpgradeStatLevel

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/Character/UpgradeStatLevel/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{\"CharacterID\":\"main\",\"StatID\":\"Power\"}"

UpgradeCharacterLevel

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/Character/UpgradeCharacterLevel/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{\"CharacterID\":\"hero_1\"}"

EquipItems

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/Character/EquipItems/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{\"CharacterID\":\"main\",\"ItemsToEquip\":[{\"SlotID\":\"Weapon\",\"ItemInstanceID\":\"I_001\"}]}"

UnequipItems

curl -X POST "https://<host>/api/v2/<TitleTemplateId>/<TitleId>/Client/Character/UnequipItems/<UserID>" \
  -H "Authorization: Bearer <SessionTicket>" \
  -H "Content-Type: application/json" \
  -d "{\"CharacterID\":\"main\",\"UnequipSlotIDs\":[\"Weapon\"]}"