Public Interface

API Reference & Integration

Connect your AI agents, bots, tools, and applications directly to E-Teyvat's structured Genshin Impact knowledge base and graph database.

REST / OpenAPI 3.1 Protocol

Machine-Readable Genshin Impact Telemetry & Facts

All endpoints return standard JSON and support CDN edge caching. Designed for high-throughput AI retrieval, Discord bots, and interactive web tools.

OpenAPI 3.1 Spec (/api/openapi.json)

Section

Core & Health

GET/api/health

Health & System Status

Test Endpoint

Returns health status, active dataset revision, entity/relation counts, and current game version telemetry.

Example Request

curl -X GET https://e-teyvat.vxnus.xyz/api/health

Example Response (JSON)

{
  "status": "ready",
  "connected": true,
  "revision": "81c86d97c771",
  "shortRevision": "81c86d9",
  "gameVersion": "v7.0.1",
  "phaseLabel": "Version 7.0 P1",
  "lastSyncedAt": "2026-07-26T03:17:00.000Z",
  "entityCount": 4200,
  "relationCount": 8900,
  "unresolvedRelationCount": 0
}

NOTE:Responses are cached with Cache-Control: public, max-age=60, s-maxage=300.

POST/api/e/verify

E Knowledge Provider Verification

Test Endpoint

Handshake verification endpoint for E knowledge provider registration and publisher authorization.

Request Headers

Header	Requirement	Description
Authorization	Optional	Optional Bearer token containing publisher verification key.

Example Request

curl -X POST https://e-teyvat.vxnus.xyz/api/e/verify -H "Authorization: Bearer <KEY>"

Example Response (JSON)

{
  "valid": true,
  "provider": "@vxnus/e-teyvat",
  "publisher": "vxnus"
}

NOTE:Part of the @vxnus/e provider distribution protocol.

Section

Entities & Relations

GET/api/v1/entities

List & Search Entities

Test Endpoint

Search canonical entities across all categories (characters, weapons, artifacts, enemies, materials, domains) with pagination and full-text keyword matching.

Parameters

Name	Type	Requirement	Description
q	string	Optional	Case-insensitive entity name or keyword substring.
kind	string	Optional	Exact category filter (e.g. characters, weapons, artifacts, enemies, materials, domains).
limit	number	Optional	Maximum records to return (1 to 50, default 24).
page	number	Optional	Pagination page number (default 1).

Example Request

curl -X GET "https://e-teyvat.vxnus.xyz/api/v1/entities?kind=characters&q=nahida&limit=10"

Example Response (JSON)

{
  "items": [
    {
      "id": "characters/nahida",
      "kind": "characters",
      "slug": "nahida",
      "name": "Nahida",
      "image": "https://cdn.e-teyvat.vxnus.xyz/characters/nahida.png",
      "description": "A caged bird secluded within the Sanctuary of Surasthana..."
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10,
  "preview": false
}

GET/api/v1/entities/{kind}/{slug}

Entity Detail & Graph Relations

Test Endpoint

Retrieve a single canonical entity along with its typed relations (requirements, drops, domain sources, builds, elements).

Parameters

Name	Type	Requirement	Description
kind	string	Required	Entity kind folder (e.g. characters, weapons, artifacts).
slug	string	Required	Entity identifier slug (e.g. furina, splendor-of-tranquil-waters).

Example Request

curl -X GET https://e-teyvat.vxnus.xyz/api/v1/entities/weapons/splendor-of-tranquil-waters

Example Response (JSON)

{
  "entity": {
    "id": "weapons/splendor-of-tranquil-waters",
    "kind": "weapons",
    "slug": "splendor-of-tranquil-waters",
    "name": "Splendor of Tranquil Waters",
    "rarity": 5,
    "weaponType": "Sword",
    "description": "A scepter with the color of clean water..."
  },
  "relations": [
    {
      "relationType": "requires",
      "targetKind": "materials",
      "targetSlug": "dross-of-pure-sacred-dewdrop",
      "targetName": "Dross of Pure Sacred Dewdrop",
      "metadata": {
        "count": 5
      }
    }
  ],
  "preview": false
}

Section

Farming & Domains

GET/api/v1/farming

Farming & Material Retrieval

Test Endpoint

Retrieves complete ascension farming pathways, material costs, domain schedules, and enemy drop locations for any character or weapon.

Parameters

Name	Type	Requirement	Description
target	string	Required	Target entity name, slug, or alias (e.g. Furina, Splendor of Tranquil Waters).
kind	string	Optional	Optional entity kind disambiguation (characters or weapons).

Example Request

curl -X GET "https://e-teyvat.vxnus.xyz/api/v1/farming?target=Furina"

Example Response (JSON)

{
  "target": {
    "name": "Furina",
    "kind": "characters",
    "slug": "furina"
  },
  "materials": [
    {
      "name": "Varunada Lazurite Gemstone",
      "kind": "materials",
      "slug": "varunada-lazurite-gemstone",
      "sources": [
        {
          "sourceType": "boss_drop",
          "name": "Hydro Tulpa",
          "days": [
            "Always Available"
          ]
        }
      ]
    },
    {
      "name": "Teachings of Justice",
      "kind": "materials",
      "slug": "teachings-of-justice",
      "sources": [
        {
          "sourceType": "domain_reward",
          "name": "Pale Forgotten Glory",
          "days": [
            "Tuesday",
            "Friday",
            "Sunday"
          ]
        }
      ]
    }
  ]
}

Section

Banner Intelligence

GET/api/v1/banners/rerun-pressure

Banner Rerun Pressure Ranking

Test Endpoint

Returns statistical banner pressure scores and urgency rankings for all characters based on historical rerun intervals and current absence duration.

Parameters

Name	Type	Requirement	Description
limit	number	Optional	Max characters to return (default 50).
offset	number	Optional	Offset for pagination (default 0).
pressureLevel	string	Optional	Filter by level: critical, elevated, normal, or recent.

Example Request

curl -X GET "https://e-teyvat.vxnus.xyz/api/v1/banners/rerun-pressure?limit=5"

Example Response (JSON)

{
  "currentPhase": {
    "phaseKey": "7.0.1",
    "sequenceIndex": 84
  },
  "characters": [
    {
      "id": "shenhe",
      "name": "Shenhe",
      "currentWait": 22,
      "medianInterval": 14,
      "pressureScore": 92,
      "pressureLevel": "critical",
      "confidenceLevel": "high"
    },
    {
      "id": "ganyu",
      "name": "Ganyu",
      "currentWait": 18,
      "medianInterval": 12,
      "pressureScore": 84,
      "pressureLevel": "critical",
      "confidenceLevel": "high"
    }
  ]
}

GET/api/v1/characters/{character}/banner-history

Character Banner History

Test Endpoint

Returns complete historical banner appearances, versions, start/end dates, and appearance interval history for a specific character.

Parameters

Name	Type	Requirement	Description
character	string	Required	Character slug (e.g. nahida, zhongli, raiden-shogun).

Example Request

curl -X GET https://e-teyvat.vxnus.xyz/api/v1/characters/nahida/banner-history

Example Response (JSON)

{
  "character": {
    "id": "nahida",
    "name": "Nahida",
    "rarity": 5
  },
  "appearances": [
    {
      "phaseKey": "3.2.1",
      "version": "3.2",
      "phaseNumber": 1,
      "sequenceIndex": 38,
      "startDate": "2022-11-02",
      "endDate": "2022-11-18"
    },
    {
      "phaseKey": "3.6.1",
      "version": "3.6",
      "phaseNumber": 1,
      "sequenceIndex": 48,
      "startDate": "2023-04-12",
      "endDate": "2023-05-02"
    }
  ],
  "intervals": [
    10,
    14
  ],
  "currentWait": 6,
  "source": {
    "name": "Samsara",
    "commitSha": null,
    "importedAt": null
  }
}

GET/api/v1/characters/{character}/rerun-analysis

Character Rerun Telemetry & Analysis

Test Endpoint

Provides granular statistical distribution metrics, mean/median intervals, percentile benchmarks, and automated forecast analysis notes.

Parameters

Name	Type	Requirement	Description
character	string	Required	Character slug (e.g. furina, arlecchino).

Example Request

curl -X GET https://e-teyvat.vxnus.xyz/api/v1/characters/furina/rerun-analysis

Example Response (JSON)

{
  "character": {
    "id": "furina",
    "name": "Furina"
  },
  "statistics": {
    "appearanceCount": 3,
    "completedIntervalCount": 2,
    "intervals": [
      9,
      11
    ],
    "currentWait": 5,
    "meanInterval": 10,
    "medianInterval": 10,
    "minimumInterval": 9,
    "maximumInterval": 11,
    "modeIntervals": [
      9,
      11
    ],
    "currentWaitPercentile": 45
  },
  "analysis": {
    "pressureScore": 48,
    "pressureLevel": "normal",
    "confidenceScore": 82,
    "confidenceLevel": "high",
    "summary": "Furina is likely not due for a rerun immediately based on historical patterns.",
    "reasons": [
      "Current absence of 5 phases is well under her median wait of 10 phases."
    ]
  },
  "disclaimer": "This is a statistical estimate based on historical banner rotations. It is not official information or a leak.",
  "modelVersion": "v1.2"
}

Section

AI & Knowledge Retrieval

GET/api/v1/knowledge/search

Full-Text Knowledge Search

Test Endpoint

Execute PostgreSQL full-text rank queries over chunked lore, build guides, and structured entity documents with ts_rank scoring.

Parameters

Name	Type	Requirement	Description
q	string	Required	Search query text supporting English web-search syntax.
limit	number	Optional	Max results to return (1 to 50, default 8).

Example Request

curl -X GET "https://e-teyvat.vxnus.xyz/api/v1/knowledge/search?q=archon+quest+fontaine&limit=4"

Example Response (JSON)

{
  "items": [
    {
      "entity_id": "characters/furina",
      "kind": "characters",
      "slug": "furina",
      "name": "Furina",
      "section": "Character Story 5",
      "content": "For five hundred years, she had maintained this performance...",
      "rank": 0.892
    }
  ],
  "preview": false
}

NOTE:Ideal for AI Agent retrieval tools and fuzzy lore queries across the entire knowledge base.

GET/api/v1/lore/search

Lore Engine Narrative Search

Test Endpoint

Search 1,239 in-game book volumes, 299 artifact relic chronicles, weapon histories, and monster lore with category filtering and snippet extraction.

Parameters

Name	Type	Requirement	Description
q	string	Optional	Keyword search across lore title, entity, and volume text.
category	string	Optional	Category filter: book, artifact, weapon, monster, character, or all.
limit	number	Optional	Maximum results to return (default 20).
page	number	Optional	Pagination page number (default 1).

Example Request

curl -X GET "https://e-teyvat.vxnus.xyz/api/v1/lore/search?q=Dandelion+Sea&category=book"

Example Response (JSON)

{
  "items": [
    {
      "id": "genshin:document:doc_book_1_vol_1",
      "category": "book",
      "title": "The Fox in the Dandelion Sea — Vol. 1",
      "entityName": "The Fox in the Dandelion Sea",
      "volumeNumber": 1,
      "snippet": "\"Dandelion, Dandelion, ride the wind to a faraway land,\" the Fox chants..."
    }
  ],
  "total": 11,
  "page": 1,
  "limit": 20,
  "categories": {
    "all": 11,
    "books": 11,
    "artifacts": 0,
    "weapons": 0,
    "monsters": 0,
    "characters": 0
  },
  "preview": false
}

NOTE:NOTICE: Currently operates as a deterministic lexical search over canonical records (books, artifact lore, weapon legends, monster profiles). Autonomous AI reasoning/synthesis is not active in Phase 1; endpoints return verbatim canonical text for grounded evidence.

GET/api/v1/lore/books

List In-Game Book Chronicles

Test Endpoint

List and browse all in-game book chronicles with total volume counts and preview snippets.

Parameters

Name	Type	Requirement	Description
q	string	Optional	Filter by book title substring.
limit	number	Optional	Records limit (default 24).
page	number	Optional	Page number (default 1).

Example Request

curl -X GET "https://e-teyvat.vxnus.xyz/api/v1/lore/books?q=Gunnhildr"

Example Response (JSON)

{
  "items": [
    {
      "id": "genshin:book:2",
      "slug": "biography-of-gunnhildr",
      "name": "Biography of Gunnhildr",
      "volumeCount": 1,
      "sampleSnippet": "A brief history of the ancient Gunnhildr clan..."
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 24
}

Section

MCP Server

POST/api/mcp

Public MCP Server

Test Endpoint

Model Context Protocol (MCP) server endpoint. Exposes all 9 Teyvat Knowledge Base tools to any MCP-compatible AI agent — Claude Desktop, Cursor, Antigravity, LangChain, and others — without custom fetch logic. Implements the 2026-07-28 MCP specification (Streamable HTTP) with automatic fallback for 2025-era clients.

Request Headers

Header	Requirement	Description
Content-Type	Required	Must be application/json for POST requests.

Example Request

# Add to mcp_config.json (Streamable HTTP clients)
{
  "mcpServers": {
    "teyvat": {
      "url": "https://e-teyvat.vxnus.xyz/api/mcp"
    }
  }
}

# For stdio-only clients (via mcp-remote bridge)
{
  "mcpServers": {
    "teyvat": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://e-teyvat.vxnus.xyz/api/mcp"]
    }
  }
}

Example Response (JSON)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "find_entity",
        "description": "Search canonical entities by name, kind, or alias."
      },
      {
        "name": "get_entity",
        "description": "Retrieve a single entity with outgoing graph relations."
      },
      {
        "name": "get_farming_sources",
        "description": "Farming pathways, material costs & domain schedules."
      },
      {
        "name": "search_lore",
        "description": "Full-text search across lore documents."
      },
      {
        "name": "get_lore_book",
        "description": "Retrieve complete anthology text for a book."
      },
      {
        "name": "search_knowledge",
        "description": "Full-text rank search over build guides & dialogue."
      },
      {
        "name": "get_banner_rerun_pressure",
        "description": "Banner rerun pressure rankings."
      },
      {
        "name": "get_character_banner_history",
        "description": "Historical banner appearances for a character."
      },
      {
        "name": "get_character_rerun_analysis",
        "description": "Statistical rerun pressure analysis."
      }
    ]
  }
}

NOTE:Rate limit: 60 requests per IP per 60 s. Responses include X-RateLimit-Limit and X-RateLimit-Window headers. Exceeding the limit returns HTTP 429 with a Retry-After: 60 header.

MCP Server — One-Line AI Agent Integration

Add E-Teyvat to any MCP-compatible AI agent (Claude Desktop, Cursor, Antigravity, LangChain, and others) by pointing it at https://e-teyvat.vxnus.xyz/api/mcp. All 9 tools are auto-discovered — no custom fetch code required.

Streamable HTTP (recommended)

{
  "mcpServers": {
    "teyvat": {
      "url": "https://e-teyvat.vxnus.xyz/api/mcp"
    }
  }
}

stdio proxy (for stdio-only clients)

{
  "mcpServers": {
    "teyvat": {
      "command": "npx",
      "args": ["-y", "mcp-remote",
        "https://e-teyvat.vxnus.xyz/api/mcp"]
    }
  }
}

find_entitySearch entities by name, kind, or alias

get_entitySingle entity with full graph relations

get_farming_sourcesMaterial costs & domain schedules

search_lore1,239 books, 299 artifact & weapon lore docs

get_lore_bookFull anthology text for an in-game book

search_knowledgeBuild guides & character dialogue

get_banner_rerun_pressureRerun pressure rankings (all chars)

get_character_banner_historyHistorical banner appearances

get_character_rerun_analysisStatistical rerun pressure analysis

RATE LIMIT:60 requests / IP / 60 s. Responses carry X-RateLimit-Limit and X-RateLimit-Window headers. Exceeding the limit returns HTTP 429 with Retry-After: 60.

AI Agent & Large Language Model Integration (RAG Architecture)

Ground Truth vs. Reasoning: E-Teyvat serves as the deterministic Retrieval Layer (Ground Truth), providing verbatim in-game chronicles, books, relic stories, and graph relations. External AI agents (Claude, Gemini, GPT, LangChain, etc.) invoke these endpoints as tool calls to retrieve raw canonical evidence, allowing the external AI model to perform the semantic reasoning, timeline synthesis, and answer generation with exact source citations.

find_entity(query, kind)Resolves names & pulls canonical stats from /api/v1/entities.

get_farming_sources(target)Extracts exact domain schedules & boss drops via /api/v1/farming.

search_lore(query, category)Retrieves 1,239 book volumes, artifact lore & legends via /api/v1/lore/search.

search_knowledge(query)Full-text rank search over chunked documents via /api/v1/knowledge/search.