API models

This reference reproduces explicit Pydantic model fields from API modules and the schedule rule used by the admin API. Types/defaults use Python source notation; they are not literal JSON examples. JSON uses null, true and false, and serialized decimals follow the actual OpenAPI schema.

Fields inherited from a model named in “Bases” also apply. A default of “Required” means that the source declares no default; a nullable type can still be required. Internal ConfigDict metadata is excluded. Refer to the deployed /api/openapi.json for exact request/response serialization.

Common aliases: Username is 1–150 characters matching ^[A-Za-z0-9._@-]+$; Password is 8–256 characters; UiLanguage is en, fr, de or es; Fraction is a floating-point value from 0 to 1. Condition values are MT/NM/EX/GD/LP/PL/PO. Job kinds are catalog/prices/images/refresh. Roles are user/admin.

JobOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
game_id	str	Required
kind	JobKind	Required
status	JobStatus	Required
trigger	JobTrigger	Required
started_at	datetime	Required
finished_at	datetime | None	Required
report	dict[str, Any]	Required
error	str | None	Required
elapsed_seconds	int	Required

Model source

ImageImportIn

Bases: BaseModel.

Field	Type	Source default
folder	str	Required

Model source

ImageImportOut

Bases: BaseModel.

Field	Type	Source default
stored	int	Required
missing	int	Required

Model source

LastRunOut

Bases: BaseModel.

Field	Type	Source default
kind	JobKind	Required
status	JobStatus	Required
started_at	datetime	Required
finished_at	datetime | None	Required
error	str | None	Required

Model source

GameStatusOut

Bases: BaseModel.

Field	Type	Source default
game_id	str	Required
runs	list[LastRunOut]	Required

Model source

QuotaOut

Bases: BaseModel.

Field	Type	Source default
source	str	Required
period	Literal['day', 'month']	Required
used	int	Required
limit	int	Required

Model source

OverviewOut

Bases: BaseModel.

Field	Type	Source default
games	list[GameStatusOut]	Required
quotas	list[QuotaOut]	Required

Model source

ScheduleOut

Bases: BaseModel.

Field	Type	Source default
game_id	str	Required
kind	JobKind	Required
next_run_at	datetime	Required
check_seconds	int	Required

Model source

SyncScheduleIn

Bases: BaseModel.

Time zone (IANA name) and one rule per job kind; kinds left out keep their default rule.

Field	Type	Source default
timezone	str	Required
jobs	dict[JobKind, schedule.ScheduleRule]	Required

Model source

SyncScheduleOut

Bases: SyncScheduleIn.

Field	Type	Source default
is_default	bool	Required
default_timezone	str	Required
upcoming	dict[JobKind, list[datetime]]	Required

Model source

ResetOut

Bases: BaseModel.

Field	Type	Source default
printings	int	Required
cards	int	Required
sets	int	Required
kept	int	Required
run_id	int	Required

Model source

DiscrepancyOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
game_id	str	Required
source	str	Required
set_code	str	Required
set_name	str	Required
card_id	int | None	Required
card_name	str | None	Required
collector_number	str | None	Required
field	str	Required
primary_value	str | None	Required
secondary_value	str | None	Required
first_seen	datetime	Required
resolution	Literal['primary', 'secondary', 'custom'] | None	Required
resolved_value	str | None	Required
resolved_at	datetime | None	Required
by_rule	bool	Required

Model source

DiscrepancyCountOut

Bases: BaseModel.

Field	Type	Source default
game_id	str	Required
source	str	Required
field	str	Required
count	int	Required
resolved	int	0
rule	Literal['primary', 'secondary'] | None	None
rule_id	int | None	None

Model source

DiscrepancyPageOut

Bases: BaseModel.

Field	Type	Source default
items	list[DiscrepancyOut]	Required
total	int	Required
counts	list[DiscrepancyCountOut]	Required

Model source

ResolveIn

Bases: BaseModel.

Field	Type	Source default
choice	Literal['primary', 'secondary', 'custom'] | None	Required
value	Annotated[str | None, Field(max_length=500)]	None

Model source

RuleIn

Bases: BaseModel.

Field	Type	Source default
game_id	str	Required
source	str	Required
field	str	Required
prefer	Literal['primary', 'secondary']	Required

Model source

StaleCardOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
game_id	str	Required
name	str	Required
printing_count	int	Required
reasons	list[str]	Required
last_seen_at	datetime | None	Required
refresh_attempted_at	datetime | None	Required

Model source

StalePageOut

Bases: BaseModel.

Field	Type	Source default
items	list[StaleCardOut]	Required
total	int	Required
refreshable	list[str]	Required

Model source

CardRefreshOut

Bases: BaseModel.

Field	Type	Source default
updated	bool	Required
stale	bool	Required

Model source

SetOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
code	str	Required
name	str	Required
lang	str | None	Required
exclusive_lang	str | None	None
release_date	date | None	Required
total	int | None	Required
icon	str | None	Required

Model source

OwnedOut

Bases: BaseModel.

Field	Type	Source default
item_id	int	Required
finish	str	Required
condition	str	Required
language	str	Required
quantity	int	Required

Model source

PriceOut

Bases: BaseModel.

Field	Type	Source default
finish	str	Required
source	str	Required
currency	str	Required
trend	Decimal	Required
low	Decimal | None	Required
date	date	Required

Model source

LinkOut

Bases: BaseModel.

Field	Type	Source default
source	str	Required
name	str	Required
url	str	Required

Model source

PrintingOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
set	SetOut	Required
collector_number	str | None	Required
rarity	str | None	Required
rarity_code	str | None	None
artist	str | None	Required
finishes	list[str]	Required
languages	list[str]	Required
image	str | None	Required
back_image	str | None	None
orientation	str	'portrait'
name	str	''
translation	str | None	None
names	dict[str, str]	Required
attributes	dict[str, Any]	Required
cardmarket_id	int | None	Required
links	list[LinkOut]	Required
prices	list[PriceOut]	Required
owned	list[OwnedOut]	Required

Model source

CardOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
game_id	str	Required
name	str	Required
translation	str | None	None
default_printing_id	int | None	None
names	dict[str, str]	{}
colors	list[str]	Required
attributes	dict[str, Any]	Required
printings	list[PrintingOut]	Required
refreshing	bool	False

Model source

CardSummaryOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
game_id	str	Required
name	str	Required
translation	str | None	None
colors	list[str]	Required
printing_count	int	Required
image	str | None	Required
printing_id	int | None	None
back_image	str | None	None
set	SetOut | None	None
collector_number	str | None	None
rarity	str | None	None
rarity_code	str | None	None
orientation	str	'portrait'
price_min	Decimal | None	Required
price_max	Decimal | None	Required
currency	str | None	None

Model source

CardPageOut

Bases: BaseModel.

Field	Type	Source default
items	list[CardSummaryOut]	Required
total	int	Required
page	int	Required
page_size	int	Required

Model source

PriceHistoryOut

Bases: BaseModel.

Field	Type	Source default
date	date	Required
finish	str	Required
source	str	Required
currency	str	Required
trend	Decimal | None	Required
low	Decimal | None	Required
avg	Decimal | None	Required

Model source

ItemSetOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
code	str	Required
name	str	Required

Model source

TrendOut

Bases: BaseModel.

Field	Type	Source default
direction	Literal['up', 'down', 'flat']	Required
change	float	Required

Model source

TrendsOut

Bases: BaseModel.

Market price trend over 24 hours, 7 days and 30 days (None: not enough history).

Field	Type	Source default
d1	TrendOut | None	None
d7	TrendOut | None	None
d30	TrendOut | None	None

Model source

ItemOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
printing_id	int	Required
card_id	int	Required
game_id	str	Required
name	str	Required
translation	str | None	None
colors	list[str]	Required
set	ItemSetOut	Required
collector_number	str | None	Required
rarity	str | None	Required
rarity_code	str | None	None
image	str | None	Required
back_image	str | None	None
orientation	str	'portrait'
finish	str	Required
condition	str	Required
language	str	Required
quantity	int	Required
manual_price	Decimal | None	Required
market_price	Decimal | None	Required
currency	str	Required
price_date	date | None	Required
unit_price	Decimal | None	Required
total	Decimal | None	Required
trends	TrendsOut	TrendsOut()
notes	str | None	Required
updated_at	datetime	Required

Model source

ItemPageOut

Bases: BaseModel.

Field	Type	Source default
items	list[ItemOut]	Required
total	int	Required
page	int	Required
page_size	int	Required

Model source

AdjustIn

Bases: BaseModel.

Field	Type	Source default
printing_id	int	Required
finish	str	Required
condition	Condition	Condition.NM
language	str	Required
delta	int	Field(ge=-1000, le=1000)
source	Source	'web'

Model source

AdjustOut

Bases: BaseModel.

Field	Type	Source default
item	ItemOut	Required
transaction_id	int	Required

Model source

ItemUpdateIn

Bases: BaseModel.

Field	Type	Source default
quantity	int | None	Field(default=None, ge=0, le=100000)
manual_price	Decimal | None	Field(default=None, ge=0, max_digits=12, decimal_places=2)
notes	str | None	Field(default=None, max_length=1000, pattern='^[^\\x00]*$')

Model source

TransactionOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
item_id	int	Required
delta	int	Required
source	str	Required
undone	bool	Required
created_at	datetime	Required
game_id	str	Required
name	str	Required
translation	str | None	None
set_code	str	Required
finish	str	Required
condition	str	Required
language	str	Required

Model source

GameValueOut

Bases: BaseModel.

Field	Type	Source default
game_id	str	Required
currency	str	Required
total	Decimal	Required
quantity	int	Required
priced	int	Required
unpriced	int	Required

Model source

CurrencyTotalOut

Bases: BaseModel.

Field	Type	Source default
currency	str	Required
total	Decimal	Required

Model source

ValueOut

Bases: BaseModel.

Field	Type	Source default
currency	str	Required
total	Decimal	Required
totals	list[CurrencyTotalOut]	Required
quantity	int	Required
games	list[GameValueOut]	Required

Model source

ValuePointOut

Bases: BaseModel.

Field	Type	Source default
date	date	Required
value	Decimal	Required

Model source

ValueHistoryOut

Bases: BaseModel.

Field	Type	Source default
currency	str	Required
points	list[ValuePointOut]	Required

Model source

ImportErrorOut

Bases: BaseModel.

Field	Type	Source default
line	int	Required
message	str	Required

Model source

ImportOut

Bases: BaseModel.

Field	Type	Source default
rows	int	Required
imported	int	Required
dry_run	bool	Required
errors	list[ImportErrorOut]	Required

Model source

MoverOut

Bases: BaseModel.

Field	Type	Source default
item	ItemOut	Required
change	Decimal	Required

Model source

MoversOut

Bases: BaseModel.

Field	Type	Source default
period	Literal['d1', 'd7', 'd30']	Required
risers	list[MoverOut]	Required
fallers	list[MoverOut]	Required

Model source

ShareOut

Bases: BaseModel.

Field	Type	Source default
key	str	Required
label	str	Required
value	Decimal	Required
quantity	int	Required

Model source

ChangeOut

Bases: BaseModel.

Field	Type	Source default
days	int	Required
past	Decimal | None	Required
now	Decimal	Required

Model source

TopItemOut

Bases: BaseModel.

Field	Type	Source default
item	ItemOut	Required
unit	Decimal	Required
value	Decimal	Required

Model source

FinanceOut

Bases: BaseModel.

Field	Type	Source default
currency	str	Required
value	Decimal	Required
quantity	int	Required
printings	int	Required
priced	int	Required
unpriced	int	Required
average	Decimal | None	Required
median	Decimal | None	Required
other_currencies	list[str]	Required
changes	list[ChangeOut]	Required
history	list[ValuePointOut]	Required
by_game	list[ShareOut]	Required
by_set	list[ShareOut]	Required
by_rarity	list[ShareOut]	Required
by_condition	list[ShareOut]	Required
by_language	list[ShareOut]	Required
by_finish	list[ShareOut]	Required
by_band	list[ShareOut]	Required
top	list[TopItemOut]	Required
top_share	float | None	Required

Model source

ColorOut

Bases: BaseModel.

Field	Type	Source default
code	str	Required
name	str	Required
hex	str	Required
icon	str | None	Required

Model source

RarityOut

Bases: BaseModel.

Field	Type	Source default
code	str	Required
name	str	Required
icon	str | None	Required
icons	dict[str, str]	{}

Model source

FinishOut

Bases: BaseModel.

Field	Type	Source default
code	str	Required
name	str	Required

Model source

PriceSourceOut

Bases: BaseModel.

Field	Type	Source default
id	str	Required
name	str	Required
currency	str	Required

Model source

FilterOut

Bases: BaseModel.

Field	Type	Source default
key	str	Required
label	str	Required

Model source

GameOut

Bases: BaseModel.

Field	Type	Source default
id	str	Required
name	str	Required
group	str	Required
group_name	str	Required
region	str | None	None
region_label	str | None	None
colors	list[ColorOut]	Required
finishes	list[FinishOut]	Required
rarities	list[RarityOut]	[]
languages	list[str]	Required
filters	list[FilterOut]	Required
price_sources	list[PriceSourceOut]	Required
has_prices	bool	Required
cardmarket	str | None	Required
legal_notice	str | None	None

Model source

OcrLineIn

Bases: BaseModel.

Field	Type	Source default
text	Annotated[str, StringConstraints(max_length=300)]	Required
left	Fraction | None	None
top	Fraction | None	None
width	Fraction | None	None
height	Fraction | None	None

Model source

IdentifyIn

Bases: BaseModel.

Field	Type	Source default
game	str | None	None
lines	list[OcrLineIn]	Field(max_length=200)

Model source

HintsOut

Bases: BaseModel.

Field	Type	Source default
name	str | None	Required
set_code	str | None	Required
collector_number	str | None	Required
lang	str | None	Required

Model source

CandidateCardOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
game_id	str	Required
name	str	Required
translation	str | None	None
colors	list[str]	Required

Model source

CandidateOut

Bases: BaseModel.

Field	Type	Source default
score	float	Required
match	str	Required
card	CandidateCardOut	Required
printings	list[PrintingOut]	Required
printing_count	int	Required

Model source

IdentifyOut

Bases: BaseModel.

Field	Type	Source default
game_id	str | None	Required
detected	HintsOut	Required
candidates	list[CandidateOut]	Required
fetched	bool	False
status	Literal['found', 'not_found', 'other_game', 'not_a_card']	'found'
detected_game	str | None	None

Model source

IdentityOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
provider	str	Required
email	str | None	Required

Model source

UserOut

Bases: BaseModel.

Field	Type	Source default
id	int	Required
username	str	Required
email	str | None	Required
role	Role	Required
disabled	bool	Required
has_password	bool	Required
sso	bool	False
role_managed_by_sso	bool	False

Model source

SsoAccountOut

Bases: BaseModel.

Identity provider managing an SSO user's password and email.

Field	Type	Source default
provider	str	Required
display_name	str	Required
account_url	str | None	Required

Model source

MeOut

Bases: UserOut.

Field	Type	Source default
identities	list[IdentityOut]	Required
sso_account	SsoAccountOut | None	None
language	UiLanguage	Required
catalog_games	list[str] | None	Required
price_source	str	Required
price_sources	list[str]	Required

Model source

SettingsIn

Bases: BaseModel.

Fields left out are not changed. catalog_games: null shows every game.

Field	Type	Source default
language	UiLanguage | None	None
catalog_games	list[str] | None	None
price_source	str | None	None
price_sources	list[str] | None	None

Model source

TokenOut

Bases: BaseModel.

Token mode (mobile). Cookie mode (web) only gets the user back.

Field	Type	Source default
access_token	str	Required
refresh_token	str	Required
token_type	Literal['bearer']	'bearer'
expires_in	int	Required

Model source

LoginIn

Bases: BaseModel.

Field	Type	Source default
username	str	Field(max_length=150)
password	str	Field(max_length=256)
mode	Literal['token', 'cookie']	'token'

Model source

RefreshIn

Bases: BaseModel.

Field	Type	Source default
refresh_token	str | None	None

Model source

OidcExchangeIn

Bases: BaseModel.

Field	Type	Source default
id_token	str	Required
nonce	str	Required
access_token	str | None	None

Model source

ProviderOut

Bases: BaseModel.

Field	Type	Source default
name	str	Required
display_name	str	Required
issuer	str	Required
mobile_client_id	str | None	Required
scopes	list[str]	Required
account_url	str | None	None

Model source

ProvidersOut

Bases: BaseModel.

Field	Type	Source default
local_login_enabled	bool	Required
providers	list[ProviderOut]	Required

Model source

EmailChangeIn

Bases: BaseModel.

Field	Type	Source default
email	EmailStr | None	Required
current_password	str | None	None

Model source

PasswordChangeIn

Bases: BaseModel.

Field	Type	Source default
current_password	str | None	None
new_password	Password	Required

Model source

UserCreateIn

Bases: BaseModel.

Field	Type	Source default
username	Username	Required
password	Password | None	None
email	EmailStr | None	None
role	Role	Role.user

Model source

UserUpdateIn

Bases: BaseModel.

Field	Type	Source default
email	EmailStr | None	None
role	Role | None	None
disabled	bool | None	None
password	Password | None	None

Model source

MaintenanceOut

Bases: BaseModel.

A catalog refresh slows the server down: users wait, administrators pass.

Field	Type	Source default
since	datetime	Required
game_id	str	Required

Model source

HealthOut

Bases: BaseModel.

Field	Type	Source default
status	str	'ok'
version	str	Required
maintenance	MaintenanceOut | None	None

Model source

ScheduleRule

Bases: BaseModel.

When one job kind runs. interval: every_hours after the last run started. Other modes: at each of times (local "HH:MM") every day (daily), on weekdays (0 Monday .. 6 Sunday, weekly) or on month_day (monthly).

Field	Type	Source default
mode	Literal['interval', 'daily', 'weekly', 'monthly']	'interval'
every_hours	int	Field(24, ge=1, le=31 * 24)
times	list[str]	Field(default_factory=lambda: ['03:00'], min_length=1, max_length=24)
weekdays	list[int]	Field(default_factory=lambda: [0], min_length=1, max_length=7)
month_day	int	Field(1, ge=1, le=28)

Model source