Grimoria API
Let apps, scripts and AI assistants read and manage a Grimoria user's Magic: The Gathering collection, decks and wishlists, and look up card data. Every call acts on behalf of one user and only reaches what that user allowed.
Base URL and spec
Base URL: https://grimoria.app/api/v1
OpenAPI 3 spec: https://grimoria.app/api/v1/openapi.json — it lists every endpoint available to API clients, with its required scope and request and response schemas.
Most responses wrap their payload as { "success": true, "data": … }. Card lookups under /cards return the payload directly.
Authentication
Send a token in the Authorization header. Tokens start with gma_. There are two ways to get one.
Personal API key
For your own scripts. Create one in Settings → API access, choose its permissions and an optional expiry, and copy it: it is shown only once. You can hold up to 10 active keys and revoke any of them there.
curl https://grimoria.app/api/v1/collections \ -H "Authorization: Bearer gma_YOUR_KEY"
OAuth 2.1 (for apps used by many people)
Grimoria is an OAuth 2.1 authorization server supporting the authorization code flow with PKCE. Only S256 challenges are accepted, and state is required. Discovery document: https://grimoria.app/.well-known/oauth-authorization-server.
- Send the user to
https://grimoria.app/oauth/authorizewithresponse_type=code, yourclient_id, a registeredredirect_uri, space-separatedscope,stateand the PKCE challenge. The user signs in and approves or denies. - Exchange the code (valid for 60 seconds, usable once) at
POST https://grimoria.app/api/v1/oauth/tokenas form data with yourcode_verifier. Confidential clients authenticate with HTTP Basic orclient_secretin the body; public clients send onlyclient_id. - Access tokens last 1 hour; refresh tokens last 30 days and rotate on every use. Reusing an old refresh token revokes the whole grant. Revoke tokens at
POST https://grimoria.app/api/v1/oauth/revoke. - Users see connected apps in Settings → API access and can disconnect them at any time.
Client registration is manual for now: send your app name, redirect URIs and the scopes you need through the feedback form.
Scopes
| Scope | Grants |
|---|---|
cards:read | Search and read card data, printings, rulings and sets. |
collection:read | List the user's collections and read or search the cards in them. |
collection:write | Add cards to a collection (one or in bulk) and edit collection cards. |
decks:read | List and read the user's decks, validate them, read public decks. |
decks:write | Create decks, edit deck details, add and edit deck cards. |
wishlist:read | List and read the user's wishlists and their cards. |
wishlist:write | Create and edit wishlists, add and edit wishlist cards. |
Tokens can never reach account, login, payment, deletion, sync or admin endpoints, and cannot create or manage other tokens. Card data is public; collection, deck and wishlist data belongs to the user who approved the token. Prices come mainly from European markets (Cardmarket, CardTrader).
Rate limits
- 10 requests per second per token, with bursts up to 30.
- 200 requests per second per client IP across all tokens.
- OAuth endpoints: 5 requests per second per IP, with bursts up to 10.
Over the limit you get HTTP 503 or 429. Back off and retry, honouring Retry-After or the X-RateLimit-* headers when a response carries them.
Errors
Errors are JSON with statusCode, message and, where one applies, a stable code. The OAuth endpoints use the standard { "error", "error_description" } format.
- 401 — the token is missing, unknown, revoked or expired (
AUTH_004). Get a new token. - 403 — the endpoint is not available to API tokens (
AUTH_020) or the token lacks the scope it needs (AUTH_021). - 404 — the resource does not exist or belongs to someone else.
Requirements
A free Grimoria account is all you need. Create one, then make a key or connect an app.