{
  "openapi": "3.0.1",
  "info": {
    "title": "HipPostcard Scraper — Postcard Prices, Listings & Sellers",
    "description": "Scrape HipPostcard collectible-postcard 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": "2fgeFsVHgTYdQZRca"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapersdelight~hippostcard-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapersdelight-hippostcard-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~hippostcard-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapersdelight-hippostcard-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~hippostcard-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapersdelight-hippostcard-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 HipPostcard's own search, e.g. 'real photo new york', 'halloween postcard', 'linen 1940s'. 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 (hippostcard.com/store/shop-postcards-50-off-for-all-free-shipping-over-50-in-usa) or the seller's username (e.g. ShopPostcards). Combine with a keyword to search inside that store."
          },
          "startUrls": {
            "title": "HipPostcard links",
            "type": "array",
            "description": "Optional: paste HipPostcard 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. 59259938) 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). Applied by HipPostcard'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) — bargain filter. Applied by HipPostcard'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 HipPostcard's search.",
            "default": "all"
          },
          "categoryId": {
            "title": "Category ID",
            "minimum": 1,
            "type": "integer",
            "description": "Optional HipPostcard category (the number in a category link, hippostcard.com/category/new-york/12228/). Categories are places and topics: 12164 United States, 29081 Europe, 29746 France, 28826 Africa, 2056 Topics (Themes), 2059 Other / Unsorted."
          },
          "condition": {
            "title": "Condition",
            "enum": [
              "any",
              "unused",
              "postally-used"
            ],
            "type": "string",
            "description": "Only listings the seller marked with this condition. Applied by HipPostcard's search (most sellers leave it unset).",
            "default": "any"
          },
          "postcardType": {
            "title": "Postcard type",
            "enum": [
              "any",
              "real-photo",
              "chrome",
              "linen",
              "lithograph"
            ],
            "type": "string",
            "description": "Only listings the seller marked with this postcard type. Applied by HipPostcard's search (most sellers leave it unset — a keyword such as 'rppc' or 'linen' finds more).",
            "default": "any"
          },
          "onSaleOnly": {
            "title": "Only listings on sale",
            "type": "boolean",
            "description": "Only listings the seller marked down (they show a 'was' price, `original_price`). Applied by HipPostcard's search.",
            "default": false
          },
          "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. 'mint', 'cgc', '9.8')."
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "default",
              "newest",
              "price_asc",
              "price_desc",
              "ending_soon",
              "most_viewed"
            ],
            "type": "string",
            "description": "HipPostcard'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 HipPostcard'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 HipPostcard'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 HipPostcard 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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}