{"openapi":"3.1.0","info":{"title":"Scope API","version":"1.0.0","description":"HTTP mirror of the Scope tool kernel. Same API keys, scopes, and spend ledger as MCP."},"servers":[{"url":"https://scope.online/v1"}],"paths":{"/whoami":{"get":{"operationId":"whoami","summary":"Returns the authenticated Scope plan. Default view=compact is plan, remaining, committed burn, this_business, weekly_brief, headline_scan_id, and next[]. Pass view=full for last_spend, upgrade_policy, skip_engines_down, recent_spend, grader_hint, and rate-limit status. Selected-business keys report this_business prompts for the allowed business. business_id is required when the key can access more than one business. next[] names the next read.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":false,"schema":{"type":"string","description":"Optional business to label the weekly brief for","format":"uuid"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["compact","full"],"default":"compact","description":"compact is the default card; full returns the kitchen-sink payload."}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_readiness_score":{"get":{"operationId":"get_readiness_score","summary":"Scores any website for AI-readiness (schema, entity, FAQ, crawlability). Foreign URLs return not_in_account with next: [] — never add_business. Owned sites with no scan return a structured no_scan payload. Use when the user pastes a URL and asks if the site is ready for AI search.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","description":"Public website URL","format":"uri"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/list_businesses":{"get":{"operationId":"list_businesses","summary":"Lists businesses this key can access with the latest visibility snapshot and scheduled check burn. next[] is add_business when empty and allowed, or run_scan when a business has no scan. Use when the user asks which sites or brands are in Scope, or before choosing a business_id.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/list_tracked_prompts":{"get":{"operationId":"list_tracked_prompts","summary":"Lists every active tracked prompt for a business with id, text (user_text, never stuffed compiled_text), compiled_text for grader audit, interval_label, and burn_per_prompt so you can audit committed burn. Also returns proposed_prompts left to enroll. Cadence is the check interval (default every 5 days), not a calendar month. Free.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_engine_status":{"get":{"operationId":"get_engine_status","summary":"Returns whether ChatGPT, Claude, Gemini, and Perplexity are green, degraded, down, unknown, or stale. Down only if a recent attempt failed or a live probe failed. Engines skipped on the last scan are unknown, not down, and will be included in the next run_scan. grok is not_in_product. Free. No spend.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":false,"schema":{"type":"string","description":"Optional business whose latest scan outages should be included","format":"uuid"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/update_business":{"post":{"operationId":"update_business","summary":"Updates name, industry, city, state, disambiguation, description, services, value proposition, audience, differentiators, money_pages, or primary flag for an owned business. Free. Requires business:write. money_pages are existing URLs recs must target.","tags":["action"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"business_id":{"type":"string","description":"Owned Scope business ID","format":"uuid"},"name":{"type":"string","description":"Business name"},"industry":{"type":"string","description":"Industry"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State or region"},"disambiguation":{"type":"string","description":"One-sentence entity disambiguation"},"description":{"type":"string","description":"What the product is, in one or two sentences"},"value_proposition":{"type":"string","description":"Primary customer promise"},"target_audience":{"type":"string","description":"Who this is for"},"services":{"type":"array","items":{"type":"string"},"description":"Services or product lines"},"key_differentiators":{"type":"array","items":{"type":"string"},"description":"Short differentiators"},"money_pages":{"type":"array","items":{"type":"string"},"description":"Existing URLs or paths recs must target. Do not invent new guides."},"never_new_url":{"type":"boolean","description":"If true, generate_fix may only edit registered money_pages"},"price_url":{"type":"string","description":"Existing pricing URL"},"homonym_pack":{"type":"object","description":"Structured us/not entities for scoring. Not copy to paste under H1."},"index_status":{"type":"string","enum":["unknown","indexed","not_indexed"],"description":"unknown | indexed | not_indexed"},"webhook_url":{"type":"string","description":"HTTPS URL for why-first scan-complete payloads"},"is_primary":{"type":"boolean","description":"Set this business as primary"}},"required":["business_id"]}}}},"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/set_primary_business":{"post":{"operationId":"set_primary_business","summary":"Sets the account primary business used for unlabeled weekly briefs. Free. Requires business:write.","tags":["action"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"business_id":{"type":"string","description":"Owned Scope business ID","format":"uuid"}},"required":["business_id"]}}}},"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_visibility_report":{"get":{"operationId":"get_visibility_report","summary":"Returns the current AI visibility score. Default view=compact is score, scorer_version, engines attempted/measured, mention-kind counts, cite_kind_split (ours/other), derived issues, and trend points with scorer_version. Pass view=full for the per-engine dump. Failed engines are not_measured and excluded from the score. Issues cannot contradict an engine that appeared. If the business has no scan yet, returns a structured no_scan payload with next: [run_scan]. Use when the user asks how visible they are in AI search.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["compact","full"],"default":"compact"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_ai_traffic":{"get":{"operationId":"get_ai_traffic","summary":"Returns AI-referral landings from a connected GA4 property: path, sessions, engine, is_money_page, and latest-scan mention-kind for that engine. When Search Console is not linked, gsc is not_connected and queries are omitted (an empty queries list is not 'no queries'). Use when the user asks whether AI visibility is turning into visits.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"default":28}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_google_connect_url":{"get":{"operationId":"get_google_connect_url","summary":"Returns the dashboard URL a human uses to connect Google Analytics and Search Console. Free. Use when get_ai_traffic or get_crawler_visits is not_connected.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":false,"schema":{"type":"string","description":"Optional owned business to label the connect URL","format":"uuid"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_scan":{"get":{"operationId":"get_scan","summary":"Returns one scan by id: queued, running, completed, completed_partial, or failed, plus engines_attempted vs engines_measured, engine errors, prompts_billed/prompts_scored, prompts_scored_count/prompts_billed_count, progress_percent, scorer_version, and whether competitors, citations, and recommendations are ready. status is completed_partial when the grid is incomplete. Default view=compact hides vs_previous.cells (delta only). Pass view=full for the cell dump. While queued or running, includes last_spend from the account pool so a debit on another business is not mistaken for a silent rescan. Free. Poll this after run_scan instead of get_visibility_report.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"scan_id","in":"query","required":true,"schema":{"type":"string","description":"Scan ID returned by run_scan","format":"uuid"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["compact","full"],"default":"compact"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_scan_diff":{"get":{"operationId":"get_scan_diff","summary":"Compares two scans for the same business: prompts added/removed, engines measured, scorer_version, and score delta. Free. Use when a trend is uninterpretable.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}},{"name":"scan_a","in":"query","required":true,"schema":{"type":"string","description":"Older scan ID","format":"uuid"}},{"name":"scan_b","in":"query","required":true,"schema":{"type":"string","description":"Newer scan ID","format":"uuid"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_prompt_results":{"get":{"operationId":"get_prompt_results","summary":"Returns paginated results for the tracked prompt set from the latest headline scan. Default is one latest cell per (prompt, engine), ChatGPT first. Default view=rollup. Optional engine=chatgpt, include_previous for history, snippet_chars (default 400). Per-cell fields include scan_id, cited_urls, cited_ours, cited_money_page, search_queries, and status (recommended / mentioned / omitted / collision / error). Free.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["cells","rollup","matrix"],"default":"rollup"}},{"name":"include_snippets","in":"query","required":false,"schema":{"type":"boolean","default":false,"description":"Default false. Set true only when you need response_snippet."}},{"name":"snippet_chars","in":"query","required":false,"schema":{"type":"integer","minimum":40,"maximum":2000,"default":400}},{"name":"engine","in":"query","required":false,"schema":{"type":"string","description":"Optional engine filter, e.g. chatgpt"}},{"name":"include_previous","in":"query","required":false,"schema":{"type":"boolean","default":false,"description":"Include older cells in the same scan. Default is latest per prompt+engine."}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_citations":{"get":{"operationId":"get_citations","summary":"Returns sources AI engines cite. Default view=compact is counts, top domains, cite_kind split, and top URLs. Pass view=full for the full citation dump. Use when the user asks who ChatGPT cites or which sources they are missing.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}},{"name":"prompt_id","in":"query","required":false,"schema":{"type":"string","description":"Optional prompt text or id to filter citations"}},{"name":"engine","in":"query","required":false,"schema":{"type":"string","description":"Optional engine filter, e.g. chatgpt"}},{"name":"view","in":"query","required":false,"schema":{"type":"string","enum":["compact","full"],"default":"compact"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_competitors":{"get":{"operationId":"get_competitors","summary":"Returns the measured competitor set and share-of-voice across AI engines. Use when the user asks who AI recommends instead of them.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/pin_competitors":{"post":{"operationId":"pin_competitors","summary":"Replaces the pinned competitor list for a business so Scope stops inventing names. Optional websites persist as competitor_website. Free. Requires business:write.","tags":["action"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"business_id":{"type":"string","description":"Owned Scope business ID","format":"uuid"},"names":{"type":"array","items":{"type":"string"},"description":"Competitor names to pin"},"websites":{"type":"array","items":{"type":"string"},"description":"Optional websites aligned with names"}},"required":["business_id","names"]}}}},"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_recommendations":{"get":{"operationId":"get_recommendations","summary":"Returns a prioritized fix list with id, rec_type, winner, winner_url (computed from cited_url), cited_url and target_url as separate fields, expected impact, and blocks_prompt_ids. Never returns an empty list when the scan already knows who won. Pass recommendation id to generate_fix.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_citation_briefs":{"get":{"operationId":"get_citation_briefs","summary":"Returns citation-backed content briefs for measured losses only. Includes urls_to_earn, ChatGPT search_queries (fan-out), and a short outline. Engine errors are not treated as losses. Use when the user asks what to write next. Drafts only — never auto-publishes.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_crawler_visits":{"get":{"operationId":"get_crawler_visits","summary":"Returns first-party AI crawler hits ingested from the WordPress snippet or plugin. Empty until a key reports hits — that is not a Google Analytics connection. Use when the user asks which AI bots read which pages.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/add_business":{"post":{"operationId":"add_business","summary":"Idempotently adds a business by normalized domain, scrapes the site, and seeds ~20 tracked plus ~20 proposed prompts. Free (no check debit). Requires business:create and an all-businesses key. Use when the user wants to monitor a new site.","tags":["action"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","description":"Canonical public website URL","format":"uri"},"name":{"type":"string","description":"Business name"},"city":{"type":"string","description":"City"},"state":{"type":"string","description":"State or region"},"industry":{"type":"string","description":"Industry"}},"required":["url","name"]}}}},"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/run_scan":{"post":{"operationId":"run_scan","summary":"Runs every tracked prompt across currently green engines (omit Gemini/Perplexity while down). Optional engines allowlist. force retries not_measured cells only and quotes those cells, not the full set. check_prompt is the 1-check quote for a single query. confirm defaults false. Poll get_scan until completed or partial.","tags":["action"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"business_id":{"type":"string","description":"Owned Scope business ID","format":"uuid"},"confirm":{"type":"boolean","default":false,"description":"If false, return a quote only. If true, spend and start the scan."},"use_defaults":{"type":"boolean","default":false,"description":"Allow Scope's 4 generated prompts when the business has no tracked set."},"force":{"type":"boolean","default":false,"description":"Pass true to run a fresh scan even if one already completed today. Required when: the tracked prompt set changed since today's scan ran; today's scan has engine_errors (Gemini/Perplexity failed cells that were billed but not measured); or the previous scan used generated defaults but the account now has tracked prompts."},"engines":{"type":"array","items":{"type":"string","enum":["chatgpt","claude","perplexity","gemini"]},"description":"Optional allowlist. Omit Gemini while it is down so the scan does not wait on it."},"idempotency_key":{"type":"string","description":"Stable caller-provided idempotency key"}},"required":["business_id"]}}}},"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/check_prompt":{"post":{"operationId":"check_prompt","summary":"Tests one prompt across engines without tracking it. confirm defaults false (quote only). Costs exactly 1 check when confirm is true. Use to try a query before adding it to monitoring.","tags":["action"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"business_id":{"type":"string","description":"Owned Scope business ID","format":"uuid"},"prompt":{"type":"string","description":"Prompt to test","maxLength":500},"confirm":{"type":"boolean","default":false,"description":"If false, return a quote only."},"idempotency_key":{"type":"string","description":"Stable caller-provided idempotency key"}},"required":["business_id","prompt"]}}}},"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/diff_prompt":{"get":{"operationId":"diff_prompt","summary":"Returns the last two measured results for one compiled prompt across engines. Free. Use after publishing a fix to see whether mention moved omit/collide → win.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}},{"name":"prompt","in":"query","required":true,"schema":{"type":"string","description":"Prompt text or compiled_text"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/track_prompt":{"post":{"operationId":"track_prompt","summary":"Starts recurring monitoring for a prompt. Free now; adds committed burn from check_interval_days (default every 5 days). Returns compiled_text, collision_risk, and a substitute. Refuse collision_risk > 0.7 unless confirm_ambiguous is true. Requires prompts:write.","tags":["action"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"business_id":{"type":"string","description":"Owned Scope business ID","format":"uuid"},"prompt":{"type":"string","description":"Prompt to track","maxLength":500},"cadence":{"type":"string","enum":["monthly","weekly"],"default":"monthly"},"confirm_ambiguous":{"type":"boolean","default":false,"description":"Required when collision_risk is above 0.7"}},"required":["business_id","prompt"]}}}},"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/untrack_prompt":{"post":{"operationId":"untrack_prompt","summary":"Stops monitoring a prompt and reduces committed burn. Requires prompts:write.","tags":["action"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"business_id":{"type":"string","description":"Owned Scope business ID","format":"uuid"},"prompt_id":{"type":"string","description":"Tracked prompt ID","format":"uuid"}},"required":["business_id","prompt_id"]}}}},"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/generate_fix":{"post":{"operationId":"generate_fix","summary":"Drafts an outline (schema, FAQ, section copy, or an off-site checklist) from a recommendation_id or a brief/snippet ({ prompt, cited_url, winner, rec_type }). Off-site drafts (Reddit / YouTube / Wikidata / crawler) are checklists, never auto-posted. Drafts are outlines, not shippable markdown and not a live CMS diff. Edits the existing money-page target_url or returns { draft: null, why }. Never writes to the website or CMS. Never auto-publishes.","tags":["action"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"recommendation_id":{"type":"string","description":"Owned recommendation ID","format":"uuid"},"business_id":{"type":"string","description":"Required when drafting from a brief instead of a recommendation","format":"uuid"},"prompt":{"type":"string","description":"Losing prompt from a citation brief"},"cited_url":{"type":"string","description":"URL engines already cite"},"winner":{"type":"string","description":"Named alternative from the losing answer"},"rec_type":{"type":"string","description":"entity_disambiguation | faq | comparison_table | on_site_guide | ugc_reddit | ugc_youtube | entity_wikidata | crawler_access | quotable_proof | off_site_target"}}}}}},"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/complete_recommendation":{"post":{"operationId":"complete_recommendation","summary":"Marks a recommendation done or dismissed. Pass status=dismissed with a reason when the rec is wrong (Yext-on-SMS). Requires business:write.","tags":["action"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"recommendation_id":{"type":"string","description":"Owned recommendation ID","format":"uuid"},"note":{"type":"string","description":"Completion note","maxLength":2000},"fix_url":{"type":"string","description":"Link to the applied fix","format":"uri"},"status":{"type":"string","enum":["completed","dismissed"],"description":"dismissed = won't fix / bad rec"},"reason":{"type":"string","description":"Why this rec was dismissed","maxLength":500}},"required":["recommendation_id"]}}}},"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_roundup_watchlist":{"get":{"operationId":"get_roundup_watchlist","summary":"Independent roundup URLs already cited in the headline scan. Excludes competitor-owned and vendor docs. Use this instead of pitching Housecall Pro or Google Support. Free.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/update_roundup_status":{"post":{"operationId":"update_roundup_status","summary":"Sets not_pitched | pitched | listed | cited_us on an independent roundup URL. Free. Requires business:write.","tags":["action"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"business_id":{"type":"string","description":"Owned Scope business ID","format":"uuid"},"url":{"type":"string","description":"Roundup URL"},"status":{"type":"string","enum":["not_pitched","pitched","listed","cited_us"]}},"required":["business_id","url","status"]}}}},"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}},"/get_money_page_gap":{"get":{"operationId":"get_money_page_gap","summary":"Per tracked prompt: registered money page vs the URL ChatGPT actually cited. Use when the model knows you from /about instead of the compare or product URL.","tags":["read"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":true,"schema":{"type":"string","description":"Owned Scope business ID","format":"uuid"}},{"name":"engine","in":"query","required":false,"schema":{"type":"string","default":"chatgpt"}}],"responses":{"200":{"description":"Tool payload. Agent chrome is in meta."},"401":{"description":"Missing or invalid API key."},"403":{"description":"Missing scope or Growth required."},"404":{"description":"Unknown tool or resource."},"405":{"description":"Wrong HTTP method for this tool."},"429":{"description":"Rate limited."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}}}}