db-skill/skills/coa-db-skill/SKILL.md

name	description	requires
coa-db-skill	Look up Conquest of Ascension (CoA) WoW items, spells, NPCs, and quests on db.exil.es via its public JSON API. Use when asked about a CoA/Ascension item/spell/NPC/quest by name or id, its stats, what drops it, or to link a db.exil.es page.	bins curl

coa-db lookup (db.exil.es)

db.exil.es is the CoA Guild "Exiles" item/spell database (a self-hosted Wowhead-style site for Project Ascension's Conquest of Azeroth realm). It exposes a public, unauthenticated JSON API — no token needed.

• API base: https://db.exil.es/api/v1
• Human pages: https://db.exil.es/{item,spell,npc,quest}/{id} and https://db.exil.es/search?q=<text>
• OpenAPI: https://db.exil.es/api/openapi.json

The data is CoA-specific (custom classes, custom items in the 200000–2000000+ id ranges, BWL/raid drops, mystic scrolls). Vanilla ids work too.

Core workflow: name → id → detail

You almost always search by name first to get an id, then fetch the detail endpoint. Pipe through jq if available; otherwise python3 -m json.tool.

# 1) search (returns items, spells, npcs, quests, worldforged — each [{id,name,label,tone}])
curl -s 'https://db.exil.es/api/v1/search?q=Neurotoxin%20Edge'

# 2) fetch the item by id
curl -s 'https://db.exil.es/api/v1/items/312518'

URL-encode the query (%20 for space). tone on item results is the quality color (q0 poor … q4 epic, q5 legendary, q6 artifact).

Endpoints

Endpoint	Returns
GET /api/v1/search?q=<text>	{query, items[], spells[], npcs[], quests[], worldforged[]}; each entry {id, name, label, tone?}
GET /api/v1/items/{id}	item detail (below)
GET /api/v1/spells/{id}	spell detail
GET /api/v1/npcs/{id}	NPC detail
GET /api/v1/quests/{id}	quest detail
GET /api/v1/spells?mechanic=&effect_mechanic=&dispel_type=&limit=&cursor=	filterable spell catalogue (keyset-paginated; cursor = last id seen, limit 1–1000 default 200)
GET /api/v1/changes	newest-first change_event log
GET /api/v1/health	{status, version, database} (200 even in fixtures-only mode; data endpoints return 503 if database=false)

Unknown ids return 404.

Item detail fields

id, name, quality, item_level, required_level, item_class, item_subclass, inventory_type, bonding, worldforged, armor, stats[ {stat,value} ], spell_lines[], taught_spell, sell_price, source_label, description, required_class_mask.

source_label is the recorded drop/vendor/quest source (may be null if not yet catalogued). description can contain @…@-wrapped flavour tags (e.g. @Heroic Raid@).

Spell filter examples

# every Bleed spell (mechanic 15)
curl -s 'https://db.exil.es/api/v1/spells?mechanic=15&limit=1000'
# every Poison-dispellable aura (dispel_type 4)
curl -s 'https://db.exil.es/api/v1/spells?dispel_type=4'

Common codes: mechanic 15=Bleed, 1=Charm, 19=Disarm; dispel_type 1=Magic, 2=Curse, 3=Disease, 4=Poison.

Optional helper

bin/coa-db (in this repo) wraps the above:

coa-db search "Neurotoxin Edge"   # search, compact id/name list
coa-db item 312518                # item detail (jq-pretty if jq present)
coa-db spell 500071               # spell detail
coa-db npc 11502                  # npc detail
coa-db quest 580226               # quest detail
coa-db url item 312518            # print the human page URL

Set COADB_BASE to override the base URL (default https://db.exil.es).

Tips

• When a user gives a bare number that "looks like an item", try /api/v1/items/{id} directly; fall back to /search if it 404s.
• To share a result with a human, link the page: https://db.exil.es/item/<id>.
• Search is fuzzy/multi-type — a name like "Ragnaros" returns the NPC, the quest, and items at once; pick the right section.
• This API is read-only; there is no write/auth surface.