iScope Mechanist API

Integration guide for third-party Evony bots — ESB, Ragebot, GNBots, and more.

Quick Start

Log in to the iScope Portal with your account.

Subscribe — an active subscription is required.

Go to the API tab and click "Generate API Key". Copy and save it immediately — it will not be shown again in full.

Configure your bot with the API key and the endpoint base URL.

Base URL

https://iscope.app/api/mechanist

All endpoints are prefixed with /api/mechanist/

Authentication

Send your API key in one of these ways:

# Option 1: X-API-Key header (recommended)
curl -H "X-API-Key: iscope_abc123..." https://iscope.app/api/mechanist/monsters

# Option 2: Query parameter
curl "https://iscope.app/api/mechanist/monsters?api_key=iscope_abc123..."

Important: Your API key is locked to the first device (IP address) that uses it. If you need to change devices, contact support for a reset.

One key per account: Each account can generate exactly one API key. It cannot be regenerated. Keep it safe!

Data Endpoints

All data endpoints return JSON. Data is refreshed after each scan cycle (approximately every 75 minutes).

GET /api/mechanist/monsters

All regular monsters on the map.

Response

{
  "server_id": 1497,
  "server_name": "Server 1497",
  "generated_at": "2026-03-10T17:28:00",
  "total": 65107,
  "data": [
    {
      "wx": 731, "wy": 389, "level": 50,
      "entity_name": "Takeda Fire Cavalry",
      "entity_type": "monster",
      "hp_pct": null,
      "alliance_name": null,
      "scanned_at": "2026-03-10T17:23:09"
    }
  ]
}

GET /api/mechanist/bosses

All boss monsters (Ymir, Goblins, etc.).

Fields: wx, wy, level, entity_name, hp_pct, scanned_at

GET /api/mechanist/events

All event monsters (Knight Bayard, Sphinx, etc.).

Fields: wx, wy, level, entity_name, entity_type, scanned_at

GET /api/mechanist/resources

All resource tiles (farms, sawmills, quarries, iron mines, gold mines).

Fields: wx, wy, level, resource_type, entity_name, occupier_name, is_free, scanned_at

GET /api/mechanist/barbarians

All barbarian castles (regular + Arctic).

Fields: wx, wy, level, entity_name, scanned_at

GET /api/mechanist/all

Combined dump of all data types in a single response.

Contains: monsters, bosses, events, resources, barbarians arrays plus *_total counts.

Response Codes

Code	Meaning
200	Success — data returned
401	Missing or invalid API key
403	Subscription inactive or API key locked to another device
400	No server selected — log into the portal and select a server first
404	Cache not yet generated — wait for next scan cycle

Bot Configuration Examples

ESB (Evony Scanner Bot)

Base URL: https://iscope.app/api/mechanist
API Key:  iscope_xxxx...
Auth Header: X-API-Key

Ragebot

Mechanist API URL: https://iscope.app/api/mechanist/all
API Key: iscope_xxxx...
Method: GET, Header: X-API-Key

GNBots

Scanner API: https://iscope.app/api/mechanist
Key: iscope_xxxx...

cURL Example

curl -H "X-API-Key: iscope_xxxx..." https://iscope.app/api/mechanist/monsters | jq '.total'

Python Example

import requests

API_KEY = "iscope_xxxx..."
BASE = "https://iscope.app/api/mechanist"

r = requests.get(f"{BASE}/monsters", headers={"X-API-Key": API_KEY})
data = r.json()
print(f"Found {data['total']} monsters")
for m in data['data'][:5]:
    print(f"  ({m['wx']},{m['wy']}) {m['entity_name']} Lv{m['level']}")

FAQ

How often is data updated?

Data is refreshed after each scan cycle, approximately every 75 minutes.

Can I change my API key?

No. Each account gets exactly one API key. It cannot be regenerated or changed. Keep it safe!

I changed my IP / device. Now what?

Your API key is locked to the first device (IP address) that uses it. Contact support on Discord to request a reset.

What is the rate limit?

There is no strict rate limit, but data only changes every ~75 minutes. Polling more frequently than once per minute is unnecessary.