{
  "openapi": "3.1.0",
  "info": {
    "title": "mtgomni API",
    "version": "1.1.0",
    "description": "Fast Magic: The Gathering card search with every printing's variations and prices. Card data, images and prices courtesy of Scryfall (https://scryfall.com) and MTGJSON (https://mtgjson.com, MIT); Magic: The Gathering is © Wizards of the Coast. Not affiliated with or endorsed by any of them. Prices are informational, updated daily, and not offers to buy or sell. Free to use, no key required. Be polite: cache responses and honor 429 + Retry-After."
  },
  "paths": {
    "/v1/fuzzy": {
      "get": {
        "summary": "Typo-tolerant card name lookup",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Best matches, one per card",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FuzzyResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "summary": "Scryfall-style query search",
        "description": "Terms: bare words (name), \"phrase\", t: type, o: oracle text, c: colors (: at least, = exact, <= subset), ci: color identity, cmc/mv, s: set, r: rarity (supports >=), f: legal format, banned:, -negation, `or`.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 300
            },
            "example": "t:creature c:rg cmc<=3 f:modern",
            "description": "Price/variation filters (any printing): usd<5 usd_foil>=10 eur<=2 tix<1, finish:foil|nonfoil|etched, promo:<type>, is:fullart, is:variation."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "name",
                "cmc",
                "released",
                "usd"
              ],
              "default": "name"
            },
            "description": "'usd' sorts by the card's highest USD price. 'relevance' ranks name matches first (exact, prefix, word, substring) and falls back to price when the query has no name text."
          },
          {
            "name": "dir",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "per",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 60
            }
          },
          {
            "name": "facets",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                0,
                1
              ]
            },
            "description": "1 adds counts by color, type, rarity, mana value and top sets over the whole result set"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of matching cards",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/cards/{id}": {
      "get": {
        "summary": "Card detail with all printings",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Oracle id or any printing's Scryfall id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The card",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Card"
                }
              }
            }
          },
          "404": {
            "description": "Unknown id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/status": {
      "get": {
        "summary": "Snapshot the API is serving",
        "responses": {
          "200": {
            "description": "Snapshot metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "cards": {
                      "type": "integer"
                    },
                    "printings": {
                      "type": "integer"
                    },
                    "built_at": {
                      "type": "integer"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "summary": "Liveness/readiness for monitors",
        "responses": {
          "200": {
            "description": "Ready"
          },
          "503": {
            "description": "No snapshot loaded yet"
          }
        }
      }
    },
    "/v1/printings/{id}": {
      "get": {
        "summary": "One printing: full detail, variations and current prices",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Scryfall printing id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Printing + prices",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "printing": {
                      "$ref": "#/components/schemas/PrintingDetail"
                    },
                    "prices": {
                      "$ref": "#/components/schemas/PriceSet"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/printings/{id}/prices": {
      "get": {
        "summary": "Current prices for one printing (Scryfall + MTGJSON vendors)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Scryfall printing id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Prices",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "prices": {
                      "$ref": "#/components/schemas/PriceSet"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/printings/{id}/history": {
      "get": {
        "summary": "Daily price history per vendor/finish (up to 400 days kept)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Scryfall printing id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 90,
              "maximum": 400
            }
          },
          {
            "name": "provider",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "tcgplayer, cardkingdom, cardmarket, cardsphere, cardhoarder"
          },
          {
            "name": "kind",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "retail",
                "buylist"
              ]
            }
          },
          {
            "name": "finish",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "normal",
                "foil",
                "etched"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Series of [date, price] points",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "since": {
                      "type": "string"
                    },
                    "series": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "series": {
                            "type": "string"
                          },
                          "format": {
                            "type": "string"
                          },
                          "provider": {
                            "type": "string"
                          },
                          "kind": {
                            "type": "string"
                          },
                          "finish": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "points": {
                            "type": "array",
                            "items": {
                              "type": "array",
                              "prefixItems": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "number"
                                }
                              ]
                            }
                          }
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/cards/{id}/printings": {
      "get": {
        "summary": "Every printing of a card with full detail and prices (newest first)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Oracle id or any printing's Scryfall id",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "per",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100,
              "maximum": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Printings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "oracle_id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "page": {
                      "type": "integer"
                    },
                    "per": {
                      "type": "integer"
                    },
                    "printings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "printing": {
                            "$ref": "#/components/schemas/PrintingDetail"
                          },
                          "prices": {
                            "$ref": "#/components/schemas/PriceSet"
                          }
                        }
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/prices": {
      "get": {
        "summary": "Bulk current prices for up to 100 printings",
        "parameters": [
          {
            "name": "ids",
            "in": "query",
            "required": true,
            "description": "Comma-separated Scryfall printing ids (max 100)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Map of id -> PriceSet (null when a printing has no price data)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prices": {
                      "type": "object",
                      "additionalProperties": {
                        "oneOf": [
                          {
                            "$ref": "#/components/schemas/PriceSet"
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed ids",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/sets": {
      "get": {
        "summary": "All sets with printing counts, rarity mix and USD value",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Scryfall set_type, e.g. expansion, core, masters, commander"
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Substring of set name or code"
          }
        ],
        "responses": {
          "200": {
            "description": "List of sets, newest first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "sets": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/sets/{code}": {
      "get": {
        "summary": "One set and its printings (paged)",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "number",
                "name",
                "usd",
                "rarity",
                "cmc"
              ]
            }
          },
          {
            "name": "dir",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "rarity",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "per",
            "in": "query",
            "schema": {
              "type": "integer",
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Set info plus a page of printings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "set": {
                      "type": "object"
                    },
                    "total": {
                      "type": "integer"
                    },
                    "page": {
                      "type": "integer"
                    },
                    "per": {
                      "type": "integer"
                    },
                    "cards": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown set code"
          }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "summary": "Catalog-wide statistics: totals, rarity, colors, types, formats, years, price bands, most valuable printings and sets",
        "responses": {
          "200": {
            "description": "Statistics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "totals": {
                      "type": "object"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/Meta"
                    }
                  },
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "RateLimited": {
        "description": "Too many requests. Wait Retry-After seconds.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Meta": {
        "type": "object",
        "properties": {
          "snapshot": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "attribution": {
            "type": "string"
          },
          "terms": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "retry_after": {
            "type": "integer"
          }
        }
      },
      "CardItem": {
        "type": "object",
        "properties": {
          "o": {
            "type": "string",
            "description": "oracle id"
          },
          "n": {
            "type": "string",
            "description": "name"
          },
          "m": {
            "type": [
              "string",
              "null"
            ],
            "description": "mana cost"
          },
          "c": {
            "type": "number",
            "description": "mana value"
          },
          "t": {
            "type": [
              "string",
              "null"
            ],
            "description": "type line"
          },
          "i": {
            "type": [
              "string",
              "null"
            ],
            "description": "image URL (Scryfall CDN); keep full card images uncropped"
          }
        }
      },
      "FuzzyResponse": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/CardItem"
                },
                {
                  "type": "object",
                  "properties": {
                    "score": {
                      "type": "number"
                    }
                  }
                }
              ]
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "page": {
            "type": "integer"
          },
          "per": {
            "type": "integer"
          },
          "cards": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CardItem"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "Printing": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "s": {
            "type": "string",
            "description": "set code"
          },
          "sn": {
            "type": [
              "string",
              "null"
            ]
          },
          "cn": {
            "type": "string",
            "description": "collector number"
          },
          "r": {
            "type": "string",
            "description": "rarity"
          },
          "d": {
            "type": "string",
            "description": "release date"
          },
          "i": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Card": {
        "type": "object",
        "properties": {
          "o": {
            "type": "string"
          },
          "n": {
            "type": "string"
          },
          "m": {
            "type": [
              "string",
              "null"
            ]
          },
          "c": {
            "type": "number"
          },
          "t": {
            "type": [
              "string",
              "null"
            ]
          },
          "x": {
            "type": [
              "string",
              "null"
            ],
            "description": "oracle text"
          },
          "k": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "colors"
          },
          "ci": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "color identity"
          },
          "l": {
            "type": "string",
            "description": "layout"
          },
          "lg": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "format -> legal|restricted|banned (not_legal omitted)"
          },
          "i": {
            "type": [
              "string",
              "null"
            ]
          },
          "printings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Printing"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Meta"
          }
        }
      },
      "PriceSet": {
        "type": "object",
        "description": "Current prices for one printing.",
        "properties": {
          "scryfall": {
            "type": "object",
            "description": "Scryfall daily prices (numbers): usd, usd_foil, usd_etched, eur, eur_foil, eur_etched, tix. Missing = no price.",
            "additionalProperties": {
              "type": "number"
            }
          },
          "as_of": {
            "type": [
              "string",
              "null"
            ],
            "description": "Scryfall snapshot date"
          },
          "vendors": {
            "type": "object",
            "description": "MTGJSON multi-vendor prices: format (paper|mtgo) -> provider (tcgplayer, cardkingdom, cardmarket, cardsphere, cardhoarder) -> {cur, date, retail:{normal|foil|etched}, buylist:{...}}.",
            "additionalProperties": true
          },
          "vendors_as_of": {
            "type": "string"
          }
        }
      },
      "PrintingDetail": {
        "type": "object",
        "description": "Full per-printing detail: faces, finishes, frame, frame_effects, border_color, full_art, textless, promo, promo_types, variation, variation_of, security_stamp, artist, flavor_name, games, ids (tcgplayer/cardmarket/mtgo/multiverse), images, purchase_uris, ...",
        "additionalProperties": true
      }
    }
  }
}