{
  "openapi": "3.0.1",
  "info": {
    "title": "HipStamp Scraper — Stamp Prices, Listings & Seller Data",
    "description": "Scrape HipStamp collectible-stamp listings — title, price, seller, condition, country & photos — by keyword or seller. No login or API key. Schedule it as a new-listing / price-drop monitor with Slack, email & webhook alerts. $4 per 1,000 listings.",
    "version": "0.1",
    "x-build-id": "Fs4qkoaOwtv5TvTNQ"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapersdelight~hipstamp-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapersdelight-hipstamp-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/scrapersdelight~hipstamp-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapersdelight-hipstamp-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/scrapersdelight~hipstamp-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapersdelight-hipstamp-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "keyword": {
            "title": "Keyword",
            "type": "string",
            "description": "Search text, run on HipStamp's own search (titles, Scott / SG numbers, countries, topics), e.g. 'benjamin franklin', 'penny black', 'germany 1936'. Leave empty to browse everything (or to read a whole seller store with 'Seller store')."
          },
          "searchQueries": {
            "title": "More keywords",
            "type": "array",
            "description": "Optional: several searches in one run. Each is read separately (up to 'Max listings' each) and every row says which search found it in `search_query`; a listing found by two searches is delivered once.",
            "items": {
              "type": "string"
            }
          },
          "sellerStore": {
            "title": "Seller store",
            "type": "string",
            "description": "Optional: one dealer only. Paste the store name from the store link (hipstamp.com/store/richards-stamps) or the seller's username (e.g. likeke). Combine with a keyword to search inside that store."
          },
          "startUrls": {
            "title": "HipStamp links",
            "type": "array",
            "description": "Optional: paste HipStamp search, category or store links (filters in the link are kept) or listing links. Each search link is read as its own search, up to 'Max listings'.",
            "items": {
              "type": "string"
            }
          },
          "listingUrls": {
            "title": "Listing IDs or links",
            "type": "array",
            "description": "Optional: look up specific listings by ID (e.g. 32961905) or listing link. Every one found is delivered (not limited by 'Max listings'). In monitor mode a listed listing is delivered again only when its price changed.",
            "items": {
              "type": "string"
            }
          },
          "priceMin": {
            "title": "Min price ($)",
            "minimum": 0,
            "type": "integer",
            "description": "Only listings priced at or above this (current price, USD). Applied by HipStamp's search. Leave empty for no floor."
          },
          "priceMax": {
            "title": "Max price ($)",
            "minimum": 0,
            "type": "integer",
            "description": "Only listings priced at or below this (current price, USD) — bargain filter. Applied by HipStamp's search. Leave empty for no cap."
          },
          "listingType": {
            "title": "Listing type",
            "enum": [
              "all",
              "fixed",
              "auction"
            ],
            "type": "string",
            "description": "Fixed-price (buy now) listings, auctions, or both. Applied by HipStamp's search.",
            "default": "all"
          },
          "categoryId": {
            "title": "Category ID",
            "minimum": 1,
            "type": "integer",
            "description": "Optional HipStamp category (the number in a category link, hipstamp.com/category/great-britain/8/). Top level: 1 Africa, 2 Asia, 3 Australia & Oceania, 5 Canada, 6 Caribbean, 7 Europe, 8 Great Britain, 9 Central & South America, 10 Middle East, 11 Worldwide, 12 United States, 13 Publications & Supplies, 14 Specialty Philately."
          },
          "condition": {
            "title": "Condition",
            "enum": [
              "any",
              "mint-nh",
              "unused",
              "used",
              "first-day-cover",
              "cover-postal-history"
            ],
            "type": "string",
            "description": "Only listings the seller marked with this condition. Applied by HipStamp's search.",
            "default": "any"
          },
          "issueCountry": {
            "title": "Country of issue",
            "type": "string",
            "description": "Optional: the stamp's country as HipStamp names it in the listing's item specifics, e.g. 'Great Britain', 'United States', 'Germany'. Applied by HipStamp's search."
          },
          "stampFormat": {
            "title": "Stamp format",
            "enum": [
              "any",
              "single",
              "pair",
              "block",
              "plate-block",
              "multiple",
              "souvenir-sheet",
              "miniature-sheet",
              "full-sheet",
              "plate-number-coil",
              "error"
            ],
            "type": "string",
            "description": "Only singles, blocks, sheets, … as the seller marked them. Applied by HipStamp's search.",
            "default": "any"
          },
          "certifiedOnly": {
            "title": "Only listings with a certificate",
            "type": "boolean",
            "description": "Only listings whose seller marked 'Has a certificate: Yes' (expertising certificate). Applied by HipStamp's search.",
            "default": false
          },
          "dealerAssociation": {
            "title": "Seller association",
            "enum": [
              "any",
              "aps",
              "ipda",
              "pts"
            ],
            "type": "string",
            "description": "Only sellers who are members of this dealer association. Applied by HipStamp's search.",
            "default": "any"
          },
          "conditionContains": {
            "title": "Title/condition contains",
            "type": "string",
            "description": "Optional extra filter on our side: keep only listings whose title or condition contains this text (e.g. 'MNH', 'imperf', 'plate 2')."
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "default",
              "newest",
              "price_asc",
              "price_desc",
              "ending_soon",
              "most_viewed",
              "catalog_number"
            ],
            "type": "string",
            "description": "HipStamp's own order, used to pick which listings come first when 'Max listings' cuts the list.",
            "default": "default"
          },
          "fetchDetails": {
            "title": "Fetch listing-page details",
            "type": "boolean",
            "description": "Also open each listing's page for what HipStamp's search does not return: watchers, sales history (sold prices + dates), offer history, auction bid history, and the seller's feedback score, positive %, member-since date and store name. One extra request per listing, billed per listing only when the details were added.",
            "default": true
          },
          "maxLots": {
            "title": "Max listings per search",
            "minimum": 0,
            "type": "integer",
            "description": "Cap per search (keyword, seller store or link). Defaults to 50 for a fast first run — set to 0 for every matching listing (also past HipStamp's own 10,000-result limit). In monitor mode: the most new listings delivered per search per run.",
            "default": 50
          },
          "monitorMode": {
            "title": "Monitor mode (new-listing watcher)",
            "type": "boolean",
            "description": "Recurring watcher: each run delivers only listings put up since the previous run of the same search (the first run delivers the newest listings and remembers where it stopped). Pair with an Apify Schedule.",
            "default": false
          },
          "alertOnNewLot": {
            "title": "Alert on new listings",
            "type": "boolean",
            "description": "In monitor mode, send an alert for each new listing to the channels below.",
            "default": true
          },
          "alertOnPriceChange": {
            "title": "Alert on price changes (watchlist)",
            "type": "boolean",
            "description": "In monitor mode, also alert when the price changes on a watched listing (see watchlist IDs).",
            "default": false
          },
          "watchlistIds": {
            "title": "Watchlist listing IDs",
            "type": "array",
            "description": "Listing IDs or links to check for price changes on every monitor run when 'Alert on price changes' is on (up to 200).",
            "items": {
              "type": "string"
            }
          },
          "webhookUrl": {
            "title": "Webhook URL",
            "type": "string",
            "description": "POST endpoint for alert payloads (Make / Zapier / n8n / custom)."
          },
          "slackWebhookUrl": {
            "title": "Slack webhook URL",
            "type": "string",
            "description": "Slack incoming-webhook URL for formatted alert cards."
          },
          "emailRecipients": {
            "title": "Email recipients",
            "type": "array",
            "description": "Email addresses for one alert digest per run (sent via apify/send-mail).",
            "items": {
              "type": "string"
            }
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Not needed: the actor connects directly and falls back to Apify's residential proxy (and then Apify's Unblocker) on its own if HipStamp refuses a connection. Set your own proxy here only if you want every request to go through it.",
            "default": {
              "useApifyProxy": false
            }
          },
          "requestConcurrency": {
            "title": "Request concurrency",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Listing pages read in parallel when 'Fetch listing-page details' is on.",
            "default": 5
          },
          "diagnose": {
            "title": "Diagnostic mode (dev)",
            "type": "boolean",
            "description": "Dev only. Saves one raw search answer and one listing page to the key-value store, logs the parsed first row, then exits.",
            "default": false
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}