{
  "openapi": "3.1.1",
  "info": {
    "title": "Cardrake Public API",
    "version": "1.0.0",
    "description": "Read-only access to Cardrake’s Pokémon TCG catalogue: cards, expansions,\nprinted and master-set totals, and TCGPlayer market pricing.\n\nNo authentication or registration is required for any endpoint described\nhere. See /auth.md for rate limits and the agent access policy.\n\nAgents are usually better served by the Model Context Protocol endpoint at\nhttps://www.cardrake.com/api/mcp (streamable HTTP), which exposes the same catalogue as six\nintent-shaped tools with resolution built in. This REST API is the lower-level\nsurface. The MCP server is described by its own server card; see\n/.well-known/api-catalog for both.\n\nPrices are TCGPlayer market values for raw, ungraded cards in USD, synced\ndaily. They are not graded comparables. Condition and exact variant both\nmaterially change what a card is worth.",
    "contact": {
      "url": "https://www.cardrake.com/guides/chatgpt-plugin"
    }
  },
  "externalDocs": {
    "description": "Agent and MCP integration guide",
    "url": "https://www.cardrake.com/guides/chatgpt-plugin"
  },
  "servers": [
    {
      "url": "https://www.cardrake.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/cards/search": {
      "get": {
        "operationId": "searchCards",
        "summary": "Search cards with filters and facet counts",
        "description": "Paginated card search. Every filter is optional; with none supplied it\nreturns the full catalogue ordered by name.\n\nFacet counts each EXCLUDE their own filter, so the returned counts show\nwhat selecting a different value would yield rather than what is already\nselected.\n\nThe `status` parameter filters by the caller’s own collection and only\ndoes anything for a browser session with a Clerk cookie. Anonymous\ncallers — including every agent — should ignore it, and will never\nreceive the `collectionStatus` field.",
        "tags": [
          "Cards"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Free-text match on card name.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "expansion",
            "in": "query",
            "description": "Comma-separated expansion ids, e.g. `sv3pt5,sv8pt5`.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "supertype",
            "in": "query",
            "description": "Comma-separated supertypes: `Pokémon`, `Trainer`, `Energy`.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "rarity",
            "in": "query",
            "description": "Comma-separated rarities, e.g. `Illustration Rare`.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "types",
            "in": "query",
            "description": "Comma-separated Pokémon types, e.g. `Fire,Water`.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subtypes",
            "in": "query",
            "description": "Comma-separated subtypes, e.g. `ex,V`.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hpMin",
            "in": "query",
            "description": "Minimum HP.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "hpMax",
            "in": "query",
            "description": "Maximum HP.",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "priceMin",
            "in": "query",
            "description": "Minimum market price in USD.",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "priceMax",
            "in": "query",
            "description": "Maximum market price in USD.",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Collection filter. Requires a signed-in browser session; no effect for anonymous callers.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "owned",
                "wanted",
                "not-owned"
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Result ordering.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "name",
                "price-desc",
                "price-asc",
                "release-desc",
                "number"
              ],
              "default": "name"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "1-based page number.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 48
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of cards plus facet counts.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "cards": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "number": {
                            "type": "string"
                          },
                          "rarity": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "supertype": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "subtypes": {
                            "anyOf": [
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "types": {
                            "anyOf": [
                              {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "hp": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "images": {
                            "type": "object",
                            "properties": {
                              "small": {
                                "type": "string"
                              },
                              "large": {
                                "type": "string"
                              }
                            },
                            "required": [
                              "small",
                              "large"
                            ],
                            "additionalProperties": {}
                          },
                          "expansionId": {
                            "type": "string"
                          },
                          "expansionName": {
                            "type": "string"
                          },
                          "expansionSeries": {
                            "type": "string"
                          },
                          "printedTotal": {
                            "type": "number"
                          },
                          "expansionIsUpcoming": {
                            "type": "boolean"
                          },
                          "price": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "hasHolofoil": {
                            "type": "boolean"
                          },
                          "hasReverseHolofoil": {
                            "type": "boolean"
                          },
                          "variants": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "collectionStatus": {
                            "type": "object",
                            "propertyNames": {
                              "type": "string"
                            },
                            "additionalProperties": {
                              "type": "object",
                              "properties": {
                                "status": {
                                  "type": "string"
                                },
                                "quantity": {
                                  "anyOf": [
                                    {
                                      "type": "number"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "condition": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              },
                              "required": [
                                "status",
                                "quantity",
                                "condition"
                              ],
                              "additionalProperties": {}
                            }
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "number",
                          "rarity",
                          "supertype",
                          "subtypes",
                          "types",
                          "hp",
                          "images",
                          "expansionId",
                          "expansionName",
                          "expansionSeries",
                          "printedTotal",
                          "expansionIsUpcoming",
                          "price",
                          "hasHolofoil",
                          "hasReverseHolofoil",
                          "variants"
                        ],
                        "additionalProperties": {}
                      }
                    },
                    "total": {
                      "type": "number"
                    },
                    "page": {
                      "type": "number"
                    },
                    "totalPages": {
                      "type": "number"
                    },
                    "facets": {
                      "type": "object",
                      "properties": {
                        "expansions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "count": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "id",
                              "name",
                              "count"
                            ],
                            "additionalProperties": {}
                          }
                        },
                        "rarities": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "value": {
                                "type": "string"
                              },
                              "count": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "value",
                              "count"
                            ],
                            "additionalProperties": {}
                          }
                        },
                        "supertypes": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "value": {
                                "type": "string"
                              },
                              "count": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "value",
                              "count"
                            ],
                            "additionalProperties": {}
                          }
                        },
                        "types": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "value": {
                                "type": "string"
                              },
                              "count": {
                                "type": "number"
                              }
                            },
                            "required": [
                              "value",
                              "count"
                            ],
                            "additionalProperties": {}
                          }
                        }
                      },
                      "required": [
                        "expansions",
                        "rarities",
                        "supertypes",
                        "types"
                      ],
                      "additionalProperties": {}
                    }
                  },
                  "required": [
                    "cards",
                    "total",
                    "page",
                    "totalPages",
                    "facets"
                  ],
                  "additionalProperties": {}
                }
              }
            }
          }
        }
      }
    },
    "/api/cards/{id}": {
      "get": {
        "operationId": "getCard",
        "summary": "Get one card by id",
        "description": "Full card detail including per-variant TCGPlayer pricing.\n\nIds are `{expansionId}-{number}`, e.g. `sv3pt5-199`. Note this response\nis wrapped in a `{ success, data }` envelope; the other endpoints here\nreturn their object directly.\n\nThis endpoint sends an `ETag`, but it is derived from the card id alone\nand does not change when prices do. Do not use it for conditional\nrequests.",
        "tags": [
          "Cards"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Card id, e.g. `sv3pt5-199`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The card, inside a success envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "supertype": {
                          "type": "string"
                        },
                        "subtypes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "hp": {
                          "type": "string"
                        },
                        "types": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "number": {
                          "type": "string"
                        },
                        "artist": {
                          "type": "string"
                        },
                        "rarity": {
                          "type": "string"
                        },
                        "regulationMark": {
                          "type": "string"
                        },
                        "images": {
                          "type": "object",
                          "properties": {
                            "small": {
                              "type": "string"
                            },
                            "large": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "small",
                            "large"
                          ],
                          "additionalProperties": {}
                        },
                        "set": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "series": {
                              "type": "string"
                            },
                            "printedTotal": {
                              "type": "number"
                            },
                            "total": {
                              "type": "number"
                            },
                            "releaseDate": {
                              "type": "string"
                            },
                            "images": {
                              "type": "object",
                              "properties": {
                                "symbol": {
                                  "type": "string"
                                },
                                "logo": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "symbol",
                                "logo"
                              ],
                              "additionalProperties": {}
                            }
                          },
                          "required": [
                            "id",
                            "name",
                            "series",
                            "printedTotal",
                            "total",
                            "releaseDate",
                            "images"
                          ],
                          "additionalProperties": {}
                        },
                        "tcgplayer": {
                          "type": "object",
                          "properties": {
                            "url": {
                              "type": "string"
                            },
                            "updatedAt": {
                              "type": "string"
                            },
                            "prices": {
                              "type": "object",
                              "propertyNames": {
                                "type": "string"
                              },
                              "additionalProperties": {
                                "anyOf": [
                                  {
                                    "type": "object",
                                    "properties": {
                                      "low": {
                                        "anyOf": [
                                          {
                                            "type": "number"
                                          },
                                          {
                                            "type": "null"
                                          }
                                        ]
                                      },
                                      "mid": {
                                        "anyOf": [
                                          {
                                            "type": "number"
                                          },
                                          {
                                            "type": "null"
                                          }
                                        ]
                                      },
                                      "high": {
                                        "anyOf": [
                                          {
                                            "type": "number"
                                          },
                                          {
                                            "type": "null"
                                          }
                                        ]
                                      },
                                      "market": {
                                        "anyOf": [
                                          {
                                            "type": "number"
                                          },
                                          {
                                            "type": "null"
                                          }
                                        ]
                                      },
                                      "directLow": {
                                        "anyOf": [
                                          {
                                            "type": "number"
                                          },
                                          {
                                            "type": "null"
                                          }
                                        ]
                                      }
                                    },
                                    "additionalProperties": {}
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              }
                            }
                          },
                          "additionalProperties": {}
                        }
                      },
                      "required": [
                        "id",
                        "name",
                        "supertype",
                        "number",
                        "rarity",
                        "images",
                        "set"
                      ],
                      "additionalProperties": {}
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ],
                  "additionalProperties": {}
                }
              }
            }
          },
          "404": {
            "description": "No card with that id.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "const": false
                    },
                    "error": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string"
                    },
                    "details": {}
                  },
                  "required": [
                    "success",
                    "error"
                  ],
                  "additionalProperties": {}
                }
              }
            }
          }
        }
      }
    },
    "/api/expansions": {
      "get": {
        "operationId": "listExpansions",
        "summary": "List every active expansion, grouped by series",
        "description": "All active expansions, grouped by series and ordered newest-first.\n\n`printedTotal` is the on-card \"/M\" denominator. `total` is the master-set\nsize, including secret rares printed above that number — the two differ\nfor most modern sets and the difference is the point of a master set.",
        "tags": [
          "Expansions"
        ],
        "responses": {
          "200": {
            "description": "Series order plus expansions grouped by series.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "series": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "expansions": {
                      "type": "object",
                      "propertyNames": {
                        "type": "string"
                      },
                      "additionalProperties": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "series": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "printedTotal": {
                              "anyOf": [
                                {
                                  "type": "number"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "total": {
                              "anyOf": [
                                {
                                  "type": "number"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "ptcgoCode": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "releaseDate": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "images": {},
                            "isUpcoming": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "id",
                            "name",
                            "series",
                            "printedTotal",
                            "total",
                            "ptcgoCode",
                            "releaseDate",
                            "images",
                            "isUpcoming"
                          ],
                          "additionalProperties": {}
                        }
                      }
                    },
                    "total": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "series",
                    "expansions",
                    "total"
                  ],
                  "additionalProperties": {}
                }
              }
            }
          }
        }
      }
    },
    "/api/valuable-sets": {
      "get": {
        "operationId": "listValuableSets",
        "summary": "Expansions ranked by total market value",
        "description": "Every active expansion with a non-zero market total, ranked by that\ntotal descending.\n\nTotals here are ONE PRICE PER CARD — the highest variant price for each\ncard — which is deliberately different from the master-set totals shown\non /guides/master-set, where each printed variant is its own slot. Both\nare correct for their own question. Do not present them as the same\nnumber or reconcile one to the other.",
        "tags": [
          "Expansions"
        ],
        "responses": {
          "200": {
            "description": "Expansions with aggregate low/mid/high/market totals in USD.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sets": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "series": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "releaseDate": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "totalCards": {
                            "type": "number"
                          },
                          "cardsWithPrices": {
                            "type": "number"
                          },
                          "low": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "mid": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "high": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "market": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "series",
                          "releaseDate",
                          "totalCards",
                          "cardsWithPrices",
                          "low",
                          "mid",
                          "high",
                          "market"
                        ],
                        "additionalProperties": {}
                      }
                    }
                  },
                  "required": [
                    "sets"
                  ],
                  "additionalProperties": {}
                }
              }
            }
          }
        }
      }
    },
    "/api/pricing": {
      "get": {
        "operationId": "getPricing",
        "summary": "Displayed Collector Plan pricing",
        "description": "The subscription prices Cardrake displays, in USD. Display-only: the\namounts actually charged come from Clerk Billing’s hosted checkout.\n\nThere is no agent-purchasable product. To subscribe, a human completes\ncheckout at https://www.cardrake.com/upgrade.",
        "tags": [
          "Account"
        ],
        "responses": {
          "200": {
            "description": "Displayed monthly and annual pricing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "monthlyPrice": {
                      "type": "number"
                    },
                    "annualMonthlyPrice": {
                      "type": "number"
                    },
                    "annualTotalPrice": {
                      "type": "number"
                    }
                  },
                  "required": [
                    "monthlyPrice",
                    "annualMonthlyPrice",
                    "annualTotalPrice"
                  ],
                  "additionalProperties": {}
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Service health",
        "description": "Returns 200 when the API can reach its database, 503 otherwise. This is the `status` target in /.well-known/api-catalog.",
        "tags": [
          "Service"
        ],
        "responses": {
          "200": {
            "description": "Service is healthy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "const": "healthy"
                    },
                    "timestamp": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status",
                    "timestamp"
                  ],
                  "additionalProperties": {}
                }
              }
            }
          },
          "503": {
            "description": "Service cannot reach its database.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "const": "unhealthy"
                    },
                    "error": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "status",
                    "error"
                  ],
                  "additionalProperties": {}
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Cards",
      "description": "Individual cards and card search."
    },
    {
      "name": "Expansions",
      "description": "Sets, totals, and value rankings."
    },
    {
      "name": "Account",
      "description": "Subscription pricing (display-only)."
    },
    {
      "name": "Service",
      "description": "Operational endpoints."
    }
  ]
}