{
 "openapi": "3.1.0",
 "info": {
  "title": "Collectibles Multiverse buyer directory",
  "version": "1.1.0",
  "description": "Who is buying old and used collectibles, from which countries, and what they say they pay. Prices are the buyers' own statements. Private data is never exposed.",
  "license": {
   "name": "CC BY 4.0 (credit Collectibles Multiverse and link the source)",
   "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "contact": {
   "name": "Collectibles Multiverse",
   "url": "https://collectiblesmultiverse.com/partners",
   "email": "hello@collectiblesmultiverse.com"
  }
 },
 "servers": [
  {
   "url": "https://collectiblesmultiverse.com"
  }
 ],
 "paths": {
  "/api/search": {
   "get": {
    "operationId": "searchBuyers",
    "summary": "Find active buyers for an item",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "What is being sold, e.g. 'Kenner Star Wars figures'"
     },
     {
      "name": "country",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "ISO 3166-1 alpha-2 code of where the items are"
     },
     {
      "name": "cat",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "vintage-toys",
        "action-figures",
        "comics",
        "football-stickers-cards",
        "sports-memorabilia",
        "advertising",
        "retro-games",
        "models-trains",
        "dolls-playsets",
        "fast-food-toys",
        "tcg",
        "sports-cards",
        "coins-banknotes",
        "stamps-postcards",
        "construction-sets",
        "vinyl-figures",
        "film-tv",
        "music",
        "other"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Matching buyers",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "count": {
           "type": "integer"
          },
          "results": {
           "type": "array",
           "items": {
            "allOf": [
             {
              "$ref": "#/components/schemas/Buyer"
             },
             {
              "type": "object",
              "properties": {
               "matched": {
                "type": "array",
                "items": {
                 "$ref": "#/components/schemas/Want"
                }
               }
              }
             }
            ]
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/buyers/{id}": {
   "get": {
    "operationId": "getBuyer",
    "summary": "One buyer's public listing",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Buyer",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Buyer"
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/api/stats": {
   "get": {
    "operationId": "getStats",
    "summary": "Active buyers, countries, open seller lists and 30-day search demand by category",
    "responses": {
     "200": {
      "description": "Totals"
     }
    }
   }
  },
  "/api/rates": {
   "get": {
    "operationId": "getRates",
    "summary": "European Central Bank daily euro reference rates used for conversion",
    "responses": {
     "200": {
      "description": "Rates"
     }
    }
   }
  },
  "/api/demand": {
   "get": {
    "operationId": "getDemandIndex",
    "summary": "Buy-Side Demand Index for a week",
    "parameters": [
     {
      "name": "week",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "ISO week like 2026-W38, or 'current'. Default: latest completed week."
     }
    ],
    "responses": {
     "200": {
      "description": "Snapshot with per-category buyers, median offers (EUR), searches and seller lists"
     },
     "404": {
      "description": "No snapshot"
     }
    }
   }
  },
  "/api/pulse": {
   "get": {
    "summary": "Live totals, trending categories and newest wanted items",
    "operationId": "getPulse",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/wanted": {
   "get": {
    "summary": "Every active buy request, newest first",
    "operationId": "getWanted",
    "parameters": [
     {
      "name": "cat",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Category id"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/events": {
   "get": {
    "summary": "Collector events worldwide",
    "operationId": "getEvents",
    "parameters": [
     {
      "name": "country",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "ISO 3166 alpha-2"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/guides.json": {
   "get": {
    "summary": "Original collector guides with URLs to cite",
    "operationId": "getGuides",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Buyer": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "kind": {
      "type": "string",
      "enum": [
       "dealer",
       "shop",
       "collector"
      ]
     },
     "country": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2"
     },
     "currency": {
      "type": "string",
      "description": "ISO 4217 currency the buyer pays in"
     },
     "about": {
      "type": "string"
     },
     "terms": {
      "type": "string"
     },
     "website": {
      "type": "string"
     },
     "buys_from": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "WW = worldwide, EU = European Union, or country codes"
     },
     "categories": {
      "type": "array",
      "items": {
       "type": "string",
       "enum": [
        "vintage-toys",
        "action-figures",
        "comics",
        "football-stickers-cards",
        "sports-memorabilia",
        "advertising",
        "retro-games",
        "models-trains",
        "dolls-playsets",
        "fast-food-toys",
        "tcg",
        "sports-cards",
        "coins-banknotes",
        "stamps-postcards",
        "construction-sets",
        "vinyl-figures",
        "film-tv",
        "music",
        "other"
       ]
      }
     },
     "items": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Want"
      }
     },
     "verified": {
      "type": "boolean"
     },
     "buyer_since": {
      "type": "integer",
      "description": "Unix time"
     },
     "confirmed_at": {
      "type": "integer",
      "description": "Unix time the buyer last confirmed they are buying"
     },
     "contacts_90d": {
      "type": "integer"
     },
     "response_rate": {
      "type": [
       "integer",
       "null"
      ],
      "description": "Percent of sellers answered in 90 days; null under 3 contacts"
     }
    }
   },
   "Want": {
    "type": "object",
    "properties": {
     "what": {
      "type": "string"
     },
     "cat": {
      "type": "string",
      "enum": [
       "vintage-toys",
       "action-figures",
       "comics",
       "football-stickers-cards",
       "sports-memorabilia",
       "advertising",
       "retro-games",
       "models-trains",
       "dolls-playsets",
       "fast-food-toys",
       "tcg",
       "sports-cards",
       "coins-banknotes",
       "stamps-postcards",
       "construction-sets",
       "vinyl-figures",
       "film-tv",
       "music",
       "other"
      ]
     },
     "min": {
      "type": [
       "number",
       "null"
      ]
     },
     "max": {
      "type": [
       "number",
       "null"
      ]
     },
     "cond": {
      "type": "string"
     },
     "note": {
      "type": "string"
     }
    },
    "description": "Something the buyer buys. min/max null means offer on request."
   }
  }
 },
 "externalDocs": {
  "description": "Open data hub, licence and citation",
  "url": "https://collectiblesmultiverse.com/data"
 }
}