API Reference

OpenMTG's backend is built with FastAPI, which automatically generates interactive API documentation. The live docs always reflect the current API with no separate maintenance required.

Accessing the Docs

With the instance running, open a browser and navigate to:

http://yourinstance:8080/api/docs

Replace yourinstance:8080 with the actual host and port. This opens the Swagger UI, a fully interactive interface where you can browse every endpoint, inspect request and response schemas, and execute requests directly from the browser.

A machine-readable OpenAPI schema is also available at:

http://yourinstance:8080/api/openapi.json

Authentication

Most endpoints require a JWT bearer token. To authenticate in Swagger UI:

1. Call POST /auth/login with the username and password
2. Copy the access_token from the response
3. Click Authorize (top right of Swagger UI) and paste the token

All subsequent requests in that session will include the token automatically.

From scripts or external tools, include the token in the Authorization header:

Authorization: Bearer <token>

Key Endpoint Groups

Prefix	Description
/auth/	First-run setup, login, current user info, currency preference
/cards/	Scryfall card lookup and cache
/collection/	Collection CRUD, import, stats
/decks/	Deck management and card assignment
/wishlist/	Wishlist management and price history
/export/	Collection and deck exports (CSV, Moxfield, JSON)
/currencies/	Currency metadata
/admin/	User management, currency config, settings
/admin/settings/	Admin controlled global and user settings
/health	Liveness check, returns {"status": "ok"}
/card-search/	Card quick-lookup enable check
/trades/	Trade proposals, confirmations, and card transfers
/showroom/display/{username}	Public display of decks and showcased cards
/admin/telemetry/	Admin-only telemetry status, enable/disable
/webhooks/	Manage your own Home Assistant webhook credentials
/api/webhook/{username}/{webhook_id}/stats	Bearer-authenticated pull endpoint for collection stats, not a session endpoint

There is no logout endpoint. Sessions are stateless JWTs, so logging out simply discards the stored token client-side. Password changes are admin-managed: an admin can set a new password for any user from Admin > User Management (Reset Password). See Admin Lockout if no admin account is accessible.

Use Cases

Home Assistant integration

OpenMTG has a dedicated, credential-based Home Assistant integration: per-user webhook credentials push trade and wishlist-price events to Home Assistant, and a bearer-authenticated pull endpoint (GET /api/webhook/{username}/{webhook_id}/stats) serves live collection stats without needing a login session.

Other dashboards and scripts

For anything besides Home Assistant, /collection/stats and /wishlist/ return structured JSON suitable for any REST-capable dashboard, and any endpoint can be scripted against with curl, httpx, requests, etc. after authenticating once for a token. The collection import endpoint (POST /collection/import) is useful for bulk operations.

Rate Limiting

The API applies per-endpoint rate limiting via slowapi. Limits are generous for normal interactive use. If building automation that calls the API frequently, add a short delay between requests to avoid 429 responses.

Outbound Scryfall API calls are rate-limited server-side, configurable in Admin > Settings. Scripts and services do not need to account for Scryfall's rate limits directly.