API endpoints

Source-derived endpoint reference for the documented commit. Prefix /api is included below. Parameter types use Python source notation, not JSON syntax. CurrentUser/AdminUser and SessionDep are injected dependencies, not request fields. An Annotated type can contain FastAPI Query or File constraints.

Defaults and response annotations are reproduced from route definitions. For full serialization, aliases and inherited fields, use your instance's /api/openapi.json. See API guide for authentication, examples, pagination and error handling and API models for model fields.

Admin

GET /api/admin/jobs

Access: Administrator. Declared success status: 200. Response: list[JobOut].

Parameter	Source type	Default
game	str | None	None
limit	int	50

Route source

GET /api/admin/overview

Access: Administrator. Declared success status: 200. Response: OverviewOut.

Data sync at a glance: latest run of each job per game, quotas used this period.

Route source

GET /api/admin/schedule

Access: Administrator. Declared success status: 200. Response: list[ScheduleOut].

Next automatic run of every job the worker runs.

Route source

GET /api/admin/sync-schedule

Access: Administrator. Declared success status: 200. Response: SyncScheduleOut.

When the worker runs each job kind (every game).

Route source

PUT /api/admin/sync-schedule

Access: Administrator. Declared success status: 200. Response: SyncScheduleOut.

Save the schedule. Set times already passed are not caught up: a job set to run daily at 04:00 saved at 10:00 runs first tomorrow at 04:00.

Parameter	Source type	Default
body	SyncScheduleIn	Required / dependency-defined

Route source

DELETE /api/admin/sync-schedule

Access: Administrator. Declared success status: 200. Response: SyncScheduleOut.

Back to the TCG_*_INTERVAL_HOURS defaults.

Route source

POST /api/admin/sync-schedule/preview

Access: Administrator. Declared success status: 200. Response: SyncScheduleOut.

Next set times of a schedule being edited, without saving it.

Parameter	Source type	Default
body	SyncScheduleIn	Required / dependency-defined

Route source

POST /api/admin/jobs/{game_id}/{kind}

Access: Administrator. Declared success status: 202_ACCEPTED. Response: dict[str, int].

Queue a run for the worker, which takes over a running automatic run of the same job.

Parameter	Source type	Default
game_id	str	Required / dependency-defined
kind	JobKind	Required / dependency-defined

Route source

POST /api/admin/games/{game_id}/reset

Access: Administrator. Declared success status: 200. Response: ResetOut.

Delete the game's catalog except owned printings, then queue its sync.

Parameter	Source type	Default
game_id	str	Required / dependency-defined

Route source

GET /api/admin/import-folders

Access: Administrator. Declared success status: 200. Response: list[str].

Route source

POST /api/admin/images/{game_id}/import

Access: Administrator. Declared success status: 200. Response: ImageImportOut.

Parameter	Source type	Default
game_id	str	Required / dependency-defined
body	ImageImportIn	Required / dependency-defined

Route source

GET /api/admin/discrepancies

Access: Administrator. Declared success status: 200. Response: DiscrepancyPageOut.

Where secondary catalog sources disagree with the primary one (kept unless arbitrated).

Parameter	Source type	Default
game	str | None	None
source	str | None	None
field	str | None	None
state	Literal['open', 'resolved', 'all']	'open'
page	Annotated[int, Query(ge=1)]	1
page_size	Annotated[int, Query(ge=1, le=200)]	50

Route source

POST /api/admin/discrepancies/{discrepancy_id}/resolve

Access: Administrator. Declared success status: 200. Response: dict[str, int].

Arbitrate one discrepancy; the value chosen is written at once and kept after every later sync.

Parameter	Source type	Default
discrepancy_id	int	Required / dependency-defined
body	ResolveIn	Required / dependency-defined

Route source

PUT /api/admin/discrepancies/rules

Access: Administrator. Declared success status: 200. Response: dict[str, int].

Prefer one side for every discrepancy of this game, source and field, the open ones and those found later (single arbitrations of that field are replaced).

Parameter	Source type	Default
body	RuleIn	Required / dependency-defined

Route source

DELETE /api/admin/discrepancies/rules/{rule_id}

Access: Administrator. Declared success status: 204_NO_CONTENT. Response: See deployed OpenAPI schema.

Remove a rule: the discrepancies it resolved are open again.

Parameter	Source type	Default
rule_id	int	Required / dependency-defined

Route source

GET /api/admin/stale

Access: Administrator. Declared success status: 200. Response: StalePageOut.

Cards whose data is outdated or incomplete (see app.services.refresh).

Parameter	Source type	Default
game	str | None	None
page	Annotated[int, Query(ge=1)]	1
page_size	Annotated[int, Query(ge=1, le=200)]	50

Route source

POST /api/admin/cards/{card_id}/refresh

Access: Administrator. Declared success status: 200. Response: CardRefreshOut.

Fetch one card again from its game's source now.

Parameter	Source type	Default
card_id	int	Required / dependency-defined

Route source

Auth

GET /api/auth/providers

Access: Public/authentication flow. Declared success status: 200. Response: ProvidersOut.

Route source

POST /api/auth/login

Access: Public/authentication flow. Declared success status: 200. Response: TokenOut | UserOut.

Parameter	Source type	Default
body	LoginIn	Required / dependency-defined

Route source

POST /api/auth/refresh

Access: Public/authentication flow. Declared success status: 200. Response: TokenOut | UserOut.

Parameter	Source type	Default
body	RefreshIn	Required / dependency-defined

Route source

POST /api/auth/logout

Access: Public/authentication flow. Declared success status: 200. Response: See deployed OpenAPI schema.

Parameter	Source type	Default
body	RefreshIn	Required / dependency-defined

Route source

GET /api/auth/me

Access: Authenticated user. Declared success status: 200. Response: MeOut.

Route source

PATCH /api/auth/me

Access: Authenticated user. Declared success status: 200. Response: MeOut.

Parameter	Source type	Default
body	SettingsIn	Required / dependency-defined

Route source

POST /api/auth/email

Access: Authenticated user. Declared success status: 200. Response: MeOut.

Change the account's email address. Refused for SSO users: their identity provider manages it (copied on every SSO login).

Parameter	Source type	Default
body	EmailChangeIn	Required / dependency-defined

Route source

POST /api/auth/password

Access: Authenticated user. Declared success status: 204_NO_CONTENT. Response: See deployed OpenAPI schema.

Change the password and end every session. A browser gets a new session at once; token clients (the app) sign in again. Refused for SSO users: their identity provider manages it (SSO and local accounts are separate).

Parameter	Source type	Default
body	PasswordChangeIn	Required / dependency-defined

Route source

GET /api/auth/oidc/{provider}/login

Access: Public/authentication flow. Declared success status: 200. Response: See deployed OpenAPI schema.

Start browser SSO. SSO and local accounts are separate: an SSO login never joins a local account.

Parameter	Source type	Default
provider	str	Required / dependency-defined
next	str	'/'

Route source

GET /api/auth/oidc/{provider}/callback

Access: Public/authentication flow. Declared success status: 200. Response: See deployed OpenAPI schema.

Parameter	Source type	Default
provider	str	Required / dependency-defined
code	str | None	None
state	str | None	None
error	str | None	None
error_description	str | None	None

Route source

POST /api/auth/oidc/{provider}/exchange

Access: Public/authentication flow. Declared success status: 200. Response: TokenOut.

Mobile SSO: the app ran authorization code + PKCE itself (AppAuth) and hands over the ID token. Only the provider's mobile client is accepted as audience.

Parameter	Source type	Default
provider	str	Required / dependency-defined
body	OidcExchangeIn	Required / dependency-defined

Route source

Catalog

GET /api/sets/{set_id}/icon

Access: Authenticated user. Declared success status: 200. Response: FileResponse.

Parameter	Source type	Default
set_id	int	Required / dependency-defined

Route source

GET /api/games/{game_id}/sets

Access: Authenticated user. Declared success status: 200. Response: list[SetOut].

Parameter	Source type	Default
game_id	str	Required / dependency-defined

Route source

GET /api/cards

Access: Authenticated user. Declared success status: 200. Response: CardPageOut.

Search cards by name in any language (substring match, case and accents ignored), set and colors. Exact name matches come first, then names starting with q. Without game, only the games chosen in the user's settings are searched.

attr=<filter key>:<value> (repeatable, all must match) uses the game's advanced filters (GameOut.filters); it needs game.

color_mode=exact: cards of exactly the chosen colors (default: at least them). sort=name orders by shown name, sort=number by collector number in set_id (ignored without a set); order gives the direction.

Parameter	Source type	Default
game	str | None	None
q	Annotated[str | None, Query(max_length=200)]	None
set_id	int | None	None
color	Annotated[list[str] | None, Query()]	None
lang	Annotated[str | None, Query(max_length=8)]	None
attr	Annotated[list[str] | None, Query(max_length=200)]	None
color_mode	Literal['include', 'exact']	'include'
sort	Literal['relevance', 'name', 'number']	'relevance'
order	Literal['asc', 'desc']	'asc'
page	Annotated[int, Query(ge=1)]	1
page_size	Annotated[int, Query(ge=1, le=200)]	50

Route source

GET /api/cards/{card_id}

Access: Authenticated user. Declared success status: 200. Response: CardOut.

Parameter	Source type	Default
card_id	int	Required / dependency-defined
background	BackgroundTasks	Required / dependency-defined

Route source

GET /api/cards/{card_id}/printings

Access: Authenticated user. Declared success status: 200. Response: list[PrintingOut].

The card's printings whose set name, set code, collector number or release year contain every word of q (case and accents ignored), newest first.

Parameter	Source type	Default
card_id	int	Required / dependency-defined
q	Annotated[str | None, Query(max_length=100)]	None
limit	Annotated[int, Query(ge=1, le=200)]	50

Route source

GET /api/printings/{printing_id}/prices

Access: Authenticated user. Declared success status: 200. Response: list[PriceHistoryOut].

Price snapshots from the user's sources, oldest first. Full history exists for printings in a collection.

Parameter	Source type	Default
printing_id	int	Required / dependency-defined
days	Annotated[int, Query(ge=1, le=3650)]	365

Route source

GET /api/printings/{printing_id}/image

Access: Authenticated user. Declared success status: 200. Response: FileResponse.

Card image in lang (default: the user's language), else English, else Japanese, else any language there is. face=back: the back of double-faced cards.

Parameter	Source type	Default
printing_id	int	Required / dependency-defined
lang	Annotated[str | None, Query(max_length=8)]	None
face	Literal['front', 'back']	'front'

Route source

Collection

GET /api/collection

Access: Authenticated user. Declared success status: 200. Response: ItemPageOut.

The current user's items with resolved prices.

Parameter	Source type	Default
game	str | None	None
q	Annotated[str | None, Query(max_length=200)]	None
set_id	int | None	None
color	Annotated[list[str] | None, Query()]	None
color_mode	Literal['include', 'exact']	'include'
finish	str | None	None
condition	Condition | None	None
language	str | None	None
include_empty	bool	False
sort	Literal['name', 'set', 'updated', 'quantity', 'price_asc', 'price_desc']	'name'
page	Annotated[int, Query(ge=1)]	1
page_size	Annotated[int, Query(ge=1, le=500)]	50

Route source

POST /api/collection/adjust

Access: Authenticated user. Declared success status: 200. Response: AdjustOut.

Add (positive delta) or remove (negative delta) copies of a printing variant.

Parameter	Source type	Default
body	AdjustIn	Required / dependency-defined

Route source

GET /api/collection/items/{item_id}

Access: Authenticated user. Declared success status: 200. Response: ItemOut.

Parameter	Source type	Default
item_id	int	Required / dependency-defined

Route source

PATCH /api/collection/items/{item_id}

Access: Authenticated user. Declared success status: 200. Response: ItemOut.

Set quantity (recorded as a stock change), manual price or notes. Send manual_price: null to go back to API prices.

Parameter	Source type	Default
item_id	int	Required / dependency-defined
body	ItemUpdateIn	Required / dependency-defined

Route source

DELETE /api/collection/items/{item_id}

Access: Authenticated user. Declared success status: 204_NO_CONTENT. Response: None.

Forget an item and its stock history.

Parameter	Source type	Default
item_id	int	Required / dependency-defined

Route source

GET /api/collection/transactions

Access: Authenticated user. Declared success status: 200. Response: list[TransactionOut].

Parameter	Source type	Default
item_id	int | None	None
limit	Annotated[int, Query(ge=1, le=500)]	50

Route source

POST /api/collection/transactions/{transaction_id}/undo

Access: Authenticated user. Declared success status: 200. Response: ItemOut.

Parameter	Source type	Default
transaction_id	int	Required / dependency-defined

Route source

GET /api/collection/value

Access: Authenticated user. Declared success status: 200. Response: ValueOut.

Current collection value, per game and overall.

Route source

GET /api/collection/movers

Access: Authenticated user. Declared success status: 200. Response: MoversOut.

Owned items whose market price moved most over the period, by value of the copies held (price change × quantity): biggest rises and falls.

Parameter	Source type	Default
period	Literal['d1', 'd7', 'd30']	'd7'
limit	Annotated[int, Query(ge=1, le=50)]	5

Route source

GET /api/collection/finance

Access: Authenticated user. Declared success status: 200. Response: FinanceOut.

Market value figures of the collection, or of one game's cards: totals, change over 1 to 365 days, value over the last year and how it splits (game, set, rarity, condition, language, finish, price band). Without a game, games priced in another currency than the user's price source are left out (listed in other_currencies).

Parameter	Source type	Default
game	str | None	None

Route source

GET /api/collection/value/history

Access: Authenticated user. Declared success status: 200. Response: ValueHistoryOut.

Daily value of current holdings over the last days days. Without a game, games priced in another currency than the user's price source are left out.

Parameter	Source type	Default
game	str | None	None
days	Annotated[int, Query(ge=1, le=3650)]	90

Route source

GET /api/collection/export.csv

Access: Authenticated user. Declared success status: 200. Response: Response.

Parameter	Source type	Default
game	str | None	None

Route source

POST /api/collection/import

Access: Authenticated user. Declared success status: 200. Response: ImportOut.

Import a CSV (see export format). Nothing is imported if any row is invalid. add adds quantities; set makes stored quantities equal to the file's.

Parameter	Source type	Default
file	Annotated[UploadFile, File()]	Required / dependency-defined
mode	Literal['add', 'set']	'add'
dry_run	bool	False

Route source

Games

GET /api/games

Access: Authenticated user. Declared success status: 200. Response: list[GameOut].

Route source

GET /api/games/{game_id}/colors/{code}/icon

Access: Authenticated user. Declared success status: 200. Response: FileResponse.

Parameter	Source type	Default
game_id	str	Required / dependency-defined
code	str	Required / dependency-defined

Route source

GET /api/games/{game_id}/rarities/{code}/icon

Access: Authenticated user. Declared success status: 200. Response: FileResponse.

The rarity's pictogram; lang: the one of cards printed in that language.

Parameter	Source type	Default
game_id	str	Required / dependency-defined
code	str	Required / dependency-defined
lang	Annotated[str | None, Query(max_length=8)]	None

Route source

GET /api/games/{game_id}/filters

Access: Authenticated user. Declared success status: 200. Response: dict[str, list[str]].

Values of each advanced search filter of the game, by filter key.

Parameter	Source type	Default
game_id	str	Required / dependency-defined

Route source

Releases

GET /api/app/android

Access: Authenticated user. Declared success status: 200. Response: AndroidRelease.

Latest Android app (GitHub release): web download link and the app's update check.

Route source

Scan

POST /api/scan/identify

Access: Authenticated user. Declared success status: 200. Response: IdentifyOut.

Match OCR text from a card photo to catalog printings.

Parameter	Source type	Default
body	IdentifyIn	Required / dependency-defined

Route source

Users

GET /api/users

Access: Administrator. Declared success status: 200. Response: list[UserOut].

Route source

POST /api/users

Access: Administrator. Declared success status: 201_CREATED. Response: UserOut.

Parameter	Source type	Default
body	UserCreateIn	Required / dependency-defined

Route source

PATCH /api/users/{user_id}

Access: Administrator. Declared success status: 200. Response: UserOut.

Parameter	Source type	Default
user_id	int	Required / dependency-defined
body	UserUpdateIn	Required / dependency-defined

Route source

DELETE /api/users/{user_id}

Access: Administrator. Declared success status: 204_NO_CONTENT. Response: See deployed OpenAPI schema.

Parameter	Source type	Default
user_id	int	Required / dependency-defined

Route source

Health

GET /api/health

Public. Returns HealthOut: status, server version, and nullable maintenance (since, game_id). A successful health response can coexist with a maintenance restriction for ordinary users.