{
    "openapi": "3.1.0",
    "info": {
        "title": "Mudwater Cards API",
        "version": "v1",
        "summary": "Card search, card facts and digital + physical prices for every Mudwater card.",
        "description": "Free, no key, 60 requests an hour per IP address. A \"Prices by MudwaterCards.com\" credit linking the card page is appreciated wherever a price shows. Reference: https://mudwatercards.com/api",
        "termsOfService": "https://mudwatercards.com/api#terms",
        "contact": {
            "name": "@KaijuTheApe on X",
            "url": "https://x.com/KaijuTheApe"
        }
    },
    "servers": [
        {
            "url": "https://mudwatercards.com/api/v1"
        }
    ],
    "paths": {
        "/cards": {
            "get": {
                "operationId": "searchCards",
                "summary": "Find cards by name, number or trait; all 128 with no parameters",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Name, a word of it, a number or a promo id",
                        "example": "gary"
                    },
                    {
                        "name": "set",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "swamp-origins",
                                "apefest-2026"
                            ]
                        }
                    },
                    {
                        "name": "rarity",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "common",
                                "uncommon",
                                "rare",
                                "prestige",
                                "legendary"
                            ]
                        }
                    },
                    {
                        "name": "type",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "example": "club"
                    },
                    {
                        "name": "artist",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        },
                        "example": "chomps"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The matching cards, set order; count 0 with an empty data when nothing matches",
                        "headers": {
                            "X-RateLimit-Limit": {
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "Cache-Control": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SearchResult"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "A parameter value the endpoint does not take",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Over the hourly limit; Retry-After says how long",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/cards/{id}": {
            "get": {
                "operationId": "getCard",
                "summary": "One card: facts, print runs, copies on chain, holders, art",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "swamp-origins:049, apefest-2026:prm-01, or the short forms 49, 049, prm-01",
                        "schema": {
                            "type": "string"
                        },
                        "example": "49"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The card",
                        "headers": {
                            "X-RateLimit-Limit": {
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "Cache-Control": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Card"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No card has that id",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Over the hourly limit",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/cards/{id}/prices": {
            "get": {
                "operationId": "getCardPrices",
                "summary": "One card: digital and physical prices, last sales, medians and a value per side, per finish",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "swamp-origins:049, apefest-2026:prm-01, or the short forms 49, 049, prm-01",
                        "schema": {
                            "type": "string"
                        },
                        "example": "49"
                    },
                    {
                        "name": "finish",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "base",
                                "foil",
                                "serialized",
                                "any"
                            ]
                        },
                        "description": "One finish alone"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The prices",
                        "headers": {
                            "X-RateLimit-Limit": {
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "Cache-Control": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CardPrices"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "A finish the endpoint does not take",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No card has that id, or it lacks that finish",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Over the hourly limit",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "No price copy exists yet",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/prices": {
            "get": {
                "operationId": "getAllValues",
                "summary": "Every card and finish in one file: a digital and a physical value, the lowest copies, the last sales",
                "parameters": [
                    {
                        "name": "finish",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "base",
                                "foil",
                                "any"
                            ]
                        },
                        "description": "Set cards of that finish, or the promos (any)"
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "json",
                                "csv"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The rows",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ValuesFile"
                                }
                            },
                            "text/csv": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "A parameter value the endpoint does not take",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Over the hourly limit",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "No price copy exists yet",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string",
                                "description": "bad_request, not_found, method_not_allowed, rate_limited or unavailable"
                            },
                            "message": {
                                "type": "string"
                            }
                        }
                    }
                }
            },
            "CardSummary": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Unique across sets: swamp-origins:049, apefest-2026:prm-01"
                    },
                    "set": {
                        "type": "string",
                        "description": "swamp-origins or apefest-2026"
                    },
                    "number": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "Set card number 1-120; null for a promo"
                    },
                    "label": {
                        "type": "string",
                        "description": "#049 or PRM-01"
                    },
                    "name": {
                        "type": "string",
                        "description": "The card name"
                    },
                    "rarity": {
                        "type": "string",
                        "description": "Common, Uncommon, Rare, Prestige or Legendary"
                    },
                    "type": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "As printed, e.g. Club"
                    },
                    "subset": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The sub-set, e.g. Dog Food"
                    },
                    "artist": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The artist credit as printed"
                    },
                    "url": {
                        "type": "string",
                        "description": "The card page on MudwaterCards.com"
                    },
                    "thumb": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Base art, 480 x 666"
                    }
                }
            },
            "SearchResult": {
                "type": "object",
                "properties": {
                    "count": {
                        "type": "integer"
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/CardSummary"
                        }
                    }
                }
            },
            "Card": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "description": "Unique across sets: swamp-origins:049, apefest-2026:prm-01"
                    },
                    "set": {
                        "type": "string",
                        "description": "swamp-origins or apefest-2026"
                    },
                    "number": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "Set card number 1-120; null for a promo"
                    },
                    "label": {
                        "type": "string",
                        "description": "#049 or PRM-01"
                    },
                    "name": {
                        "type": "string",
                        "description": "The card name"
                    },
                    "rarity": {
                        "type": "string",
                        "description": "Common, Uncommon, Rare, Prestige or Legendary"
                    },
                    "type": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "As printed, e.g. Club"
                    },
                    "subset": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The sub-set, e.g. Dog Food"
                    },
                    "artist": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The artist credit as printed"
                    },
                    "url": {
                        "type": "string",
                        "description": "The card page on MudwaterCards.com"
                    },
                    "aliases": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Other spellings sellers use"
                    },
                    "level": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "description": "1 to 5"
                    },
                    "edges": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "properties": {
                            "top": {
                                "type": "integer"
                            },
                            "right": {
                                "type": "integer"
                            },
                            "bottom": {
                                "type": "integer"
                            },
                            "left": {
                                "type": "integer"
                            }
                        }
                    },
                    "finishes": {
                        "type": "object",
                        "description": "base, foil and serialized on a set card; any on a promo",
                        "additionalProperties": {
                            "type": "object",
                            "properties": {
                                "printed": {
                                    "type": [
                                        "integer",
                                        "null"
                                    ],
                                    "description": "The fixed print run"
                                },
                                "on_chain": {
                                    "type": [
                                        "integer",
                                        "null"
                                    ],
                                    "description": "Copies on the Solana chain now"
                                },
                                "holders": {
                                    "type": [
                                        "integer",
                                        "null"
                                    ],
                                    "description": "Wallets holding at least one"
                                },
                                "image": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "description": "Full-size rendering, 1621 x 2250"
                                },
                                "thumb": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "description": "480-wide copy"
                                }
                            }
                        }
                    },
                    "on_chain_as_of": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "When the chain was counted"
                    },
                    "opensea": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The card on OpenSea"
                    },
                    "attribution": {
                        "type": "object",
                        "properties": {
                            "text": {
                                "type": "string",
                                "description": "The line to show"
                            },
                            "url": {
                                "type": "string",
                                "description": "The page to link"
                            }
                        }
                    }
                }
            },
            "CardPrices": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "set": {
                        "type": "string"
                    },
                    "number": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "label": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "rarity": {
                        "type": "string"
                    },
                    "rules": {
                        "type": "object",
                        "properties": {
                            "digital": {
                                "type": "string"
                            },
                            "physical": {
                                "type": "string"
                            }
                        }
                    },
                    "finishes": {
                        "type": "object",
                        "description": "base and foil (and serialized where the card has one) on a set card; any on a promo",
                        "additionalProperties": {
                            "type": "object",
                            "properties": {
                                "digital": {
                                    "type": "object",
                                    "description": "Every field null on a promo card",
                                    "properties": {
                                        "value": {
                                            "type": [
                                                "object",
                                                "null"
                                            ],
                                            "properties": {
                                                "usd": {
                                                    "type": [
                                                        "number",
                                                        "null"
                                                    ],
                                                    "description": "US dollars"
                                                },
                                                "basis": {
                                                    "type": "string",
                                                    "description": "median_7d, median_30d, few_sales, lowest_listing or rarity_median"
                                                },
                                                "sales": {
                                                    "type": [
                                                        "integer",
                                                        "null"
                                                    ],
                                                    "description": "Sales behind a median or a blend, else null"
                                                }
                                            }
                                        },
                                        "lowest": {
                                            "type": [
                                                "object",
                                                "null"
                                            ],
                                            "properties": {
                                                "usd": {
                                                    "type": [
                                                        "number",
                                                        "null"
                                                    ],
                                                    "description": "US dollars"
                                                },
                                                "sol": {
                                                    "type": "number"
                                                },
                                                "venue": {
                                                    "type": "string",
                                                    "description": "opensea or magiceden"
                                                },
                                                "url": {
                                                    "type": "string",
                                                    "description": "The listing"
                                                }
                                            }
                                        },
                                        "listed": {
                                            "type": "integer"
                                        },
                                        "last_sold": {
                                            "type": [
                                                "object",
                                                "null"
                                            ],
                                            "properties": {
                                                "usd": {
                                                    "type": [
                                                        "number",
                                                        "null"
                                                    ],
                                                    "description": "US dollars"
                                                },
                                                "sol": {
                                                    "type": [
                                                        "number",
                                                        "null"
                                                    ]
                                                },
                                                "at": {
                                                    "type": "string",
                                                    "description": "UTC, ISO 8601"
                                                },
                                                "venue": {
                                                    "type": "string",
                                                    "description": "opensea"
                                                }
                                            }
                                        },
                                        "median_7d": {
                                            "type": [
                                                "object",
                                                "null"
                                            ],
                                            "properties": {
                                                "usd": {
                                                    "type": [
                                                        "number",
                                                        "null"
                                                    ],
                                                    "description": "US dollars"
                                                },
                                                "sales": {
                                                    "type": "integer"
                                                }
                                            }
                                        },
                                        "median_30d": {
                                            "type": [
                                                "object",
                                                "null"
                                            ],
                                            "properties": {
                                                "usd": {
                                                    "type": [
                                                        "number",
                                                        "null"
                                                    ],
                                                    "description": "US dollars"
                                                },
                                                "sales": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                },
                                "physical": {
                                    "type": "object",
                                    "properties": {
                                        "value": {
                                            "type": [
                                                "object",
                                                "null"
                                            ],
                                            "properties": {
                                                "usd": {
                                                    "type": [
                                                        "number",
                                                        "null"
                                                    ],
                                                    "description": "US dollars"
                                                },
                                                "basis": {
                                                    "type": "string",
                                                    "description": "median_7d, median_30d, few_sales or lowest_listing"
                                                },
                                                "sales": {
                                                    "type": [
                                                        "integer",
                                                        "null"
                                                    ],
                                                    "description": "Sales behind a median or a blend, else null"
                                                },
                                                "estimate": {
                                                    "type": "boolean"
                                                }
                                            }
                                        },
                                        "lowest": {
                                            "type": [
                                                "object",
                                                "null"
                                            ],
                                            "properties": {
                                                "usd": {
                                                    "type": "number",
                                                    "description": "Item plus stated shipping, no tax"
                                                },
                                                "item": {
                                                    "type": "number"
                                                },
                                                "shipping": {
                                                    "type": [
                                                        "number",
                                                        "null"
                                                    ],
                                                    "description": "US dollars"
                                                },
                                                "shipping_at_checkout": {
                                                    "type": "boolean"
                                                },
                                                "ape": {
                                                    "type": "number",
                                                    "description": "BAYC P2P only"
                                                },
                                                "estimate": {
                                                    "type": "boolean"
                                                },
                                                "venue": {
                                                    "type": "string",
                                                    "description": "ebay, p2p or grimys"
                                                },
                                                "condition": {
                                                    "type": [
                                                        "string",
                                                        "null"
                                                    ],
                                                    "description": "As the seller states it"
                                                },
                                                "country": {
                                                    "type": [
                                                        "string",
                                                        "null"
                                                    ],
                                                    "description": "The seller's country, ISO 3166 (null on BAYC P2P)"
                                                },
                                                "url": {
                                                    "type": "string",
                                                    "description": "Through the site's redirect, which checks the listing is still up"
                                                }
                                            }
                                        },
                                        "listed": {
                                            "type": "integer"
                                        },
                                        "last_sold": {
                                            "type": [
                                                "object",
                                                "null"
                                            ],
                                            "properties": {
                                                "usd": {
                                                    "type": [
                                                        "number",
                                                        "null"
                                                    ],
                                                    "description": "US dollars"
                                                },
                                                "at": {
                                                    "type": "string",
                                                    "description": "UTC, ISO 8601; a date alone when only the day is known"
                                                },
                                                "venue": {
                                                    "type": "string",
                                                    "description": "ebay or p2p"
                                                },
                                                "estimate": {
                                                    "type": "boolean"
                                                }
                                            }
                                        },
                                        "median_7d": {
                                            "type": [
                                                "object",
                                                "null"
                                            ],
                                            "properties": {
                                                "usd": {
                                                    "type": [
                                                        "number",
                                                        "null"
                                                    ],
                                                    "description": "US dollars"
                                                },
                                                "sales": {
                                                    "type": "integer"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "as_of": {
                        "type": "object",
                        "properties": {
                            "digital": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "description": "When the digital feed was last read"
                            },
                            "physical": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "description": "When the printed markets were last read"
                            },
                            "sales": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "description": "When the sales were last read"
                            }
                        }
                    },
                    "url": {
                        "type": "string"
                    },
                    "attribution": {
                        "type": "object",
                        "properties": {
                            "text": {
                                "type": "string",
                                "description": "The line to show"
                            },
                            "url": {
                                "type": "string",
                                "description": "The page to link"
                            }
                        }
                    }
                }
            },
            "ValuesFile": {
                "type": "object",
                "properties": {
                    "as_of": {
                        "type": "object",
                        "properties": {
                            "digital": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "description": "When the digital feed was last read"
                            },
                            "physical": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "description": "When the printed markets were last read"
                            },
                            "sales": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "description": "When the sales were last read"
                            }
                        }
                    },
                    "rules": {
                        "type": "object"
                    },
                    "count": {
                        "type": "integer"
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string"
                                },
                                "set": {
                                    "type": "string"
                                },
                                "number": {
                                    "type": [
                                        "integer",
                                        "null"
                                    ]
                                },
                                "name": {
                                    "type": "string"
                                },
                                "rarity": {
                                    "type": "string"
                                },
                                "finish": {
                                    "type": "string",
                                    "description": "base, foil or any"
                                },
                                "digital_value": {
                                    "type": [
                                        "number",
                                        "null"
                                    ],
                                    "description": "US dollars"
                                },
                                "digital_basis": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "description": "median_7d, median_30d, few_sales, lowest_listing or rarity_median"
                                },
                                "digital_low": {
                                    "type": [
                                        "number",
                                        "null"
                                    ],
                                    "description": "US dollars"
                                },
                                "digital_last_sold": {
                                    "type": [
                                        "number",
                                        "null"
                                    ],
                                    "description": "US dollars"
                                },
                                "physical_value": {
                                    "type": [
                                        "number",
                                        "null"
                                    ],
                                    "description": "US dollars"
                                },
                                "physical_basis": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "description": "median_7d, median_30d, few_sales or lowest_listing"
                                },
                                "physical_low": {
                                    "type": [
                                        "number",
                                        "null"
                                    ],
                                    "description": "US dollars"
                                },
                                "physical_venue": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "description": "ebay, p2p or grimys"
                                },
                                "physical_last_sold": {
                                    "type": [
                                        "number",
                                        "null"
                                    ],
                                    "description": "US dollars"
                                },
                                "url": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "attribution": {
                        "type": "object",
                        "properties": {
                            "text": {
                                "type": "string",
                                "description": "The line to show"
                            },
                            "url": {
                                "type": "string",
                                "description": "The page to link"
                            }
                        }
                    }
                }
            }
        }
    }
}