DotGG Public API Documentation

Base URL: https://api.dotgg.gg

All responses are in JSON format. The API is read-only for public endpoints (write operations require authentication).

---

Quick Reference

Card Game Endpoints

Endpoint	Description	Method
/cgfw/getcards	Get all cards	GET
/cgfw/getcardsfiltered	Search/filter cards with pagination	GET
/cgfw/getsets	Get all card sets	GET
/cgfw/getdeck	Get single deck	GET
/cgfw/getdecks	Search/list decks	GET
/cgfw/getarchetypes	Get deck archetypes	GET
/cgfw/getcardprices	Get card price history	GET

Gacha/RPG Game Endpoints

Endpoint	Description	Method
/cgfw/getcharacters	Get all characters	GET
/cgfw/getcharacter	Get single character details	GET
/cgfw/getgacha	Get game data (items, weapons, etc.)	GET

---

Required Parameter

All endpoints require the game parameter to specify which game's data you want:

?game=lorcana
?game=magic
?game=pokemon
?game=onepiece
?game=yugioh
?game=fabtcg
?game=starwars
?game=afk-journey
?game=wuthering-waves
...etc

---

Endpoints

1. Get Cards

Retrieves all cards for a game. Returns the complete card database in a single response.

Endpoint: GET /cgfw/getcards

Parameters:	Parameter	Type	Description
game	string	Required. Game identifier
mode	string	Optional. indexed for compressed format, gzip-indexed for gzip+indexed, gzip for gzip, plain (default) for standard JSON array

Note: This endpoint returns all cards for a game. It does not support filtering by name, set, or other card attributes. To search/filter cards, use /cgfw/getcardsfiltered instead.

Example Request:

https://api.dotgg.gg/cgfw/getcards?game=lorcana
https://api.dotgg.gg/cgfw/getcards?game=cookierun&mode=indexed&cache=6

Example Response (Plain Mode):

[
  {
    "id": "001-001",
    "name": "Ariel - On Human Legs",
    "cost": "4",
    "rarity": "Super Rare",
    "set_id": "TFC",
    "image": "cards/001-001.webp",
    "type": "Character"
  }
]

Indexed Mode Response: Returns a compressed format with field names array and data array to reduce payload size. This is recommended for large card databases as it significantly reduces response size.

{
  "names": ["id", "name", "cost", "rarity", "set_id", "image", "type"],
  "data": [
    [
      "001-001",
      "Ariel - On Human Legs",
      "4",
      "Super Rare",
      "TFC",
      "cards/001-001.webp",
      "Character"
    ],
    ["001-002", "Another Card", "3", "Common", "TFC", "cards/001-002.webp", "Action"]
  ]
}

To reconstruct card objects from indexed format:

const response = await fetch(
  "https://api.dotgg.gg/cgfw/getcards?game=cookierun&mode=indexed&cache=6"
);
const data = await response.json();

const cards = data.data.map((cardArray) => {
  const card = {};
  data.names.forEach((fieldName, index) => {
    card[fieldName] = cardArray[index];
  });
  return card;
});

---

2. Get Cards Filtered

Searches and filters cards with pagination. Unlike getcards which returns everything, this endpoint supports filtering by set, color, cost, rarity, type, text search, and more.

Endpoint: GET /cgfw/getcardsfiltered

Parameters:	Parameter	Type	Description
game	string	Required. Game identifier
mode	string	Optional. Output format: indexed, gzip-indexed, gzip, or plain (default)
rq	string	Required. URL-encoded JSON filter object

Filter Object Structure:

{
  "setId": "",
  "color": "",
  "cost": "",
  "rarity": "",
  "type": "",
  "textSearch": "",
  "sortby": "name",
  "sortorder": "",
  "page": 0,
  "clear": "",
  "usdprice": "",
  "inCollection": ""
}

Filter Object Fields:

Field	Type	Description
setId	string	Filter by set ID. Comma-separated for multiple (OR logic)
color	string	Filter by color/faction. Comma-separated for multiple (AND logic)
cost	int	Filter by cost/mana (matches within range of ±1)
rarity	string	Filter by rarity. Comma-separated for multiple (OR logic)
type	string	Filter by card type. Comma-separated for multiple (OR logic)
textSearch	string	Full-text search across card name, effect text, and ID (minimum 3 characters)
sortby	string	Sort field (game-specific, common values: name, cost, number, rarity)
sortorder	string	r for descending, empty/other for ascending
page	int	Page number (0-based). Each page returns up to 200 cards
clear	string	When non-empty, clears all filters and returns unfiltered results
usdprice	float	Minimum USD price filter
inCollection	int	1 to show only cards in user's collection (requires authentication)
legalities	string	Format legality filter (game-specific, e.g. standard, modern)

Note: Some filter fields are game-specific. The legalities field is only available for games that have format legality tracking (e.g., Magic). The exact fields returned in the response depend on the game.

Example Request:

const filters = {
  setId: "TFC",
  color: "",
  cost: "",
  rarity: "Super Rare",
  type: "",
  textSearch: "",
  sortby: "name",
  sortorder: "",
  page: 0,
  clear: "",
  usdprice: "",
  inCollection: "",
};

const url = `https://api.dotgg.gg/cgfw/getcardsfiltered?game=lorcana&rq=${encodeURIComponent(JSON.stringify(filters))}`;
const response = await fetch(url);
const cards = await response.json();

Example Response:

[
  {
    "id": "001-003",
    "slug": "ariel-on-human-legs",
    "name": "Ariel - On Human Legs",
    "cost": "4",
    "rarity": "Super Rare",
    "set_id": "TFC",
    "type": "Character",
    "price": 2.5
  }
]

---

3. Get Sets

Retrieves all card sets/expansions for a game.

Endpoint: GET /cgfw/getsets

Parameters:	Parameter	Type	Description
game	string	Required. Game identifier

Example Request:

https://api.dotgg.gg/cgfw/getsets?game=lorcana

Example Response:

[
  {
    "id": "TFC",
    "name": "The First Chapter",
    "displayId": "1",
    "cardsCount": 204,
    "releaseDate": "2023-08-18"
  },
  {
    "id": "ROF",
    "name": "Rise of the Floodborn",
    "displayId": "2",
    "cardsCount": 204,
    "releaseDate": "2023-11-17"
  }
]

---

4. Get Single Deck

Retrieves detailed information about a specific deck.

Endpoint: GET /cgfw/getdeck

Parameters:	Parameter	Type	Description
game	string	Required. Game identifier
slug	string	Required. Deck slug or numeric ID
mode	string	Optional. boards to get cards grouped by board (main/sideboard)

Example Request:

https://api.dotgg.gg/cgfw/getdeck?game=lorcana&slug=my-awesome-deck-abc123
https://api.dotgg.gg/cgfw/getdeck?game=magic&slug=12345&mode=boards

Example Response:

{
  "id": 12345,
  "name": "my-awesome-deck",
  "humanname": "My Awesome Deck",
  "author": 1,
  "authornick": "PlayerName",
  "description": "Deck description here",
  "slug": "my-awesome-deck-abc123",
  "date": "2024-01-15 10:30:00",
  "date_edited": "2024-01-16 14:20:00",
  "format": "standard",
  "views": "1234",
  "public": "1",
  "deck": {
    "001-001": 4,
    "001-002": 3,
    "002-015": 2
  },
  "sideboard": {
    "003-001": 2
  },
  "price": 125.5,
  "priceeur": 115.0
}

Note: The deck object contains card IDs as keys and quantities as values.

---

5. Get Decks (List/Search)

Retrieves a list of decks with filtering and pagination.

Endpoint: GET /cgfw/getdecks

Parameters:	Parameter	Type	Description
game	string	Required. Game identifier
rq	string	Required. URL-encoded JSON request object

Request Object Structure:

{
  "page": 1,
  "limit": 30,
  "srt": "date",
  "direct": "desc",
  "type": "",
  "my": 0,
  "myarchive": 0,
  "fav": 0,
  "getdecks": {
    "hascrd": [],
    "nothascrd": [],
    "youtube": 0,
    "smartsrch": "",
    "date": "",
    "color": [],
    "collection": 0,
    "topset": "",
    "at": 0,
    "format": "",
    "is_tournament": ""
  }
}

Request Object Fields:

Field	Type	Description
page	int	Page number (1-based)
limit	int	Results per page (max 30)
srt	string	Sort field: date, views, name
direct	string	Sort direction: asc or desc
type	string	Deck type filter
my	int	User ID to show only their decks (0 = all)
getdecks.hascrd	array	Filter decks containing these card IDs
getdecks.nothascrd	array	Exclude decks with these card IDs
getdecks.youtube	int	1 = only decks with video
getdecks.smartsrch	string	Search in deck names
getdecks.color	array	Filter by colors/factions
getdecks.format	string	Filter by format (standard, etc.)
getdecks.at	int/string	Filter by archetype ID/slug
getdecks.is_tournament	string	"1" for tournament decks only

Example Request:

// Build the request
const request = {
  page: 1,
  limit: 30,
  srt: "date",
  direct: "desc",
  type: "",
  my: 0,
  myarchive: 0,
  fav: 0,
  getdecks: {
    hascrd: [],
    nothascrd: [],
    youtube: 0,
    smartsrch: "",
    date: "",
    color: [],
    collection: 0,
    topset: "",
    at: 0,
    format: "",
    is_tournament: "",
  },
};

// Make the request
const url = `https://api.dotgg.gg/cgfw/getdecks?game=lorcana&rq=${encodeURIComponent(JSON.stringify(request))}`;
fetch(url)
  .then((res) => res.json())
  .then((decks) => console.log(decks));

Example Response:

[
  {
    "id": 12345,
    "name": "deck-slug",
    "humanname": "Deck Name",
    "author": 1,
    "authornick": "PlayerName",
    "date": "2024-01-15",
    "format": "standard",
    "views": "500",
    "price": 89.99
  }
]

---

6. Get Archetypes

Retrieves deck archetypes/meta categories for a game.

Endpoint: GET /cgfw/getarchetypes

Parameters:	Parameter	Type	Description
game	string	Required. Game identifier

Example Request:

https://api.dotgg.gg/cgfw/getarchetypes?game=lorcana

Example Response:

[
  {
    "id": 1,
    "name": "Amber/Steel Midrange",
    "slug": "amber-steel-midrange",
    "cards": {
      "001-001": 4,
      "002-015": 3
    }
  }
]

---

7. Get Card Prices

Retrieves price history for a specific card.

Endpoint: GET /cgfw/getcardprices

Parameters:	Parameter	Type	Description
game	string	Required. Game identifier
cardid	string	Required. Card ID
timepattern	string	Time range: w (week), m (month), 2m, 3m, 4m, 5m, 6m, y (year)
fromdate	string	Start date (YYYYMMDD or Unix timestamp)
todate	string	End date (YYYYMMDD or Unix timestamp), defaults to now

Example Request:

https://api.dotgg.gg/cgfw/getcardprices?game=lorcana&cardid=001-001&timepattern=m
https://api.dotgg.gg/cgfw/getcardprices?game=magic&cardid=abc123&fromdate=20240101&todate=20240131

---

Gacha/RPG Game Endpoints

These endpoints are available for gacha and RPG games like Zenless Zone Zero, Wuthering Waves, AFK Journey, etc.

8. Get Characters

Retrieves all characters for a gacha game with their stats, skills, and tier ratings.

Endpoint: GET /cgfw/getcharacters

Parameters:	Parameter	Type	Description
game	string	Required. Game identifier

Example Request:

https://api.dotgg.gg/cgfw/getcharacters?game=zenless
https://api.dotgg.gg/cgfw/getcharacters?game=wuthering-waves
https://api.dotgg.gg/cgfw/getcharacters?game=afk-journey

Example Response:

[
  {
    "id": 1,
    "name": "Character Name",
    "slug": "character-name",
    "rarity": "S",
    "element": "Fire",
    "image": "big-heroes/character-name.webp",
    "skills": [],
    "tiers": {
      "pve": "S",
      "pvp": "A"
    },
    "tiersEval": {
      "pve": "Great for boss fights...",
      "pvp": "Decent in arena..."
    }
  }
]

---

9. Get Single Character

Retrieves detailed information about a specific character.

Endpoint: GET /cgfw/getcharacter

Parameters:	Parameter	Type	Description
game	string	Required. Game identifier
slug	string	Required. Character slug/URL identifier

Example Request:

https://api.dotgg.gg/cgfw/getcharacter?game=zenless&slug=ellen
https://api.dotgg.gg/cgfw/getcharacter?game=wuthering-waves&slug=rover

Example Response:

{
  "id": 1,
  "name": "Ellen",
  "slug": "ellen",
  "rarity": "S",
  "element": "Ice",
  "faction": "Victoria Housekeeping",
  "skills": [
    {
      "name": "Basic Attack",
      "description": "..."
    }
  ],
  "stats": {
    "hp": 1000,
    "atk": 500,
    "def": 300
  }
}

---

10. Get Gacha Data

Generic endpoint for retrieving various game data tables like items, weapons, equipment, etc.

Endpoint: GET /cgfw/getgacha

Parameters:	Parameter	Type	Description
game	string	Required. Game identifier
type	string	Required. Data type to retrieve (game-specific)

Available Types by Game:

Game	Available Types
zenless	characters, wengines, bangboos, diskdrives, items
wuthering-waves	characters, weapons, echoes, items
afk-journey	characters, artifacts, items
rivals	characters, shop, battlepasses
pokepocket	missions
endfield	recipes, achievements

Example Request:

https://api.dotgg.gg/cgfw/getgacha?game=zenless&type=wengines
https://api.dotgg.gg/cgfw/getgacha?game=zenless&type=bangboos
https://api.dotgg.gg/cgfw/getgacha?game=rivals&type=shop

Example Response (W-Engines):

[
  {
    "id": 1,
    "name": "Steel Cushion",
    "rarity": "S",
    "type": "Attack",
    "primaryStat": {},
    "secondaryStat": {},
    "tiers": {
      "ellen": "S",
      "lycaon": "A"
    }
  }
]

---

Caching

For better performance and to reduce server load, add a cache parameter:

Option 1: Use Data Version (Recommended)

Each game has a data version number that increments when card data is updated. Get the current version from:

https://butterfly.dotgg.gg/?game=cookierun
https://butterfly.dotgg.gg/?game=lorcana
https://butterfly.dotgg.gg/?game=magic

This returns a simple number (e.g., 6). Use it as the cache value:

https://api.dotgg.gg/cgfw/getcards?game=cookierun&mode=indexed&cache=6

This ensures you get cached responses until we update the card database, then automatically get fresh data.

Option 2: Use Timestamp

Alternatively, use a timestamp that changes periodically:

https://api.dotgg.gg/cgfw/getcards?game=lorcana&cache=1706500000000

Tip: Round timestamps to reduce cache misses (e.g., to nearest hour or day).

---

Rate Limiting

Please be respectful of our API:

• Don't make more than 1 request per second
• Cache responses on your end when possible
• Use the cache parameter for frequently-accessed data

---

Code Examples

JavaScript/Fetch

// Get all cards
async function getCards(game) {
  const response = await fetch(`https://api.dotgg.gg/cgfw/getcards?game=${game}`);
  return response.json();
}

// Search/filter cards
async function searchCards(
  game,
  { setId = "", color = "", rarity = "", textSearch = "", page = 0 } = {}
) {
  const filters = {
    setId,
    color,
    cost: "",
    rarity,
    type: "",
    textSearch,
    sortby: "name",
    sortorder: "",
    page,
    clear: "",
    usdprice: "",
    inCollection: "",
  };

  const url = `https://api.dotgg.gg/cgfw/getcardsfiltered?game=${game}&rq=${encodeURIComponent(JSON.stringify(filters))}`;
  const response = await fetch(url);
  return response.json();
}

// Get a specific deck
async function getDeck(game, slug) {
  const response = await fetch(`https://api.dotgg.gg/cgfw/getdeck?game=${game}&slug=${slug}`);
  return response.json();
}

// Search decks
async function searchDecks(game, searchTerm) {
  const request = {
    page: 1,
    limit: 30,
    srt: "date",
    direct: "desc",
    type: "",
    my: 0,
    myarchive: 0,
    fav: 0,
    getdecks: {
      hascrd: [],
      nothascrd: [],
      youtube: 0,
      smartsrch: searchTerm,
      date: "",
      color: [],
      collection: 0,
      topset: "",
      at: 0,
      format: "",
      is_tournament: "",
    },
  };

  const url = `https://api.dotgg.gg/cgfw/getdecks?game=${game}&rq=${encodeURIComponent(JSON.stringify(request))}`;
  const response = await fetch(url);
  return response.json();
}

// Usage
const cards = await getCards("lorcana");
const filteredCards = await searchCards("riftbound", { color: "Fury", rarity: "Rare" });
const deck = await getDeck("lorcana", "my-deck-slug");
const decks = await searchDecks("lorcana", "aggro");

Python

import requests
import json
from urllib.parse import quote

BASE_URL = "https://api.dotgg.gg"

def get_cards(game):
    response = requests.get(f"{BASE_URL}/cgfw/getcards?game={game}")
    return response.json()

def search_cards(game, set_id="", color="", rarity="", text_search="", page=0):
    filters = {
        "setId": set_id,
        "color": color,
        "cost": "",
        "rarity": rarity,
        "type": "",
        "textSearch": text_search,
        "sortby": "name",
        "sortorder": "",
        "page": page,
        "clear": "",
        "usdprice": "",
        "inCollection": ""
    }

    url = f"{BASE_URL}/cgfw/getcardsfiltered?game={game}&rq={quote(json.dumps(filters))}"
    response = requests.get(url)
    return response.json()

def get_deck(game, slug):
    response = requests.get(f"{BASE_URL}/cgfw/getdeck?game={game}&slug={slug}")
    return response.json()

def search_decks(game, search_term=""):
    request = {
        "page": 1,
        "limit": 30,
        "srt": "date",
        "direct": "desc",
        "type": "",
        "my": 0,
        "myarchive": 0,
        "fav": 0,
        "getdecks": {
            "hascrd": [],
            "nothascrd": [],
            "youtube": 0,
            "smartsrch": search_term,
            "date": "",
            "color": [],
            "collection": 0,
            "topset": "",
            "at": 0,
            "format": "",
            "is_tournament": ""
        }
    }

    url = f"{BASE_URL}/cgfw/getdecks?game={game}&rq={quote(json.dumps(request))}"
    response = requests.get(url)
    return response.json()

# Usage
cards = get_cards('lorcana')
filtered = search_cards('riftbound', color='Fury', rarity='Rare')
deck = get_deck('lorcana', 'my-deck-slug')
decks = search_decks('lorcana', 'aggro')

---

Supported Games

Card Games (TCG/CCG)

Use /cgfw/getcards, /cgfw/getcardsfiltered, /cgfw/getsets, /cgfw/getdecks, /cgfw/getdeck, /cgfw/getarchetypes, /cgfw/getcardprices

Game ID	Website
lorcana	lorcana.gg
magic	playingmtg.com
pokemon	pokemontcgzone.com
pokepocket	ptcgpocket.gg
yugioh	ygozone.com
onepiece	onepiece.gg
fabtcg	fabtcg.gg
riftbound	riftbound.gg
starwars	starwarsunlimited.gg
dragonball	dragonball.gg
shadowverse	shadowverse.gg
gundam	gundamcard.gg
sorcery	sorcerytcg.gg

Gacha/RPG Games

Use /cgfw/getcharacters, /cgfw/getcharacter, /cgfw/getgacha

Game ID	Website
zenless	zenless.gg
wuthering-waves	wutheringwaves.gg
afk-journey	afkjourney.gg
snowbreak	snowbreak.gg
endfield	endfield.gg
umamusume	umamusume.gg
cookierun	cookierun.gg

Hybrid Games (Cards + Characters)

These games support both card and gacha endpoints.

Game ID	Website
marvelsnap	marvelsnap.gg
rivals	marvelrivals.gg
thebazaar	thebazaarzone.com

---

Questions?

Join our Discord community for API support and discussions.

---

Last updated: March 2026