{
  "openapi": "3.0.1",
  "info": {
    "title": "PricePulse AI — Cross-Marketplace Product Intelligence",
    "description": "Track competitor products across Amazon, eBay, and Walmart and return AI-ready product-intelligence snapshots: cross-marketplace prices, change flags, review summaries, and opportunity insights — in one MCP-friendly call.",
    "version": "0.2",
    "x-build-id": "R8eTQFzsQYcgml4uN"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/entranced_gelato~price-pulse-ai/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-entranced_gelato-price-pulse-ai",
        "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/entranced_gelato~price-pulse-ai/runs": {
      "post": {
        "operationId": "runs-sync-entranced_gelato-price-pulse-ai",
        "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/entranced_gelato~price-pulse-ai/run-sync": {
      "post": {
        "operationId": "run-sync-entranced_gelato-price-pulse-ai",
        "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",
        "required": [
          "mode"
        ],
        "properties": {
          "mode": {
            "title": "Mode",
            "enum": [
              "product_list",
              "keyword_research"
            ],
            "type": "string",
            "description": "How to find products. 'product_list' tracks the ASINs/URLs you supply. 'keyword_research' discovers the top-N products per marketplace for a search term (strict cap via max_products_per_marketplace).",
            "default": "product_list"
          },
          "products": {
            "title": "Products to track",
            "type": "array",
            "description": "One entry per logical product group. Each entry needs either an ASIN or at least one URL on a supported marketplace OR any storefront with Schema.org Product JSON-LD. 'label' is your stable grouping key — pick something memorable like 'my_main_chair'. Max 25 entries per run.",
            "default": []
          },
          "marketplaces": {
            "title": "Marketplaces (bundled — adding sites does NOT add cost)",
            "uniqueItems": true,
            "type": "array",
            "description": "Which dedicated marketplaces to query. Subset of ['amazon', 'ebay', 'walmart']. All bundled into ONE snapshot — pay $0.04 once whether you query one site or all three. Any URL on a non-listed host (Target, Best Buy, Etsy, Shopify, etc.) falls through to the JSON-LD universal parser automatically.",
            "default": [
              "amazon"
            ],
            "items": {
              "type": "string"
            }
          },
          "include_reviews_summary": {
            "title": "Include reviews summary",
            "type": "boolean",
            "description": "Attach a reviews_summary block per product: themes + rating distribution. Rule-based by default (free, deterministic). Set enrichment_model='anthropic' for LLM-quality.",
            "default": true
          },
          "include_history": {
            "title": "Include price/rank history (last 30 days)",
            "type": "boolean",
            "description": "If true AND prior runs stored data in the KV store, attach a 30-day history block.",
            "default": false
          },
          "change_detection_baseline_key": {
            "title": "Change-detection baseline key",
            "type": "string",
            "description": "Any string — first run writes a baseline; later runs with the same key diff against it and overwrite. Use one key per tracking cadence (e.g., 'daily_chairs', 'hourly_bf2026').",
            "default": ""
          },
          "reference_label": {
            "title": "Reference product label (for vs-reference comparisons)",
            "type": "string",
            "description": "v0.2: when set, the product whose label/ASIN matches becomes the reference. Every OTHER snapshot gets a vs_reference block with price_delta + is_undercut vs. the reference. Useful for 'how do my competitors stack up against my product' questions.",
            "default": ""
          },
          "alert_webhook_url": {
            "title": "Webhook URL for significant price-change alerts",
            "type": "string",
            "description": "v0.2: when a snapshot's changes.price_change_flags contains a flag with abs(relative_pct) >= alert_undercut_pct AND significant=true, POST to this URL. Each successful POST is one chargeable webhook_alert_dispatched event at $0.005. Use HTTPS endpoints; query-string secrets are redacted from the snapshot record.",
            "default": ""
          },
          "alert_undercut_pct": {
            "title": "Webhook trigger threshold (% price drop)",
            "minimum": 0,
            "maximum": 99,
            "type": "integer",
            "description": "Minimum absolute relative price-change (in %) that fires an alert. Default 5. Higher values = fewer, more important alerts.",
            "default": 5
          },
          "use_apify_proxy": {
            "title": "Route fetches through Apify Residential proxy",
            "type": "boolean",
            "description": "v0.2: dramatically reduces Amazon CAPTCHA rate. Proxy bandwidth is billed by Apify to YOUR account (not bundled into this Actor's price). Recommended for daily/hourly runs on Amazon.",
            "default": false
          },
          "dry_run": {
            "title": "Dry run (preview without charging)",
            "type": "boolean",
            "description": "v0.2: build snapshots, write them to OUTPUT, but DO NOT push to the dataset and DO NOT charge. Lets you preview the output shape and verify the schema before committing to a paid run.",
            "default": false
          },
          "amazon_locale": {
            "title": "Amazon locale (for ASIN-derived URLs)",
            "enum": [
              "us",
              "uk",
              "de",
              "fr",
              "jp",
              "in",
              "ca",
              "au"
            ],
            "type": "string",
            "description": "v0.2: which amazon.<tld> host to use when only an ASIN (not a full URL) is provided. URLs you pass directly always override this.",
            "default": "us"
          },
          "user_notes": {
            "title": "Free-form notes (echoed in output for traceability)",
            "type": "string",
            "description": "Any context you want preserved in request_context. Useful for tagging runs in BI dashboards.",
            "default": ""
          },
          "enrichment_model": {
            "title": "Optional LLM enrichment for review summaries",
            "enum": [
              "none",
              "anthropic"
            ],
            "type": "string",
            "description": "'none' (default) = rule-based, no extra cost. 'anthropic' = call Claude Haiku for higher-quality themes (requires anthropic_api_key). Falls back to rule-based on any LLM failure.",
            "default": "none"
          },
          "anthropic_api_key": {
            "title": "Anthropic API key (only used if enrichment_model='anthropic')",
            "type": "string",
            "description": "Your Anthropic API key. Stored as a secret Apify input (never echoed in output, never logged). Get one at https://console.anthropic.com."
          },
          "max_products_per_marketplace": {
            "title": "Max products per marketplace (keyword_research mode)",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "v0.2: cap how many products keyword_research discovers per marketplace. Default 10, hard cap 50. Total products in the run is also bounded at 25 (global cap).",
            "default": 10
          },
          "keyword": {
            "title": "Search keyword (keyword_research mode)",
            "type": "string",
            "description": "Search term to discover top products. Used when mode='keyword_research'. Ignored otherwise.",
            "default": ""
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}