Filtering & sorting

The API uses structured query parameters — no Lucene-style query DSL, no include=, no field projection. Each filter is a named param.

Filtering

• Equality is the bare param: ?rarity=SR.
• Substring match uses a _contains suffix: ?name_contains=pikachu (case-insensitive).
• There are no range/null/_in operator suffixes in v1.

name_contains matches English names only

name_contains (on cards and Pokémon) matches the English name field only. To match Chinese names — or pinyin for sets and Pokémon — use /v1/search, which is the one endpoint that searches Chinese text.

Unknown parameters fail loudly

The data routes (/v1/cards, /v1/sets, /v1/pokemon, /v1/search, and the price/sales sub-routes) reject unknown query params with 400 unknown_query_param — the details.allowed array names what's accepted. A typo'd or imagined filter errors instead of silently returning unfiltered data, so you find out immediately.

Shared card filter surface

/v1/cards, /v1/sets/{set_id}/cards, and /v1/pokemon/{pokemon_id}/cards share the same card filter/sort surface (only the path-scoped id differs):

Filter	Notes
set_id	On /v1/cards and /v1/pokemon/{id}/cards (fixed by path on /sets/{id}/cards).
card_type	One of pokemon, trainer, supporter, stadium, energy. Trainer-class cards are split: Supporters and Stadiums are their own types; trainer covers the rest (item-style cards).
element	Pokémon energy type: Grass, Fire, Water, Lightning, Psychic, Darkness, Metal, Dragon, Fairy, Colorless. null on non-Pokémon and untyped cards — those never match an element filter.
rarity	Raw Chinese-catalog rarity code: letter codes (C, R, SR, AR, SAR, …), printed corner symbols (●, ◆, ★), or 无标记 ("unmarked"). Responses also carry a human-readable rarity_label ("Super Rare") — filter on rarity, display rarity_label.
name_contains	Substring of the English name (see note above).
has_price	true/false. Hobby+ only — 400 filter_not_available on free.

Sorting

?sort=field ascending, ?sort=-field descending. Allowed sort fields are documented per endpoint. On card listings an unsupported (or tier-gated) field returns 400 invalid_sort with details.allowed_sorts; on /v1/sets and /v1/pokemon the sort value is schema-validated, so an unknown field returns 422 validation_error instead.

Card-listing sort fields are tier-gated:

Sort field	Min tier	Default
card_number	free	✓ (cards)
name	free
price_raw	hobby
price_psa10	pro

card_number is a zero-padded string (e.g. "020"), so the default order is lexicographic — which matches collector order within a set. Rows with a null sort value (e.g. cards without an English name) sort last.

Other endpoints:

• Sets (/v1/sets) — sort by release_date or name. Default -release_date. Filters: series (SunMoon, SwordShield, ScarletViolet) and popular (curated high-interest shortlist).
• Pokémon (/v1/pokemon) — sort by id (national-dex order, default) or name. Filter: name_contains.

See the API Reference in the sidebar for the exact, validated parameter list on each endpoint.