Developer API

The MTG Rack API gives you programmatic access to your collection, decks, binders, and card data via a standard REST interface. Use it to build custom integrations — Discord bots that look up card prices, spreadsheets that sync with your collection, automated imports from other platforms, price alert systems, or anything else you can imagine.

Base URL and Versioning

All API endpoints are served under a versioned base URL. The current version is v1:

https://mtgrack.com/api/v1

The version number is part of the URL path, not a header. When a new major version is released, the previous version will continue to work for at least 12 months with a deprecation notice in the response headers. Minor additions (new fields, new endpoints) are added to the current version without a version bump and are always backward compatible.

Authentication

All requests require an Authorization: Bearer <token> header. MTG Rack supports two authentication methods:

• Personal API Keys — for scripts, bots, and tools that access your own data. Create keys in the Developer Portal. Keys are prefixed with mtr_k_ and tied to your account. See the Authentication guide for setup instructions.
• OAuth2 Access Tokens — for third-party apps that access other users' data with their consent. Use the standard authorization code flow to obtain tokens scoped to specific permissions. See the OAuth2 Integration guide for the full flow.

Response Format

All responses return JSON. Successful responses follow a consistent envelope structure with data and optional meta fields. List endpoints return paginated results:

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 234,
    "has_more": true
  }
}

Single-resource endpoints return the resource directly in data. Error responses use a consistent structure that includes a machine-readable code, a human-readable message, and the HTTP status:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This token does not have the required scope(s): collection:write",
    "status": 403
  }
}

Always check the HTTP status code first — 2xx means success, 4xx means a client error (bad request, auth failure, rate limit), and 5xx means a server error (rare, and safe to retry with backoff).

Rate Limits

API requests are rate limited per key to ensure fair usage for all developers:

• 60 requests per minute — a sliding window that resets continuously.
• 10,000 requests per day — a daily quota that resets at midnight UTC.

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so you can track your usage programmatically. When you exceed a limit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait. See Rate Limits for strategies on staying within quotas.

Webhooks

Instead of polling for changes, you can register webhook endpoints to receive real-time HTTP POST callbacks when events happen in your account — cards added, decks updated, binders modified, and more. Webhook payloads are signed with HMAC-SHA256 for verification. See the Webhooks guide for setup, events, and signature verification.

Interactive Reference

For a complete list of every endpoint with request/response schemas and a try-it-out console, visit the API Reference in the Developer Portal. You can authenticate directly in the reference UI and make live API calls against your own data.

Quick Links