Getting Started

Introduction

Everything you need to make your first request to the Genshin API.

The Genshin API is a free, read-only REST API that serves Genshin Impact data as JSON. Every endpoint is a plain GET request you can call from a browser, a server or a terminal, sending your API key in theX-API-Key header. Keys are free and require no sign-up: seeAuthentication to get one.

Base URL

All endpoints live under a single versioned base URL:

Base URL
https://genshin-api.REPLACE_ME.workers.dev/api/v1

Calling the base URL returns the list of available resources:

GET /api/v1
{
  "elements": "https://genshin-api.replace_me.workers.dev/api/v1/elements",
  "regions": "https://genshin-api.replace_me.workers.dev/api/v1/regions",
  "weapon-types": "https://genshin-api.replace_me.workers.dev/api/v1/weapon-types",
  "rarities": "https://genshin-api.replace_me.workers.dev/api/v1/rarities",
  "versions": "https://genshin-api.replace_me.workers.dev/api/v1/versions",
  "weapons": "https://genshin-api.replace_me.workers.dev/api/v1/weapons",
  "characters": "https://genshin-api.replace_me.workers.dev/api/v1/characters",
  "constellations": "https://genshin-api.replace_me.workers.dev/api/v1/constellations",
  "artifact-types": "https://genshin-api.replace_me.workers.dev/api/v1/artifact-types",
  "artifact-sets": "https://genshin-api.replace_me.workers.dev/api/v1/artifact-sets",
  "artifacts": "https://genshin-api.replace_me.workers.dev/api/v1/artifacts",
  "stats": "https://genshin-api.replace_me.workers.dev/api/v1/stats",
  "enemy-types": "https://genshin-api.replace_me.workers.dev/api/v1/enemy-types",
  "enemy-families": "https://genshin-api.replace_me.workers.dev/api/v1/enemy-families",
  "enemy-groups": "https://genshin-api.replace_me.workers.dev/api/v1/enemy-groups",
  "enemies": "https://genshin-api.replace_me.workers.dev/api/v1/enemies",
  "item-types": "https://genshin-api.replace_me.workers.dev/api/v1/item-types",
  "item-groups": "https://genshin-api.replace_me.workers.dev/api/v1/item-groups",
  "items": "https://genshin-api.replace_me.workers.dev/api/v1/items",
  "domain-types": "https://genshin-api.replace_me.workers.dev/api/v1/domain-types",
  "domains": "https://genshin-api.replace_me.workers.dev/api/v1/domains"
}

Three endpoints per resource

Every resource exposes the same three endpoints:

GET/api/v1/{resource}Paginated list
GET/api/v1/{resource}/randomOne random item
GET/api/v1/{resource}/{id or name}A single item

A single item can be requested by its numeric id or by its name. Names are case and space insensitive, so hu-tao,Hu Tao and HU-TAO all return the same character.

Your first request

Try it right here, or change the path to explore other resources:

GETgenshin-api.REPLACE_ME.workers.dev

Or from your own code:

JavaScript
const res = await fetch("https://genshin-api.REPLACE_ME.workers.dev/api/v1/characters/hu-tao", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const character = await res.json();

console.log(character.name, character.element.name);
cURL
curl -H "X-API-Key: YOUR_API_KEY" https://genshin-api.REPLACE_ME.workers.dev/api/v1/characters/hu-tao

Available resources

ResourceItemsDescription
artifact-sets64Artifact sets with the rarities they drop in, their release version and their pieces.
artifact-types5The five artifact slots with their possible main stats and sub stats. Each type lists the artifact sets that have a piece for it.
artifacts301Individual artifact pieces with their set, slot, description and lore. Rarities come from their set.
characters124Playable characters with their element, weapon, region, birthday, materials and constellations.
constellations136Character constellations with their meaning, release version and six levels. Each constellation links to its character; travelers have one per element.
domain-types6Domain types such as Domains of Blessing, Forgery or Mastery, Trounce Domains, One-Time Domains and Quest Domains. Each type lists its domains.
domains192Challenge, trounce, one-time and quest domains with their type, location, recommended elements, difficulty tiers, rewards, bosses and release version. Domains of Forgery and Mastery list the material each level gives and the days it is open.
elements8The elemental types of Teyvat. Each element lists the characters that wield it and the enemies that deal its damage.
enemies369Common enemies, elites and bosses with their type, family, group, region, damage elements, resistances, drops, release version and archive description.
enemy-families8Top-level enemy families such as Hilichurls, The Abyss or Automatons. Each family lists its groups and all its enemies.
enemy-groups55Enemy groups inside a family, such as Samachurls or Abyss Mages. Each group lists its family and its enemies.
enemy-types4Enemy classifications: common enemies, elites, normal bosses and weekly bosses. Each type lists its enemies.
item-groups122Groups of items that are the same material in different rarities, such as Hilichurl Materials or Agnidus Agate. Each group lists its items, the enemies that drop them and, for domain materials, the domain and level that rewards them.
item-types6Item types as shown in the in-game inventory, such as Character Ascension Materials or Local Specialties. Each type lists its groups and items.
items509Materials such as enemy drops, ascension gems, talent books, weapon ascension materials and local specialties, with their type, source, group, region, rarity, description, release version and farming days. Each item lists the enemies that drop it, the domains that reward it and the characters and weapons that use it.
rarities5Star ratings from 1 to 5. Each rarity lists the characters and weapons that have it.
regions9The nations and lands of Teyvat. Each region lists its characters, local specialties, bosses and domains.
stats33Character attributes such as HP, CRIT Rate or Elemental Mastery. Each stat lists the characters that gain it on ascension, the weapons that have it as secondary stat and the artifact types where it can roll.
versions54Game versions with their update title and release date. Each version lists the characters, weapons, constellations, artifact sets, enemies, items and domains released in it.
weapon-types5The weapon classes available to characters. Each type lists its characters and weapons.
weapons252Every weapon with its rarity, type, secondary stat, series, ascension materials and release version.

References and images

Related resources are returned as references: small objects with the id, slug, name and fullurl of the related item (plus its icon when it has one), so you can follow links without building URLs yourself.

Image fields always contain absolute URLs, ready to use in an <img> tag.