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/	Login, logout, password change
/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/	Per-user settings
/health	Liveness check, returns {"status": "ok"}

Use Cases

Home Assistant / custom dashboards

The /collection/stats and /wishlist/ endpoints return structured JSON suitable for Home Assistant template sensors or any REST-capable dashboard.

Scripts and automation

Authenticate once to get a token, then use any HTTP client (curl, httpx, requests) against any endpoint. The collection import endpoint (POST /collection/import) is useful for bulk operations.

HACS / Home Assistant integration (planned for v1.10)

The API is the foundation for the planned Home Assistant integration. Anyone building toward that can use the live docs to explore available data today.

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.