NOSTOS

Search the live NOSTOS catalog of retro games, consoles, and vintage apparel. Free-text query plus platform, department, region, condition, and price filters. Returns online-buyable items by default. Every item is unique and individually graded.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Free-text match across name, description, genre, and platform. All words must match."
    },
    "platform": {
      "type": "string",
      "description": "Filter by platform (case-insensitive substring), e.g. 'Saturn', 'N64', 'Game Boy'."
    },
    "department": {
      "type": "string",
      "description": "Filter by department (substring), e.g. 'VG - Software', 'Apparel'."
    },
    "region": {
      "type": "string",
      "description": "Filter by exact region code, e.g. 'JP', 'US', 'PAL'."
    },
    "condition": {
      "type": "string",
      "description": "Filter by exact condition, e.g. 'Loose', 'CIB', 'New'."
    },
    "minPrice": {
      "type": "number",
      "minimum": 0,
      "description": "Minimum price in USD."
    },
    "maxPrice": {
      "type": "number",
      "minimum": 0,
      "description": "Maximum price in USD."
    },
    "includeSold": {
      "type": "boolean",
      "description": "Include sold and in-store-only items. Default false (online-buyable only)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Max results to return. Default 20."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Full details for one SKU: description, condition notes, price, region, image, and a direct product URL, plus real-time availability.

{
  "type": "object",
  "properties": {
    "sku": {
      "type": "string",
      "description": "The product SKU, e.g. 'NOST-VGS-0075'."
    }
  },
  "required": [
    "sku"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Real-time status (available, reserved, sold, or invalid) for up to 50 SKUs at once. The live source of truth; the catalog can lag a recent sale.

{
  "type": "object",
  "properties": {
    "skus": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 50,
      "description": "SKUs to check, up to 50, e.g. ['NOST-VGS-0075','NOST-VGS-0076']."
    }
  },
  "required": [
    "skus"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the console platforms currently in stock, each with a count of available items.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the store departments currently in stock (e.g. 'VG - Software', 'CLTH - Vintage Apparel'), each with a count of available items.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List the most recently added in-stock items, newest first. The answer to what is new at NOSTOS.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Max items to return. Default 10."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

NOSTOS store information: address, hours, contact, mission, tagline, categories, area served, social links, and current online and storefront status.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The NOSTOS condition grading vocabulary and the criteria for each grade, with region-code meanings. Optionally filter to one department.

{
  "type": "object",
  "properties": {
    "department": {
      "type": "string",
      "description": "Optional department filter, e.g. 'VG - Software', 'CLTH - Vintage Apparel'. Omit for the full rubric."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

What NOSTOS buys and declines, how cash and store-credit offers are calculated, bounty premiums, basket caps, the free shipping label threshold, and the trade-in process.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The NOSTOS return policy: 14-day window, eligible reasons, free return shipping on valid claims, refund timing, and the 110% store-credit option.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

How NOSTOS store credit works: the 15% uplift over cash, the in-store drop-off bonus, the return bonus, and redemption.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

The NOSTOS shipping policy for a destination country (US, Canada, or not-yet-active international), including the free prepaid trade-in label threshold. Policy, not a live carrier rate.

{
  "type": "object",
  "properties": {
    "destination_country": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "ISO-3166-1 alpha-2 destination country code, e.g. 'US', 'CA'."
    },
    "item_count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "Number of items. Default 1."
    }
  },
  "required": [
    "destination_country"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Estimated market value (loose, CIB, and new) for a game or console from current PriceCharting guide data, plus the NOSTOS cash and store-credit buy offers.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 2,
      "description": "Title to look up, e.g. 'Mario Kart 64'."
    },
    "platform": {
      "type": "string",
      "description": "Platform hint to disambiguate, e.g. 'N64', 'Saturn'."
    },
    "condition": {
      "type": "string",
      "enum": [
        "loose",
        "cib",
        "new"
      ],
      "description": "Optional condition to focus the result on."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Cash and store-credit totals for a basket of items to sell, with free-shipping eligibility and whether the basket routes to a personal review. Persists nothing. Provide each item's buyPrice from lookup_market_price.

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Optional client id for the item."
          },
          "name": {
            "type": "string",
            "description": "Item title."
          },
          "platform": {
            "type": "string",
            "description": "Platform, e.g. 'Nintendo 64'."
          },
          "condKey": {
            "type": "string",
            "enum": [
              "loose",
              "cib",
              "new",
              "manual"
            ],
            "description": "Condition key."
          },
          "condLabel": {
            "type": "string",
            "description": "Human condition label."
          },
          "buyPrice": {
            "type": "number",
            "minimum": 0,
            "description": "Per-item NOSTOS cash offer in USD, from lookup_market_price."
          }
        },
        "required": [
          "name",
          "platform",
          "condKey",
          "buyPrice"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 100,
      "description": "Basket of items to sell. Use lookup_market_price to get each item's buyPrice first."
    }
  },
  "required": [
    "items"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}