{
  "openapi": "3.0.1",
  "info": {
    "title": "Yelp Scraper - Review Sentiment & Reputation Monitor",
    "description": "Scrapes Yelp businesses and reviews, returns a ranked incident queue: which locations need attention first, why, and what changed. Review sentiment, complaint themes, rating-trajectory detection, comp-set benchmarking, monitor mode. Drop-in tri_angle replacement. $0.15/business analysed.",
    "version": "1.0",
    "x-build-id": "McgdcEbEAdUspUG1O"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/ryanclinton~yelp-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-ryanclinton-yelp-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/ryanclinton~yelp-scraper/runs": {
      "post": {
        "operationId": "runs-sync-ryanclinton-yelp-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/ryanclinton~yelp-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-ryanclinton-yelp-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": {
          "mode": {
            "title": "Mode",
            "enum": [
              "monitor",
              "search",
              "businesses",
              "reviews",
              "compset"
            ],
            "type": "string",
            "description": "Entry point. 'monitor' (default) tracks businesses over time and returns a ranked incident queue of only what changed - the killer mode; paste one business URL for the 10-second outcome. 'search' ranks a category in a city by reputation risk. 'businesses' analyses specific business URLs. 'reviews' pulls + synthesises reviews for a business. 'compset' ranks a business against its competitors. Same input shape as tri_angle/yelp-scraper.",
            "default": "monitor"
          },
          "track": {
            "title": "Business URLs to monitor (monitor mode)",
            "type": "array",
            "description": "Monitor mode: Yelp /biz/<slug> URLs to track over time. Each run returns only what changed since the last run - rating trajectory, new complaint themes, unanswered negatives, comp-set movement. Schedule a daily/weekly run across your locations.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "searchTerms": {
            "title": "Search terms (search mode)",
            "type": "array",
            "description": "Search mode: categories/keywords to search in the location below, e.g. [\"plumber\"] or [\"restaurants\"]. Results surface the reputation-at-risk and rising businesses first.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "location": {
            "title": "Location (search mode)",
            "type": "string",
            "description": "Search mode: the city / location to search in, e.g. 'Austin, TX'.",
            "default": ""
          },
          "businesses": {
            "title": "Business URLs (businesses / reviews mode)",
            "type": "array",
            "description": "Businesses or reviews mode: Yelp /biz/<slug> URLs to analyse. Each result carries its reputation state, review sentiment + theme synthesis, and a response-priority queue.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "rankBy": {
            "title": "Rank by",
            "enum": [
              "attention",
              "reputationRisk",
              "trajectory",
              "reviewVolume"
            ],
            "type": "string",
            "description": "How to order the queue. 'attention' uses the composite attentionIndex. 'reputationRisk' surfaces sliding/at-risk businesses first. 'trajectory' surfaces the steepest decliners. 'reviewVolume' orders by review count.",
            "default": "attention"
          },
          "maxBusinesses": {
            "title": "Max businesses (search mode)",
            "minimum": 1,
            "maximum": 240,
            "type": "integer",
            "description": "Maximum businesses to analyse in search mode. Coverage reports requested vs returned honestly.",
            "default": 50
          },
          "includeReviewsSample": {
            "title": "Include + synthesise reviews",
            "type": "boolean",
            "description": "When on (default), each business carries the deterministic review sentiment + theme synthesis (lexicon-tfidf-v1). Turn off for a faster substrate-only run.",
            "default": true
          },
          "reviewsSamplePerBusiness": {
            "title": "Maximum reviews to synthesise per business",
            "minimum": 0,
            "maximum": 2000,
            "type": "integer",
            "description": "Upper limit on reviews analysed per business. Reviews are taken from the business's own page, which publishes roughly 10 to 15, so raising this above that returns no extra reviews. The count actually analysed is reported per business in sampling.reviewsAnalyzed, next to sampling.reviewsAvailable.",
            "default": 20
          },
          "watchlistName": {
            "title": "Watchlist name (monitor mode)",
            "type": "string",
            "description": "Monitor mode: a stable name for this watchlist. State (rating/theme/incident history, recurrence, trajectory) persists in a named store keyed on this name across runs - the moat. Rename = a fresh memory clock. Defaults to a slug of the tracked URLs.",
            "default": ""
          },
          "deltaWindowDays": {
            "title": "Delta window (days)",
            "minimum": 1,
            "maximum": 90,
            "type": "integer",
            "description": "The comparison window for delta intelligence (what changed since the prior run).",
            "default": 7
          },
          "business": {
            "title": "Business URL (compset mode)",
            "type": "string",
            "description": "Compset mode: the Yelp /biz/<slug> URL of YOUR business - the anchor everything else is benchmarked against.",
            "default": ""
          },
          "competitors": {
            "title": "Competitor URLs (compset mode)",
            "type": "array",
            "description": "Compset mode: Yelp /biz/<slug> URLs of competitors to rank against the anchor business above.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "persona": {
            "title": "Persona",
            "enum": [
              "generic",
              "multi-location-ops",
              "owner",
              "agency",
              "researcher",
              "prospector"
            ],
            "type": "string",
            "description": "Reshapes materiality weights and which signals escalate. 'multi-location-ops' weights rating moves + negative themes across locations; 'owner' weights unanswered negatives; 'agency' weights comp-set position; 'researcher' weights theme surges. Orthogonal to mode and rankBy.",
            "default": "generic"
          },
          "outputProfile": {
            "title": "Output profile",
            "enum": [
              "signals",
              "compat",
              "minimal"
            ],
            "type": "string",
            "description": "'signals' (default) = full envelope: incident + signals + attention routing + reputation profile + review intelligence + trajectory + delta. 'compat' = exact tri_angle 5-field set + dataCompleteness, no signal fields (migration parity). 'minimal' = IDs + business name + rating only.",
            "default": "signals"
          },
          "analysisDepth": {
            "title": "Analysis depth",
            "enum": [
              "fast",
              "standard",
              "deep"
            ],
            "type": "string",
            "description": "'fast' = substrate + profile. 'standard' (default) = + signals + review intelligence. 'deep' = + full trajectory and recurrence.",
            "default": "standard"
          },
          "explainability": {
            "title": "Explainability",
            "enum": [
              "standard",
              "full"
            ],
            "type": "string",
            "description": "'standard' trims the heaviest diagnostic blocks (evidenceQuality, signalProfileEvidence). 'full' keeps everything.",
            "default": "standard"
          },
          "maxRuntimeSeconds": {
            "title": "Max runtime (seconds)",
            "minimum": 60,
            "maximum": 7200,
            "type": "integer",
            "description": "Soft runtime budget. The actor auto-clamps against the Apify timeout and emits partial output before a hard kill.",
            "default": 3600
          },
          "startUrls": {
            "title": "Start URLs (compat alias)",
            "type": "array",
            "description": "Drop-in migration: paste your existing tri_angle/yelp-scraper /biz/ URLs here. Mapped to businesses mode automatically. Use 'track' / 'businesses' / 'searchTerms' for new runs.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "searchQuery": {
            "title": "Search query (compat alias)",
            "type": "string",
            "description": "Drop-in migration: a single search term, mapped to search mode. Use 'searchTerms' for new runs.",
            "default": ""
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apify proxy. Defaults to RESIDENTIAL (required for Yelp's AWS WAF anti-bot layer). Leave as default unless you have a reason to change it.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}