{"openapi":"3.1.0","info":{"title":"aivisibilityskill API","version":"1.0.0","description":"AI visibility for your agent: ask ChatGPT, Gemini, Google AI Overviews / AI Mode, Perplexity, Claude, Grok and DeepSeek about your product, get brands, sources and facts with confidence ranges, and fix what's wrong.\n\n## Quickstart\n\n1. Get a key (aiv_test_… keys are a free sandbox with sample data; aiv_live_… keys spend credits).\n2. Ask a question:\n\n```sh\ncurl https://api.aivisibilityskill.com/v1/checks \\\n  -H \"Authorization: Bearer $AIV_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"questions\": [\"best invoicing app for freelancers\"], \"wait\": 60}'\n```\n\n3. Read `answers[].brands` (who is named, recommended, sentiment, exact quotes), `citations` (with source types) and `facts`. Not finished yet? `GET /v1/jobs/{id}` after `poll_after_seconds`.\n4. Track a product with `POST /v1/projects`, then `GET /v1/projects/{id}/visibility` for mention rates with confidence ranges.\n\n## Countries and languages\n\n`locale` is language-COUNTRY: `en-US` (default), `pt-BR`, `ja-JP`, `hi-IN`, `es-MX`. Any language works with any country an engine supports; `GET /v1/locales` (free, no key) lists them per engine, and a locale an engine can't do is refused before anything is charged.\n\n## Building for your own customers\n\n- Send `customer` (your id for your customer) and `metadata` (up to 20 strings) with checks and projects. Each customer's requests are kept apart in the 10-minute duplicate window.\n- `GET /v1/usage?group_by=day,customer` returns credits per customer (add `format=csv` for a spreadsheet).\n- `POST /v1/keys` with `customer` creates a key locked to that customer: it only sees and spends for that customer.\n\n## Webhooks\n\n`POST /v1/webhooks` with your https URL returns a signing secret (`whsec_…`, shown once). We then POST small JSON events: `check.completed` (answers in and read), `check.failed`, `action.completed` / `action.failed`, `schedule.skipped`, and `balance.low` (set the level with `PATCH /v1/account`). Fetch the details with `GET /v1/jobs/{id}` or `GET /v1/actions/{id}`.\n\nRequests are signed the Standard Webhooks way (`webhook-id`, `webhook-timestamp`, `webhook-signature`), so any Standard Webhooks library verifies them (Node: `new Webhook(secret).verify(rawBody, headers)` from `standardwebhooks`). By hand: base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{raw body}`, keyed with the base64-decoded part after `whsec_`, must equal one of the `v1,…` values; reject timestamps more than 5 minutes off.\n\nAnswer 2xx within 10 seconds and do the work afterwards. Failed deliveries retry for about 2.7 days (5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h, 14 h, 24 h); the same event can arrive twice, so dedupe on `webhook-id`. An endpoint that keeps failing for 2.5 days is paused and you're emailed; `POST /v1/webhooks/{id}/recover` resends what it missed, and `GET /v1/events` lists every event for 30 days. Test keys get webhooks too (`sandbox: true`), and `POST /v1/webhooks/{id}/test` sends a ping.\n\n## Money safety\n\n- `POST /v1/estimate` prices anything for free. Failed answers are never charged.\n- `max_credits` refuses a check above a cost; keys can have a `daily_budget` and a `confirm_above` threshold (agent keys default to the plan's agent cap — 10% of its monthly credits per day — and 300).\n- `Idempotency-Key` makes retries safe; identical requests within 10 minutes return the first job instead of charging again.\n\nErrors are `application/problem+json` with a stable `code`."},"servers":[{"url":"https://api.aivisibilityskill.com"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your API key: aiv_live_… (spends credits) or aiv_test_… (free sandbox)."}},"schemas":{"CheckCompletedEvent":{"type":"object","properties":{"id":{"type":"string","description":"Event id; also the webhook-id header. Dedupe on it."},"type":{"type":"string","enum":["check.completed"]},"timestamp":{"type":"string"},"sandbox":{"type":"boolean","description":"true for work done with a test (aiv_test_) key."},"data":{"type":"object","properties":{"object":{"type":"string","enum":["check"]},"id":{"type":"string"},"project_id":{"type":["string","null"]},"customer":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"credits":{"type":"object","properties":{"quoted":{"type":"integer"},"charged":{"type":"integer"},"refunded":{"type":"integer"}},"required":["quoted","charged","refunded"]},"created_at":{"type":"string"},"finished_at":{"type":"string"},"status":{"type":"string","enum":["succeeded","partial"]},"answers":{"type":"object","properties":{"total":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"}},"required":["total","succeeded","failed"]},"reading":{"type":"string","enum":["done","partial"]}},"required":["object","id","project_id","customer","metadata","credits","created_at","finished_at","status","answers","reading"]}},"required":["id","type","timestamp","sandbox","data"]},"CheckFailedEvent":{"type":"object","properties":{"id":{"type":"string","description":"Event id; also the webhook-id header. Dedupe on it."},"type":{"type":"string","enum":["check.failed"]},"timestamp":{"type":"string"},"sandbox":{"type":"boolean","description":"true for work done with a test (aiv_test_) key."},"data":{"type":"object","properties":{"object":{"type":"string","enum":["check"]},"id":{"type":"string"},"project_id":{"type":["string","null"]},"customer":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"credits":{"type":"object","properties":{"quoted":{"type":"integer"},"charged":{"type":"integer"},"refunded":{"type":"integer"}},"required":["quoted","charged","refunded"]},"created_at":{"type":"string"},"finished_at":{"type":"string"},"status":{"type":"string","enum":["failed"]},"answers":{"type":"object","properties":{"total":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"}},"required":["total","succeeded","failed"]},"failures":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"count":{"type":"integer"}},"required":["code","count"]}}},"required":["object","id","project_id","customer","metadata","credits","created_at","finished_at","status","answers","failures"]}},"required":["id","type","timestamp","sandbox","data"]},"ActionCompletedEvent":{"type":"object","properties":{"id":{"type":"string","description":"Event id; also the webhook-id header. Dedupe on it."},"type":{"type":"string","enum":["action.completed"]},"timestamp":{"type":"string"},"sandbox":{"type":"boolean","description":"true for work done with a test (aiv_test_) key."},"data":{"type":"object","properties":{"object":{"type":"string","enum":["action"]},"kind":{"type":"string"},"id":{"type":"string"},"project_id":{"type":["string","null"]},"customer":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"credits":{"type":"object","properties":{"quoted":{"type":"integer"},"charged":{"type":"integer"},"refunded":{"type":"integer"}},"required":["quoted","charged","refunded"]},"created_at":{"type":"string"},"finished_at":{"type":"string"},"status":{"type":"string","enum":["succeeded"]},"result_id":{"type":["string","null"]},"error":{"type":"null"}},"required":["object","kind","id","project_id","customer","metadata","credits","created_at","finished_at","status","result_id","error"]}},"required":["id","type","timestamp","sandbox","data"]},"ActionFailedEvent":{"type":"object","properties":{"id":{"type":"string","description":"Event id; also the webhook-id header. Dedupe on it."},"type":{"type":"string","enum":["action.failed"]},"timestamp":{"type":"string"},"sandbox":{"type":"boolean","description":"true for work done with a test (aiv_test_) key."},"data":{"type":"object","properties":{"object":{"type":"string","enum":["action"]},"kind":{"type":"string"},"id":{"type":"string"},"project_id":{"type":["string","null"]},"customer":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"credits":{"type":"object","properties":{"quoted":{"type":"integer"},"charged":{"type":"integer"},"refunded":{"type":"integer"}},"required":["quoted","charged","refunded"]},"created_at":{"type":"string"},"finished_at":{"type":"string"},"status":{"type":"string","enum":["failed"]},"result_id":{"type":"null"},"error":{"type":"string"}},"required":["object","kind","id","project_id","customer","metadata","credits","created_at","finished_at","status","result_id","error"]}},"required":["id","type","timestamp","sandbox","data"]},"ScheduleSkippedEvent":{"type":"object","properties":{"id":{"type":"string","description":"Event id; also the webhook-id header. Dedupe on it."},"type":{"type":"string","enum":["schedule.skipped"]},"timestamp":{"type":"string"},"sandbox":{"type":"boolean","description":"true for work done with a test (aiv_test_) key."},"data":{"type":"object","properties":{"object":{"type":"string","enum":["schedule"]},"project_id":{"type":"string"},"customer":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"run_at":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"},"job_id":{"type":["string","null"]}},"required":["object","project_id","customer","metadata","run_at","reason","message","job_id"]}},"required":["id","type","timestamp","sandbox","data"]},"BalanceLowEvent":{"type":"object","properties":{"id":{"type":"string","description":"Event id; also the webhook-id header. Dedupe on it."},"type":{"type":"string","enum":["balance.low"]},"timestamp":{"type":"string"},"sandbox":{"type":"boolean","description":"true for work done with a test (aiv_test_) key."},"data":{"type":"object","properties":{"object":{"type":"string","enum":["account"]},"balance":{"type":"integer"},"threshold":{"type":"integer"}},"required":["object","balance","threshold"]}},"required":["id","type","timestamp","sandbox","data"]},"BatchCompletedEvent":{"type":"object","properties":{"id":{"type":"string","description":"Event id; also the webhook-id header. Dedupe on it."},"type":{"type":"string","enum":["batch.completed"]},"timestamp":{"type":"string"},"sandbox":{"type":"boolean","description":"true for work done with a test (aiv_test_) key."},"data":{"type":"object","properties":{"object":{"type":"string","enum":["batch"]},"id":{"type":"string"},"status":{"type":"string","enum":["completed"]},"stop_reason":{"type":["string","null"]},"customer":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"answers":{"type":"object","properties":{"total":{"type":"integer"},"started":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"not_started":{"type":"integer"}},"required":["total","started","succeeded","failed","not_started"]},"credits":{"type":"object","properties":{"charged":{"type":"integer"},"refunded":{"type":"integer"}},"required":["charged","refunded"]},"checks":{"type":"integer"},"created_at":{"type":"string"},"completed_at":{"type":"string"}},"required":["object","id","status","stop_reason","customer","metadata","answers","credits","checks","created_at","completed_at"]}},"required":["id","type","timestamp","sandbox","data"]},"BatchStoppedEvent":{"type":"object","properties":{"id":{"type":"string","description":"Event id; also the webhook-id header. Dedupe on it."},"type":{"type":"string","enum":["batch.stopped"]},"timestamp":{"type":"string"},"sandbox":{"type":"boolean","description":"true for work done with a test (aiv_test_) key."},"data":{"type":"object","properties":{"object":{"type":"string","enum":["batch"]},"id":{"type":"string"},"status":{"type":"string","enum":["stopped"]},"stop_reason":{"type":["string","null"]},"customer":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"answers":{"type":"object","properties":{"total":{"type":"integer"},"started":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"not_started":{"type":"integer"}},"required":["total","started","succeeded","failed","not_started"]},"credits":{"type":"object","properties":{"charged":{"type":"integer"},"refunded":{"type":"integer"}},"required":["charged","refunded"]},"checks":{"type":"integer"},"created_at":{"type":"string"},"completed_at":{"type":"string"}},"required":["object","id","status","stop_reason","customer","metadata","answers","credits","checks","created_at","completed_at"]}},"required":["id","type","timestamp","sandbox","data"]},"PingEvent":{"type":"object","properties":{"id":{"type":"string","description":"Event id; also the webhook-id header. Dedupe on it."},"type":{"type":"string","enum":["ping"]},"timestamp":{"type":"string"},"sandbox":{"type":"boolean","description":"true for work done with a test (aiv_test_) key."},"data":{"type":"object","properties":{"object":{"type":"string","enum":["ping"]},"endpoint_id":{"type":"string"},"message":{"type":"string"}},"required":["object","endpoint_id","message"]}},"required":["id","type","timestamp","sandbox","data"]},"Health":{"type":"object","properties":{"ok":{"type":"boolean"},"service":{"type":"string","enum":["api"]},"env":{"type":"string"},"price_version":{"type":"integer"}},"required":["ok","service","env","price_version"]},"ComponentHealth":{"type":"object","properties":{"ok":{"type":"boolean"},"components":{"type":"object","properties":{"database":{"type":"boolean"},"engine":{"type":"boolean"}},"required":["database","engine"]}},"required":["ok","components"]},"DeepHealth":{"type":"object","properties":{"ok":{"type":"boolean"},"env":{"type":"string"},"checks":{"type":"object","additionalProperties":{"type":"object","properties":{"ok":{"type":"boolean"},"ms":{"type":"number"},"detail":{"type":"string"}},"required":["ok","ms"]}}},"required":["ok","env","checks"]},"Pricing":{"type":"object","properties":{"price_version":{"type":"integer"},"credits_per_usd":{"type":"integer"},"credits":{"type":"object","additionalProperties":{"type":"integer"}},"engines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"surface":{"type":"string","enum":["app","serp","api"]},"credits":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["id","label","surface","credits"]}},"plans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"monthly_usd":{"type":["number","null"]},"credits":{"type":["integer","null"]},"req_per_min":{"type":"integer"},"concurrent_tasks":{"type":"integer"},"projects":{"type":"integer"},"history_days":{"type":"integer"},"reports":{"type":"string"}},"required":["id","label","monthly_usd","credits","req_per_min","concurrent_tasks","projects","history_days","reports"]}},"terms":{"type":"object","properties":{"free_credit_expiry_days":{"type":"integer"},"payg_min_topup_usd":{"type":"number"},"payg_credit_expiry_days":{"type":"integer"},"yearly_discount":{"type":"number"}},"required":["free_credit_expiry_days","payg_min_topup_usd","payg_credit_expiry_days","yearly_discount"]}},"required":["price_version","credits_per_usd","credits","engines","plans","terms"]},"Locales":{"type":"object","properties":{"format":{"type":"string"},"default":{"type":"string"},"updated":{"type":"string","description":"When the lists were last refreshed."},"countries":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"engines":{"type":"array","items":{"type":"string","enum":["chatgpt","gemini","ai_overviews","ai_mode","deepseek","perplexity","claude","grok"]}}},"required":["code","name","engines"]}},"languages":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"engines":{"type":"array","items":{"type":"string","enum":["chatgpt","gemini","ai_overviews","ai_mode","deepseek","perplexity","claude","grok"]}}},"required":["code","name","engines"]}}},"required":["format","default","updated","countries","languages"]},"LocaleSupport":{"type":"object","properties":{"locale":{"type":"string","description":"The canonical form: send this one."},"language":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"]},"country":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"]},"engines":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string","enum":["chatgpt","gemini","ai_overviews","ai_mode","deepseek","perplexity","claude","grok"]},"supported":{"type":"boolean"},"language_code":{"type":["string","null"],"description":"The language code this engine is sent (null when unsupported)."},"reason":{"type":["string","null"]}},"required":["engine","supported","language_code","reason"]}}},"required":["locale","language","country","engines"]},"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"},"request_id":{"type":"string"}},"required":["type","title","status","code"],"additionalProperties":{}},"Account":{"type":"object","properties":{"account":{"type":"object","properties":{"id":{"type":"string"},"plan":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"balance":{"type":"integer"},"reserved":{"type":"integer","description":"Held for checks still running."},"balance_alert_below":{"type":["integer","null"],"description":"balance.low webhook threshold (credits), or null when off."},"limits":{"type":"object","properties":{"requests_per_minute":{"type":"integer"},"concurrent_answers":{"type":"integer"},"projects":{"type":"integer"},"history_days":{"type":"integer"}},"required":["requests_per_minute","concurrent_answers","projects","history_days"]}},"required":["id","plan","mode","balance","reserved","balance_alert_below","limits"]},"key":{"allOf":[{"$ref":"#/components/schemas/Key"},{"type":"object","properties":{"used_today":{"type":"integer"},"budget_remaining_today":{"type":["integer","null"]}},"required":["used_today","budget_remaining_today"]}]}},"required":["account","key"]},"Key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mode":{"type":"string","enum":["live","test"]},"kind":{"type":"string","enum":["rest","mcp"]},"scope":{"type":"string","enum":["full","read"]},"display":{"type":"string"},"daily_budget":{"type":["integer","null"]},"daily_budget_follows_plan":{"type":"boolean"},"confirm_above":{"type":["integer","null"]},"customer":{"type":["string","null"],"description":"The customer this key is locked to (null = whole account)."},"allowed_ips":{"type":["array","null"],"items":{"type":"string"},"description":"IP addresses/ranges the key works from (null = anywhere)."},"status":{"type":"string","enum":["active","revoked","expired"]},"created_at":{"type":"string"},"last_used_at":{"type":["string","null"]},"expires_at":{"type":["string","null"]},"revoked_at":{"type":["string","null"]}},"required":["id","name","mode","kind","scope","display","daily_budget","daily_budget_follows_plan","confirm_above","customer","allowed_ips","status","created_at","last_used_at","expires_at","revoked_at"]},"Estimate":{"type":"object","properties":{"credits":{"type":"integer"},"answers":{"type":"integer"},"reused_answers":{"type":"integer","description":"With max_age_hours: answers served from an identical recent answer, at half price."},"by_engine":{"type":"object","additionalProperties":{"type":"object","properties":{"answers":{"type":"integer"},"credits":{"type":"integer"}},"required":["answers","credits"]}},"balance":{"type":"integer"},"budget_remaining_today":{"type":["integer","null"]},"confirmation_required":{"type":"boolean"},"affordable":{"type":"boolean"}},"required":["credits","answers","reused_answers","by_engine","balance","budget_remaining_today","confirmation_required","affordable"]},"EstimateRequest":{"type":"object","properties":{"questions":{"type":"array","items":{"type":"string","example":"best invoicing app for freelancers"},"minItems":1,"maxItems":25,"description":"Buyer questions to ask. Or use project_id to ask a project's questions."},"project_id":{"type":"string","pattern":"^prj_[0-9A-HJKMNP-TV-Z]{26}$"},"question_ids":{"type":"array","items":{"type":"string","pattern":"^q_[0-9A-HJKMNP-TV-Z]{26}$"},"minItems":1,"maxItems":100,"description":"With project_id: only these questions."},"engines":{"type":"array","items":{"type":"string","enum":["chatgpt","gemini","ai_overviews","ai_mode","deepseek","perplexity","claude","grok"],"example":"chatgpt"},"minItems":1,"maxItems":8,"description":"Default: chatgpt, gemini, ai_overviews, ai_mode (or the project's engines)."},"mode":{"type":"string","enum":["batch","standard","live"],"description":"Default: live."},"samples":{"type":"integer","minimum":1,"maximum":5,"description":"Answers per question and engine (AI answers vary; more samples = tighter ranges). Default 1."},"locale":{"type":"string","example":"en-US","description":"Where and in which language to ask, as language-COUNTRY: en-US, pt-BR, ja-JP, es-MX, de-CH. Any language with any country, if every engine supports both (GET /v1/locales). Default en-US."},"customer":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Your id for your own customer. Tags the job for usage reports, filters and (soon) webhooks; a different customer is never deduplicated with another's request."},"max_age_hours":{"type":"integer","minimum":1,"maximum":168,"description":"Accept an identical answer (same question, engine and locale) that was collected within this many hours (1–168), at half the price and in seconds. Answers without a recent match are collected fresh. Default: always fresh."}},"additionalProperties":false},"JobResponse":{"allOf":[{"$ref":"#/components/schemas/Job"},{"type":"object","properties":{"deduplicated":{"type":"boolean","description":"true when an identical request in the last 10 minutes was returned instead of charging again."}},"required":["deduplicated"]}]},"JobCredits":{"type":"object","properties":{"quoted":{"type":"integer"},"charged":{"type":["integer","null"]},"refunded":{"type":["integer","null"]}},"required":["quoted","charged","refunded"]},"Answer":{"type":"object","properties":{"id":{"type":"string"},"engine":{"type":"string"},"engine_label":{"type":"string"},"surface":{"type":"string","description":"app = the real consumer app, serp = Google's AI, api = model API with web search."},"mode":{"type":"string"},"question":{"type":"string"},"locale":{"type":"string"},"collected_at":{"type":"string"},"has_ai_answer":{"type":"boolean","description":"false when the engine showed no AI answer (e.g. no AI Overview)."},"text":{"type":"string","description":"The answer's text; omitted with text=false."},"model":{"type":["string","null"]},"reading":{"type":"string","enum":["done","partial","pending"],"description":"Whether brands, facts and source types have been extracted yet (usually within a minute)."},"citations":{"type":"array","items":{"$ref":"#/components/schemas/Citation"}},"brands":{"type":"array","items":{"$ref":"#/components/schemas/BrandMention"}},"facts":{"type":"array","items":{"$ref":"#/components/schemas/Fact"}},"sandbox":{"type":"boolean","description":"true for test-key sample data."},"reused":{"type":"boolean","description":"true when this answer was served from an identical recent answer (max_age_hours); collected_at is when the engine gave it."},"receipt":{"type":["object","null"],"properties":{"sha256":{"type":"string"},"url":{"type":"string"}},"required":["sha256","url"],"description":"The engine's raw response as stored, and its SHA-256."}},"required":["id","engine","engine_label","surface","mode","question","locale","collected_at","has_ai_answer","model","reading","citations","brands","facts","sandbox","reused","receipt"]},"Citation":{"type":"object","properties":{"position":{"type":"integer"},"url":{"type":"string"},"domain":{"type":"string"},"source_type":{"type":["string","null"],"description":"brand_owned, review_site, media, reddit, youtube, wikipedia, forum, social, blog_platform, marketplace, gov_edu, other; null until read"},"title":{"type":["string","null"]}},"required":["position","url","domain","source_type","title"]},"BrandMention":{"type":"object","properties":{"name":{"type":"string"},"rank":{"type":["integer","null"],"description":"Order of first mention (1 = first)."},"recommended":{"type":"boolean"},"sentiment":{"type":["string","null"],"enum":["positive","neutral","negative",null]},"quote":{"type":["string","null"],"description":"Exact words from the answer."}},"required":["name","rank","recommended","sentiment","quote"]},"Fact":{"type":"object","properties":{"brand":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"quote":{"type":"string"},"price":{"type":["object","null"],"properties":{"amount":{"type":"number"},"currency":{"type":["string","null"]},"period":{"type":["string","null"]},"per_user":{"type":"boolean"}},"required":["amount","currency","period","per_user"]}},"required":["brand","type","value","quote","price"]},"Job":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["running","succeeded","partial","failed"]},"created_at":{"type":"string"},"finished_at":{"type":["string","null"]},"project_id":{"type":["string","null"]},"customer":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"sandbox":{"type":"boolean"},"price_version":{"type":"integer"},"credits":{"$ref":"#/components/schemas/JobCredits"},"progress":{"type":"object","properties":{"total":{"type":"integer"},"done":{"type":"integer"},"failed":{"type":"integer"},"running":{"type":"integer"}},"required":["total","done","failed","running"]},"poll_after_seconds":{"type":["integer","null"],"description":"When to check again; null when finished."},"answers":{"type":"array","items":{"$ref":"#/components/schemas/Answer"}},"failures":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"question":{"type":"string"},"sample":{"type":"integer"},"code":{"type":"string"},"message":{"type":"string"}},"required":["engine","question","sample","code","message"]}}},"required":["id","status","created_at","finished_at","project_id","customer","metadata","sandbox","price_version","credits","progress","poll_after_seconds","answers","failures"]},"CheckRequest":{"type":"object","properties":{"questions":{"type":"array","items":{"type":"string","example":"best invoicing app for freelancers"},"minItems":1,"maxItems":25,"description":"Buyer questions to ask. Or use project_id to ask a project's questions."},"project_id":{"type":"string","pattern":"^prj_[0-9A-HJKMNP-TV-Z]{26}$"},"question_ids":{"type":"array","items":{"type":"string","pattern":"^q_[0-9A-HJKMNP-TV-Z]{26}$"},"minItems":1,"maxItems":100,"description":"With project_id: only these questions."},"engines":{"type":"array","items":{"type":"string","enum":["chatgpt","gemini","ai_overviews","ai_mode","deepseek","perplexity","claude","grok"],"example":"chatgpt"},"minItems":1,"maxItems":8,"description":"Default: chatgpt, gemini, ai_overviews, ai_mode (or the project's engines)."},"mode":{"type":"string","enum":["batch","standard","live"],"description":"Default: live."},"samples":{"type":"integer","minimum":1,"maximum":5,"description":"Answers per question and engine (AI answers vary; more samples = tighter ranges). Default 1."},"locale":{"type":"string","example":"en-US","description":"Where and in which language to ask, as language-COUNTRY: en-US, pt-BR, ja-JP, es-MX, de-CH. Any language with any country, if every engine supports both (GET /v1/locales). Default en-US."},"customer":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Your id for your own customer. Tags the job for usage reports, filters and (soon) webhooks; a different customer is never deduplicated with another's request."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"example":{"workspace":"acme","report":"weekly"},"description":"Up to 20 string values of your own, stored and returned as sent. Not used for anything else."},"max_age_hours":{"type":"integer","minimum":1,"maximum":168,"description":"Accept an identical answer (same question, engine and locale) that was collected within this many hours (1–168), at half the price and in seconds. Answers without a recent match are collected fresh. Default: always fresh."},"max_credits":{"type":"integer","minimum":0,"description":"Refuse (402 budget_exceeded, nothing charged) if the check would cost more."},"confirm":{"type":"boolean","description":"Required when the cost is above your key's confirm_above threshold."},"wait":{"type":"integer","minimum":0,"maximum":90,"description":"Seconds to wait for results before answering (0–90). Default 0: return at once."}},"additionalProperties":false},"JobList":{"type":"object","properties":{"jobs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["running","succeeded","partial","failed"]},"created_at":{"type":"string"},"finished_at":{"type":["string","null"]},"project_id":{"type":["string","null"]},"customer":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"sandbox":{"type":"boolean"},"credits":{"$ref":"#/components/schemas/JobCredits"}},"required":["id","status","created_at","finished_at","project_id","customer","metadata","sandbox","credits"]}},"next":{"type":["string","null"]}},"required":["jobs","next"]},"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"brand":{"type":"object","properties":{"name":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}}},"required":["name","aliases","domains"]},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}}},"required":["name","aliases","domains"]}},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"question":{"type":"string"}},"required":["id","question"]}},"engines":{"type":"array","items":{"type":"string"}},"locale":{"type":"string"},"customer":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"schedule":{"type":"object","properties":{"cadence":{"type":"string","enum":["off","daily","weekly"]},"mode":{"type":"string"},"samples":{"type":"integer"},"next_run_at":{"type":["string","null"]},"credits_per_run":{"type":"integer"},"credits_per_month":{"type":"integer"}},"required":["cadence","mode","samples","next_run_at","credits_per_run","credits_per_month"]},"last_run":{"type":"object","properties":{"at":{"type":["string","null"]},"job_id":{"type":["string","null"]},"error":{"type":["string","null"]}},"required":["at","job_id","error"]},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","brand","competitors","questions","engines","locale","customer","metadata","schedule","last_run","created_at","updated_at"]},"ProjectRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"brand":{"$ref":"#/components/schemas/Brand"},"competitors":{"type":"array","items":{"$ref":"#/components/schemas/Brand"},"maxItems":20},"questions":{"type":"array","items":{"type":"string","example":"best invoicing app for freelancers"},"minItems":1,"maxItems":100},"engines":{"type":"array","items":{"type":"string","enum":["chatgpt","gemini","ai_overviews","ai_mode","deepseek","perplexity","claude","grok"],"example":"chatgpt"},"minItems":1,"maxItems":8},"locale":{"type":"string","example":"en-US","description":"Where and in which language to ask, as language-COUNTRY: en-US, pt-BR, ja-JP, es-MX, de-CH. Any language with any country, if every engine supports both (GET /v1/locales). Default en-US."},"customer":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Your id for your own customer. Set once: the project's checks, schedules, actions and analytics are all reported under it."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"example":{"workspace":"acme","report":"weekly"},"description":"Up to 20 string values of your own, stored and returned as sent. Not used for anything else."},"schedule":{"$ref":"#/components/schemas/Schedule"},"confirm":{"type":"boolean","description":"Needed when a schedule costs more per run than your key's confirm_above."}},"required":["name","brand","questions"],"additionalProperties":false},"Brand":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"aliases":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"maxItems":20},"domains":{"type":"array","items":{"type":"string"},"maxItems":10}},"required":["name"],"additionalProperties":false},"Schedule":{"type":"object","properties":{"cadence":{"type":"string","enum":["off","daily","weekly"]},"mode":{"type":"string","enum":["batch","standard","live"],"description":"live = answer now (all engines); standard = within ~5 min; batch = within ~45 min, cheapest. standard and batch: ChatGPT, Gemini, AI Overviews, AI Mode only."},"samples":{"type":"integer","minimum":1,"maximum":5}},"additionalProperties":false},"ProjectPatch":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"brand":{"$ref":"#/components/schemas/Brand"},"competitors":{"type":"array","items":{"$ref":"#/components/schemas/Brand"},"maxItems":20},"questions":{"type":"array","items":{"type":"string","example":"best invoicing app for freelancers"},"minItems":1,"maxItems":100},"engines":{"type":"array","items":{"type":"string","enum":["chatgpt","gemini","ai_overviews","ai_mode","deepseek","perplexity","claude","grok"],"example":"chatgpt"},"minItems":1,"maxItems":8},"locale":{"type":"string","example":"en-US","description":"Where and in which language to ask, as language-COUNTRY: en-US, pt-BR, ja-JP, es-MX, de-CH. Any language with any country, if every engine supports both (GET /v1/locales). Default en-US."},"customer":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Your id for your own customer. Set once: the project's checks, schedules, actions and analytics are all reported under it."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"example":{"workspace":"acme","report":"weekly"},"description":"Up to 20 string values of your own, stored and returned as sent. Not used for anything else."},"schedule":{"$ref":"#/components/schemas/Schedule"},"confirm":{"type":"boolean","description":"Needed when a schedule costs more per run than your key's confirm_above."}},"additionalProperties":false},"Visibility":{"type":"object","properties":{"brand":{"type":"string"},"overall":{"type":"object","properties":{"answers":{"type":"integer"},"with_ai_answer":{"type":"integer"},"mentioned":{"$ref":"#/components/schemas/Rate"},"mentioned_when_answered":{"$ref":"#/components/schemas/Rate"},"recommended":{"$ref":"#/components/schemas/Rate"},"cited":{"$ref":"#/components/schemas/Rate"},"avg_rank":{"type":["number","null"]},"sentiment":{"type":"object","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}},"required":["positive","neutral","negative"]}},"required":["answers","with_ai_answer","mentioned","mentioned_when_answered","recommended","cited","avg_rank","sentiment"]},"engines":{"type":"object","additionalProperties":{"type":"object","properties":{"answers":{"type":"integer"},"with_ai_answer":{"type":"integer"},"mentioned":{"$ref":"#/components/schemas/Rate"},"mentioned_when_answered":{"$ref":"#/components/schemas/Rate"},"recommended":{"$ref":"#/components/schemas/Rate"},"cited":{"$ref":"#/components/schemas/Rate"},"avg_rank":{"type":["number","null"]},"sentiment":{"type":"object","properties":{"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"}},"required":["positive","neutral","negative"]}},"required":["answers","with_ai_answer","mentioned","mentioned_when_answered","recommended","cited","avg_rank","sentiment"]}},"unread":{"type":"integer"},"meta":{"type":"object","properties":{"cached":{"type":"boolean","description":"true = same call within 10 minutes; not charged again."},"credits_charged":{"type":"integer"},"window":{"type":"object","properties":{"from":{"type":"string"},"days":{"type":"integer"}},"required":["from","days"]}},"required":["cached","credits_charged","window"]}},"required":["brand","overall","engines","unread","meta"]},"Rate":{"type":"object","properties":{"k":{"type":"integer"},"n":{"type":"integer"},"rate":{"type":["number","null"]},"low":{"type":["number","null"]},"high":{"type":["number","null"]},"display":{"type":"string","example":"62% (±9%)"}},"required":["k","n","rate","low","high","display"]},"Competitors":{"type":"object","properties":{"answers":{"type":"integer"},"brands":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"is_you":{"type":"boolean"},"tracked":{"type":"boolean"},"mentioned":{"$ref":"#/components/schemas/Rate"},"recommended":{"$ref":"#/components/schemas/Rate"},"avg_rank":{"type":["number","null"]},"share_of_voice":{"type":"number"}},"required":["name","is_you","tracked","mentioned","recommended","avg_rank","share_of_voice"]}},"unread":{"type":"integer"},"meta":{"type":"object","properties":{"cached":{"type":"boolean","description":"true = same call within 10 minutes; not charged again."},"credits_charged":{"type":"integer"},"window":{"type":"object","properties":{"from":{"type":"string"},"days":{"type":"integer"}},"required":["from","days"]}},"required":["cached","credits_charged","window"]}},"required":["answers","brands","unread","meta"]},"Sources":{"type":"object","properties":{"answers":{"type":"integer"},"domains":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string"},"type":{"type":"string"},"cited":{"$ref":"#/components/schemas/Rate"},"citations":{"type":"integer"},"is_yours":{"type":"boolean"},"top_urls":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"citations":{"type":"integer"}},"required":["url","citations"]}}},"required":["domain","type","cited","citations","is_yours","top_urls"]}},"by_type":{"type":"object","additionalProperties":{"type":"object","properties":{"answers":{"type":"integer"},"citations":{"type":"integer"}},"required":["answers","citations"]}},"meta":{"type":"object","properties":{"cached":{"type":"boolean","description":"true = same call within 10 minutes; not charged again."},"credits_charged":{"type":"integer"},"window":{"type":"object","properties":{"from":{"type":"string"},"days":{"type":"integer"}},"required":["from","days"]}},"required":["cached","credits_charged","window"]}},"required":["answers","domains","by_type","meta"]},"Facts":{"type":"object","properties":{"facts":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"answers":{"type":"integer"},"engines":{"type":"array","items":{"type":"string"}},"quote":{"type":"string"},"last_seen":{"type":"string"},"price":{"type":["object","null"],"properties":{"amount":{"type":"number"},"currency":{"type":["string","null"]},"period":{"type":["string","null"]},"per_user":{"type":"boolean"}},"required":["amount","currency","period","per_user"]}},"required":["type","value","answers","engines","quote","last_seen","price"]}},"meta":{"type":"object","properties":{"cached":{"type":"boolean","description":"true = same call within 10 minutes; not charged again."},"credits_charged":{"type":"integer"},"window":{"type":"object","properties":{"from":{"type":"string"},"days":{"type":"integer"}},"required":["from","days"]}},"required":["cached","credits_charged","window"]}},"required":["facts","meta"]},"History":{"type":"object","properties":{"points":{"type":"array","items":{"type":"object","properties":{"period":{"type":"string"},"mentioned":{"$ref":"#/components/schemas/Rate"}},"required":["period","mentioned"]}},"meta":{"type":"object","properties":{"cached":{"type":"boolean","description":"true = same call within 10 minutes; not charged again."},"credits_charged":{"type":"integer"},"window":{"type":"object","properties":{"from":{"type":"string"},"days":{"type":"integer"}},"required":["from","days"]}},"required":["cached","credits_charged","window"]}},"required":["points","meta"]},"ActionResult":{"type":"object","properties":{"job_id":{"type":"string"},"kind":{"type":"string"},"status":{"type":"string","enum":["running","succeeded","partial","failed"]},"sandbox":{"type":"boolean"},"deduplicated":{"type":"boolean"},"credits":{"type":"object","properties":{"quoted":{"type":"integer"},"charged":{"type":["integer","null"]},"refunded":{"type":["integer","null"]}},"required":["quoted","charged","refunded"]},"poll_after_seconds":{"type":["integer","null"]},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"result":{"type":["object","null"],"additionalProperties":{},"description":"The action's result once it succeeded (shape per endpoint)."}},"required":["job_id","kind","status","sandbox","deduplicated","credits","poll_after_seconds","error","result"]},"SiteCheckRequest":{"type":"object","properties":{"urls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":9,"description":"Extra pages of your site to check (on the brand's domains). Homepage, pricing and the pages closest to your questions are always checked."},"max_credits":{"type":"integer","minimum":0,"description":"Refuse (nothing charged) if it would cost more."},"confirm":{"type":"boolean","description":"Required when the cost is above your key's confirm_above."},"wait":{"type":"integer","minimum":0,"maximum":90,"description":"Seconds to wait for the result (default 60)."}},"additionalProperties":false},"ResearchRequest":{"type":"object","properties":{"question_id":{"type":"string","pattern":"^q_[0-9A-HJKMNP-TV-Z]{26}$"},"question":{"type":"string","example":"best invoicing app for freelancers"},"google":{"type":"boolean","description":"Include Google's top 30 for the question (30 credits, 2 if fetched in the last 24 h). Default true."},"max_credits":{"type":"integer","minimum":0,"description":"Refuse (nothing charged) if it would cost more."},"confirm":{"type":"boolean","description":"Required when the cost is above your key's confirm_above."},"wait":{"type":"integer","minimum":0,"maximum":90,"description":"Seconds to wait for the result (default 60)."}},"additionalProperties":false},"OpportunitiesRequest":{"type":"object","properties":{"days":{"type":"integer","minimum":1,"maximum":90,"description":"Answers from the last N days (default 30)."},"max_credits":{"type":"integer","minimum":0,"description":"Refuse (nothing charged) if it would cost more."},"confirm":{"type":"boolean","description":"Required when the cost is above your key's confirm_above."},"wait":{"type":"integer","minimum":0,"maximum":90,"description":"Seconds to wait for the result (default 60)."}},"additionalProperties":false},"Opportunity":{"type":"object","additionalProperties":{}},"Fix":{"type":"object","additionalProperties":{}},"FixRequest":{"type":"object","properties":{"summary":{"type":"string","minLength":3,"maxLength":500,"description":"What you changed, in a sentence."},"urls_changed":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":10},"commit_url":{"type":"string","maxLength":500,"format":"uri"},"verify":{"type":"boolean","description":"Re-fetch the pages and run the acceptance checks now (20 credits). Default true."},"max_credits":{"type":"integer","minimum":0,"description":"Refuse (nothing charged) if it would cost more."},"confirm":{"type":"boolean","description":"Required when the cost is above your key's confirm_above."},"wait":{"type":"integer","minimum":0,"maximum":90,"description":"Seconds to wait for the result (default 60)."}},"required":["summary"],"additionalProperties":false},"CreatedKey":{"allOf":[{"$ref":"#/components/schemas/Key"},{"type":"object","properties":{"secret":{"type":"string","description":"Shown once. Store it now; we only keep a hash."}},"required":["secret"]}]},"KeyRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"mode":{"type":"string","enum":["live","test"],"description":"test = free sandbox with sample data. Default live."},"kind":{"type":"string","enum":["rest","mcp"],"description":"mcp keys default to the plan's agent daily cap (10% of its monthly credits) and confirmation above 300 credits."},"scope":{"type":"string","enum":["full","read"],"description":"read keys can't start checks or change anything."},"daily_budget":{"anyOf":[{"type":"integer","minimum":1,"maximum":10000000},{"type":"string","enum":["plan"]},{"type":"null"}],"description":"Credits per UTC day. \"plan\" = the plan's agent cap (follows upgrades); null = no key limit."},"confirm_above":{"type":["integer","null"],"minimum":0,"maximum":10000000},"expires_in_days":{"type":"integer","minimum":1,"maximum":3650},"customer":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Lock the key to one of your customers: everything it creates is tagged with this customer, and it only sees that customer's jobs, projects and answers. Locked keys can't manage keys."},"allowed_ips":{"type":"array","items":{"type":"string"},"example":["203.0.113.0/24","2001:db8::/48"],"description":"Only accept this key from these IP addresses or ranges (up to 20, IPv4 or IPv6). null or [] = anywhere."}},"required":["name"],"additionalProperties":false},"KeyPatch":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"daily_budget":{"anyOf":[{"type":"integer","minimum":1,"maximum":10000000},{"type":"string","enum":["plan"]},{"type":"null"}],"description":"Credits per UTC day. \"plan\" = the plan's agent cap (follows upgrades); null = no key limit."},"confirm_above":{"type":["integer","null"],"minimum":0,"maximum":10000000},"allowed_ips":{"type":"array","items":{"type":"string"},"example":["203.0.113.0/24","2001:db8::/48"],"description":"Only accept this key from these IP addresses or ranges (up to 20, IPv4 or IPv6). null or [] = anywhere."}},"additionalProperties":false},"Usage":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"group_by":{"type":"array","items":{"type":"string","enum":["day","month","customer","project","key","kind","engine"]}},"customer":{"type":["string","null"]},"project_id":{"type":["string","null"]},"totals":{"type":"object","properties":{"credits":{"type":"integer","description":"Credits used: succeeded answers and actions, and analytics reads."},"pending":{"type":"integer","description":"Credits held for work still running (used or returned when done)."},"refunded":{"type":"integer","description":"Credits of failed work: never charged."},"answers":{"type":"integer"},"actions":{"type":"integer","description":"Site checks, research, scans, briefs, verifications."},"analytics":{"type":"integer","description":"Charged analytics reads."},"failed":{"type":"integer","description":"Answers and actions that failed (not charged)."}},"required":["credits","pending","refunded","answers","actions","analytics","failed"]},"rows":{"type":"array","items":{"$ref":"#/components/schemas/UsageRow"}}},"required":["from","to","group_by","customer","project_id","totals","rows"]},"UsageRow":{"type":"object","properties":{"day":{"type":"string"},"month":{"type":"string"},"customer":{"type":["string","null"]},"project_id":{"type":["string","null"]},"key_id":{"type":["string","null"]},"kind":{"type":"string","description":"answer, site_check, research, opportunities, fix_brief, verify or analytics."},"engine":{"type":["string","null"]},"credits":{"type":"integer","description":"Credits used: succeeded answers and actions, and analytics reads."},"pending":{"type":"integer","description":"Credits held for work still running (used or returned when done)."},"refunded":{"type":"integer","description":"Credits of failed work: never charged."},"answers":{"type":"integer"},"actions":{"type":"integer","description":"Site checks, research, scans, briefs, verifications."},"analytics":{"type":"integer","description":"Charged analytics reads."},"failed":{"type":"integer","description":"Answers and actions that failed (not charged)."}},"required":["credits","pending","refunded","answers","actions","analytics","failed"]},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"description":{"type":["string","null"]},"events":{"type":"array","items":{"type":"string"}},"customer":{"type":["string","null"]},"status":{"type":"string","enum":["enabled","disabled"]},"disabled_reason":{"type":["string","null"],"enum":["failing","manual",null],"description":"failing = paused by us after about 2.5 days of failed deliveries."},"disabled_at":{"type":["string","null"]},"failing_since":{"type":["string","null"]},"last_success_at":{"type":["string","null"]},"last_failure_at":{"type":["string","null"]},"previous_secret_expires_at":{"type":["string","null"],"description":"After a rotation, the old secret also signs until this time."},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","url","description","events","customer","status","disabled_reason","disabled_at","failing_since","last_success_at","last_failure_at","previous_secret_expires_at","created_at","updated_at"]},"CreatedWebhook":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string","description":"The signing secret (whsec_…). Shown once: store it now. Verify each request with any Standard Webhooks library."}},"required":["secret"]}]},"WebhookRequest":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"description":"Your public https:// URL. We POST signed JSON to it (Standard Webhooks) and don't follow redirects.","example":"https://example.com/webhooks/aivisibilityskill"},"events":{"type":"array","items":{"type":"string","enum":["*","check.completed","check.failed","action.completed","action.failed","schedule.skipped","balance.low","batch.completed","batch.stopped"]},"minItems":1,"maxItems":9,"description":"Which events to send: any of check.completed, check.failed, action.completed, action.failed, schedule.skipped, balance.low, batch.completed, batch.stopped, or \"*\" for all (also future ones). Default [\"*\"].","example":["check.completed","check.failed"]},"description":{"type":"string","maxLength":200},"customer":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Only this customer's events (keys locked to a customer always get their own). Default: every event on the account."}},"required":["url"],"additionalProperties":false},"WebhookPatch":{"type":"object","properties":{"url":{"type":"string","maxLength":2048,"description":"Your public https:// URL. We POST signed JSON to it (Standard Webhooks) and don't follow redirects.","example":"https://example.com/webhooks/aivisibilityskill"},"events":{"type":"array","items":{"type":"string","enum":["*","check.completed","check.failed","action.completed","action.failed","schedule.skipped","balance.low","batch.completed","batch.stopped"]},"minItems":1,"maxItems":9,"description":"Which events to send: any of check.completed, check.failed, action.completed, action.failed, schedule.skipped, balance.low, batch.completed, batch.stopped, or \"*\" for all (also future ones). Default [\"*\"].","example":["check.completed","check.failed"]},"description":{"type":["string","null"],"maxLength":200},"status":{"type":"string","enum":["enabled","disabled"],"description":"Turn the endpoint off or back on. Turning it on clears a pause; then resend what it missed with /recover."}},"additionalProperties":false},"WebhookDeliveryDetail":{"allOf":[{"$ref":"#/components/schemas/WebhookDelivery"},{"type":"object","properties":{"attempt_log":{"type":"array","items":{"type":"object","properties":{"attempt":{"type":"integer"},"at":{"type":"string"},"status":{"type":["integer","null"]},"error":{"type":["string","null"]},"latency_ms":{"type":["integer","null"]},"response":{"type":["string","null"],"description":"The first 500 characters your server replied."}},"required":["attempt","at","status","error","latency_ms","response"]}},"event":{"$ref":"#/components/schemas/Event"}},"required":["attempt_log","event"]}]},"Event":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"timestamp":{"type":"string"},"sandbox":{"type":"boolean"},"data":{"type":"object","additionalProperties":{}}},"required":["id","type","timestamp","sandbox","data"]},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_id":{"type":"string"},"event_type":{"type":"string"},"status":{"type":"string","enum":["pending","succeeded","failed","skipped"]},"attempts":{"type":"integer"},"max_attempts":{"type":"integer"},"next_attempt_at":{"type":["string","null"]},"last_attempt_at":{"type":["string","null"]},"last_status":{"type":["integer","null"],"description":"Your server's HTTP status."},"last_error":{"type":["string","null"],"description":"http_500, timeout, connection_failed: …, redirect to …, endpoint_disabled…"},"last_latency_ms":{"type":["integer","null"]},"succeeded_at":{"type":["string","null"]},"created_at":{"type":"string"}},"required":["id","event_id","event_type","status","attempts","max_attempts","next_attempt_at","last_attempt_at","last_status","last_error","last_latency_ms","succeeded_at","created_at"]},"AuditEntry":{"type":"object","properties":{"id":{"type":"integer"},"at":{"type":"string"},"actor":{"type":"string","description":"e.g. key \"CI\", agent \"Claude\", Console (you@example.com)"},"actor_key_id":{"type":["string","null"]},"ip":{"type":["string","null"]},"action":{"type":"string","example":"webhook.created"},"target_type":{"type":"string"},"target_id":{"type":["string","null"]},"customer":{"type":["string","null"]},"details":{"type":["object","null"],"additionalProperties":{}}},"required":["id","at","actor","actor_key_id","ip","action","target_type","target_id","customer","details"]},"Batch":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["running","stopping","completed","stopped"]},"stop_reason":{"type":["string","null"],"description":"Why a batch stopped early: insufficient_credits, budget_exceeded, max_credits, key_revoked, account_unavailable, customer_being_deleted, cancelled or internal_error."},"customer":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"answers":{"type":"object","properties":{"total":{"type":"integer"},"started":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"running":{"type":"integer"},"not_started":{"type":"integer"}},"required":["total","started","succeeded","failed","running","not_started"]},"credits":{"type":"object","properties":{"estimate":{"type":"integer"},"reserved":{"type":"integer"},"charged":{"type":"integer"},"refunded":{"type":"integer"}},"required":["estimate","reserved","charged","refunded"]},"checks":{"type":"array","items":{"type":"string"},"description":"The checks it runs as, in order; read their answers with GET /v1/jobs/{id}."},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]},"poll_after_seconds":{"type":["integer","null"]}},"required":["id","status","stop_reason","customer","metadata","answers","credits","checks","created_at","completed_at","poll_after_seconds"]},"BatchRequest":{"type":"object","properties":{"questions":{"type":"array","items":{"type":"string","example":"best invoicing app for freelancers"},"minItems":1,"maxItems":2000,"description":"Up to 2,000 questions."},"engines":{"type":"array","items":{"type":"string","enum":["chatgpt","gemini","ai_overviews","ai_mode","deepseek","perplexity","claude","grok"],"example":"chatgpt"},"minItems":1,"maxItems":8},"mode":{"type":"string","enum":["batch","standard","live"],"description":"Default: live. batch is cheapest."},"samples":{"type":"integer","minimum":1,"maximum":5},"locale":{"type":"string","example":"en-US","description":"Where and in which language to ask, as language-COUNTRY: en-US, pt-BR, ja-JP, es-MX, de-CH. Any language with any country, if every engine supports both (GET /v1/locales). Default en-US."},"customer":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Your id for your own customer. Tags the job for usage reports, filters and (soon) webhooks; a different customer is never deduplicated with another's request."},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"example":{"workspace":"acme","report":"weekly"},"description":"Up to 20 string values of your own, stored and returned as sent. Not used for anything else."},"max_age_hours":{"type":"integer","minimum":1,"maximum":168,"description":"Reuse identical answers collected within this many hours, at half price."},"max_credits":{"type":"integer","minimum":0,"description":"Refuse (402, nothing charged) if the estimate is above this, and never reserve more than this in total while it runs (it stops with stop_reason max_credits)."},"confirm":{"type":"boolean","description":"Required when the estimate is above your key's confirm_above threshold."}},"required":["questions"],"additionalProperties":false},"DataDeletion":{"type":"object","properties":{"id":{"type":"string"},"customer":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"counts":{"type":["object","null"],"additionalProperties":{"type":"integer"},"description":"What was deleted so far: answers, files, project_results, jobs, projects, events, webhooks, keys_revoked."},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]}},"required":["id","customer","status","counts","created_at","completed_at"]}},"parameters":{}},"paths":{"/health":{"get":{"tags":["ops"],"summary":"Liveness check","operationId":"getHealth","responses":{"200":{"description":"Alive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/health/components":{"get":{"tags":["ops"],"summary":"Up or down for each part of the service (public, no details)","description":"What the status page at aivisibilityskill.com/status checks every 5 minutes. Free and unauthenticated.","operationId":"getHealthComponents","responses":{"200":{"description":"All parts up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComponentHealth"}}}},"503":{"description":"A part is down","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComponentHealth"}}}}}}},"/health/deep":{"get":{"tags":["ops"],"summary":"Checks every binding (ops token required)","x-internal":true,"operationId":"getHealthDeep","responses":{"200":{"description":"All dependencies healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeepHealth"}}}},"503":{"description":"A dependency failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeepHealth"}}}}}}},"/v1/pricing":{"get":{"tags":["account"],"summary":"Credit price of every action (free)","operationId":"getPricing","responses":{"200":{"description":"Current price table","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pricing"}}}}}}},"/v1/locales":{"get":{"tags":["account"],"summary":"Countries and languages per engine (free, no key)","description":"A locale is language-COUNTRY (en-US, pt-BR, ja-JP, es-MX). Any language works with any country, as long as every engine in the check supports both; anything else is refused before it costs a credit.","operationId":"listLocales","responses":{"200":{"description":"Every country and language","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Locales"}}}}}}},"/v1/locales/{locale}":{"get":{"tags":["account"],"summary":"Which engines can answer in one locale (free, no key)","operationId":"getLocale","parameters":[{"schema":{"type":"string","maxLength":40,"example":"pt-BR"},"required":true,"name":"locale","in":"path"}],"responses":{"200":{"description":"Support per engine","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocaleSupport"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/account":{"patch":{"tags":["account"],"summary":"Account settings: the balance.low webhook threshold (free)","security":[{"bearer":[]}],"operationId":"updateAccount","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"balance_alert_below":{"type":["integer","null"],"minimum":1,"maximum":100000000,"description":"Send balance.low once when the balance drops below this many credits (again after it's back above). null turns it off."}},"required":["balance_alert_below"],"additionalProperties":false}}}},"responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"tags":["account"],"summary":"Balance, limits and the calling key (free)","security":[{"bearer":[]}],"operationId":"getAccount","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/estimate":{"post":{"tags":["checks"],"summary":"Price a check without running it (free)","security":[{"bearer":[]}],"operationId":"estimateCheck","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateRequest"}}}},"responses":{"200":{"description":"What it would cost and whether you can afford it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Estimate"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/checks":{"post":{"tags":["checks"],"summary":"Ask AI engines your questions (charged per answer)","description":"Reserves credits, queues one answer per question × engine × sample and returns the job. Failed answers are never charged. An identical request (same questions, engines, locale and customer) within 10 minutes returns the same job instead of charging again (deduplicated: true), whatever its Idempotency-Key; a job that failed doesn't count.","security":[{"bearer":[]}],"operationId":"createCheck","parameters":[{"schema":{"type":"string","description":"Retry-safe: the same key with the same body always returns the same job and never charges twice; reusing a key for a different body is a 409. A new key doesn't bypass the 10-minute duplicate window."},"required":false,"description":"Retry-safe: the same key with the same body always returns the same job and never charges twice; reusing a key for a different body is a 409. A new key doesn't bypass the 10-minute duplicate window.","name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckRequest"}}}},"responses":{"200":{"description":"Finished (with wait, a sandbox key, or a duplicate of a finished job)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"202":{"description":"Running; poll GET /v1/jobs/{id}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/jobs/{id}":{"get":{"tags":["checks"],"summary":"A check's status and answers (free)","security":[{"bearer":[]}],"operationId":"getJob","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"Include answer text (default true)."},"required":false,"description":"Include answer text (default true).","name":"text","in":"query"}],"responses":{"200":{"description":"Job","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/jobs":{"get":{"tags":["checks"],"summary":"Recent checks, newest first (free)","security":[{"bearer":[]}],"operationId":"listJobs","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: a job id from the previous page."},"required":false,"description":"Cursor: a job id from the previous page.","name":"before","in":"query"},{"schema":{"type":"string"},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Only this customer's checks."},"required":false,"description":"Only this customer's checks.","name":"customer","in":"query"}],"responses":{"200":{"description":"Jobs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobList"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/answers/{id}":{"get":{"tags":["answers"],"summary":"One answer with its brands, facts and sources (free)","security":[{"bearer":[]}],"operationId":"getAnswer","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/answers/{id}/receipt":{"get":{"tags":["answers"],"summary":"The engine's raw response, exactly as stored (free)","description":"JSON with an X-Receipt-Sha256 header; SHA-256 of the body equals the answer's receipt.sha256.","security":[{"bearer":[]}],"operationId":"getAnswerReceipt","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Raw response","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/projects":{"post":{"tags":["projects"],"summary":"Track a product: brand, competitors, questions, optional schedule (free)","security":[{"bearer":[]}],"operationId":"createProject","parameters":[{"schema":{"type":"string"},"required":false,"name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectRequest"}}}},"responses":{"200":{"description":"Already created with this Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"tags":["projects"],"summary":"Your projects (free)","security":[{"bearer":[]}],"operationId":"listProjects","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Only this customer's projects."},"required":false,"description":"Only this customer's projects.","name":"customer","in":"query"}],"responses":{"200":{"description":"Projects","content":{"application/json":{"schema":{"type":"object","properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}},"required":["projects"]}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/projects/{id}":{"get":{"tags":["projects"],"summary":"One project (free)","security":[{"bearer":[]}],"operationId":"getProject","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"tags":["projects"],"summary":"Change a project; `questions` replaces the list (free)","security":[{"bearer":[]}],"operationId":"updateProject","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectPatch"}}}},"responses":{"200":{"description":"Project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["projects"],"summary":"Archive a project and stop its schedule; collected answers stay (free)","security":[{"bearer":[]}],"operationId":"archiveProject","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Archived"},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/projects/{id}/visibility":{"get":{"tags":["analytics"],"summary":"How often engines mention / recommend / cite you, per engine, with confidence ranges (5 credits; repeats within 10 min free)","description":"Charged once per identical call per 10 minutes; repeats are served from cache for free. Read-only keys get only the free repeats.","security":[{"bearer":[]}],"operationId":"getProjectVisibility","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^q_[0-9A-HJKMNP-TV-Z]{26}$"},"required":false,"name":"question_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated engines, e.g. chatgpt,gemini. Default: all."},"required":false,"description":"Comma-separated engines, e.g. chatgpt,gemini. Default: all.","name":"engines","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":730,"description":"Look-back window. Default 30."},"required":false,"description":"Look-back window. Default 30.","name":"days","in":"query"}],"responses":{"200":{"description":"How often engines mention / recommend / cite you, per engine, with confidence ranges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Visibility"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/projects/{id}/competitors":{"get":{"tags":["analytics"],"summary":"Brands engines name for your questions, share of voice (10 credits; repeats within 10 min free)","description":"Charged once per identical call per 10 minutes; repeats are served from cache for free. Read-only keys get only the free repeats.","security":[{"bearer":[]}],"operationId":"getProjectCompetitors","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^q_[0-9A-HJKMNP-TV-Z]{26}$"},"required":false,"name":"question_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated engines, e.g. chatgpt,gemini. Default: all."},"required":false,"description":"Comma-separated engines, e.g. chatgpt,gemini. Default: all.","name":"engines","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":730,"description":"Look-back window. Default 30."},"required":false,"description":"Look-back window. Default 30.","name":"days","in":"query"}],"responses":{"200":{"description":"Brands engines name for your questions, share of voice","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Competitors"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/projects/{id}/sources":{"get":{"tags":["analytics"],"summary":"Sites engines cite for your questions (5 credits; repeats within 10 min free)","description":"Charged once per identical call per 10 minutes; repeats are served from cache for free. Read-only keys get only the free repeats.","security":[{"bearer":[]}],"operationId":"getProjectSources","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^q_[0-9A-HJKMNP-TV-Z]{26}$"},"required":false,"name":"question_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated engines, e.g. chatgpt,gemini. Default: all."},"required":false,"description":"Comma-separated engines, e.g. chatgpt,gemini. Default: all.","name":"engines","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":730,"description":"Look-back window. Default 30."},"required":false,"description":"Look-back window. Default 30.","name":"days","in":"query"}],"responses":{"200":{"description":"Sites engines cite for your questions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sources"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/projects/{id}/facts":{"get":{"tags":["analytics"],"summary":"What engines claim about your brand (prices, plans…), with quotes (5 credits; repeats within 10 min free)","description":"Charged once per identical call per 10 minutes; repeats are served from cache for free. Read-only keys get only the free repeats.","security":[{"bearer":[]}],"operationId":"getProjectFacts","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^q_[0-9A-HJKMNP-TV-Z]{26}$"},"required":false,"name":"question_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated engines, e.g. chatgpt,gemini. Default: all."},"required":false,"description":"Comma-separated engines, e.g. chatgpt,gemini. Default: all.","name":"engines","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":730,"description":"Look-back window. Default 30."},"required":false,"description":"Look-back window. Default 30.","name":"days","in":"query"}],"responses":{"200":{"description":"What engines claim about your brand (prices, plans…), with quotes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Facts"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/projects/{id}/history":{"get":{"tags":["analytics"],"summary":"Your mention rate per week (or day) (5 credits; repeats within 10 min free)","description":"Charged once per identical call per 10 minutes; repeats are served from cache for free. Read-only keys get only the free repeats.","security":[{"bearer":[]}],"operationId":"getProjectHistory","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^q_[0-9A-HJKMNP-TV-Z]{26}$"},"required":false,"name":"question_id","in":"query"},{"schema":{"type":"string","description":"Comma-separated engines, e.g. chatgpt,gemini. Default: all."},"required":false,"description":"Comma-separated engines, e.g. chatgpt,gemini. Default: all.","name":"engines","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":730,"description":"Look-back window. Default 30."},"required":false,"description":"Look-back window. Default 30.","name":"days","in":"query"},{"schema":{"type":"string","enum":["week","day"]},"required":false,"name":"bucket","in":"query"}],"responses":{"200":{"description":"Your mention rate per week (or day)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/History"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/projects/{id}/site-check":{"post":{"tags":["fixes"],"summary":"Check your site the way AI crawlers see it (20 credits)","description":"robots.txt per AI crawler, llms.txt, sitemap, then up to 10 pages read as raw HTML (no JavaScript, like GPTBot or PerplexityBot): titles, headings, structured data, whether the page is empty without JavaScript, noindex, and your real prices (read and checked against the page). Results include the site issues found. Failed checks are refunded.","security":[{"bearer":[]}],"operationId":"runSiteCheck","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteCheckRequest"}}}},"responses":{"200":{"description":"Finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResult"}}}},"202":{"description":"Running; poll GET /v1/actions/{job_id}","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResult"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/projects/{id}/research":{"post":{"tags":["fixes"],"summary":"What the pages engines cite for a question contain, and where they rank (40 + 30 credits)","description":"Reads up to 10 pages engines cited for one of your questions (respecting each site's robots.txt): which brands each lists and whether you're on it, page type, headings, last update. With google: true (default), also Google's top 30 and which of those the engines cite. Needs answers for the question first (run a check). Failed research is refunded.","security":[{"bearer":[]}],"operationId":"runResearch","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchRequest"}}}},"responses":{"200":{"description":"Finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResult"}}}},"202":{"description":"Running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResult"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/projects/{id}/opportunities":{"post":{"tags":["fixes"],"summary":"Find what's wrong, ranked, with evidence (30 credits; 5 if nothing changed)","description":"Runs every detector over the project's answers, latest site check and research: blocked crawlers, pages empty without JavaScript, wrong prices, questions where competitors are named and you aren't, cited pages that list competitors but not you, competitor pages engines cite where you have none, Google rankings. Each has impact, confidence, a plain summary with real numbers, and evidence. Free to read again with GET.","security":[{"bearer":[]}],"operationId":"findOpportunities","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpportunitiesRequest"}}}},"responses":{"200":{"description":"Finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResult"}}}},"202":{"description":"Running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResult"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"tags":["fixes"],"summary":"The project's opportunities, best first (free)","security":[{"bearer":[]}],"operationId":"listOpportunities","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["open","active","all"],"description":"open = not fixed yet; active (default) = everything not dismissed or resolved; all."},"required":false,"description":"open = not fixed yet; active (default) = everything not dismissed or resolved; all.","name":"status","in":"query"}],"responses":{"200":{"description":"Opportunities","content":{"application/json":{"schema":{"type":"object","properties":{"opportunities":{"type":"array","items":{"$ref":"#/components/schemas/Opportunity"}}},"required":["opportunities"]}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/opportunities/{id}":{"get":{"tags":["fixes"],"summary":"One opportunity with its evidence, latest brief and fixes (free)","security":[{"bearer":[]}],"operationId":"getOpportunity","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Opportunity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Opportunity"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"tags":["fixes"],"summary":"Dismiss an opportunity (or reopen it) (free)","security":[{"bearer":[]}],"operationId":"updateOpportunity","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["dismissed","open"]}},"required":["status"],"additionalProperties":false}}}},"responses":{"200":{"description":"Opportunity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Opportunity"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/opportunities/{id}/brief":{"post":{"tags":["fixes"],"summary":"An exact, site-specific plan to fix one opportunity (40 credits; 5 if nothing changed)","description":"Mechanical fixes (robots.txt, noindex, structured data, llms.txt, pricing page) are written by code, exactly, including file contents. Content and outreach fixes are drafted by a model from the evidence and then checked: prices must be on your site, URLs must come from the evidence or your domain, stated facts are copied from your pages, and acceptance checks are ones we can verify by fetching your site again. A plan that doesn't survive the checks is refunded.","security":[{"bearer":[]}],"operationId":"createFixBrief","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"Refuse (nothing charged) if it would cost more."},"confirm":{"type":"boolean","description":"Required when the cost is above your key's confirm_above."},"wait":{"type":"integer","minimum":0,"maximum":90,"description":"Seconds to wait for the result (default 60)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResult"}}}},"202":{"description":"Running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResult"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/opportunities/{id}/fixes":{"post":{"tags":["fixes"],"summary":"Mark an opportunity fixed (free), and verify it on the site (optional, credits)","description":"Records what you changed. With verify (default), re-fetches the pages and runs the brief's acceptance checks: verified, or not live yet with what's missing. Later, once enough answers come in, compares how often engines name you before and after (free, automatic).","security":[{"bearer":[]}],"operationId":"recordFix","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FixRequest"}}}},"responses":{"200":{"description":"Fix recorded (and verified)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fix"}}}},"202":{"description":"Fix recorded; verification running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fix"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/fixes/{id}/verify":{"post":{"tags":["fixes"],"summary":"Run a fix's acceptance checks on the live site again (20 credits)","description":"Identical verifications within 10 minutes return the same result.","security":[{"bearer":[]}],"operationId":"verifyFix","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"max_credits":{"type":"integer","minimum":0,"description":"Refuse (nothing charged) if it would cost more."},"confirm":{"type":"boolean","description":"Required when the cost is above your key's confirm_above."},"wait":{"type":"integer","minimum":0,"maximum":90,"description":"Seconds to wait for the result (default 60)."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Finished","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResult"}}}},"202":{"description":"Running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResult"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/fixes/{id}":{"get":{"tags":["fixes"],"summary":"A fix and its verification results (free)","security":[{"bearer":[]}],"operationId":"getFix","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Fix","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fix"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/actions/{id}":{"get":{"tags":["fixes"],"summary":"A site check, research, opportunity scan, brief or verification by job id (free)","security":[{"bearer":[]}],"operationId":"getAction","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionResult"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/keys":{"get":{"tags":["keys"],"summary":"Your API keys (live and test) — never the secrets","security":[{"bearer":[]}],"operationId":"listKeys","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Default 100."},"required":false,"description":"Default 100.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: a key id from the previous page."},"required":false,"description":"Cursor: a key id from the previous page.","name":"before","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Only keys locked to this customer."},"required":false,"description":"Only keys locked to this customer.","name":"customer","in":"query"}],"responses":{"200":{"description":"Keys, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/Key"}},"next":{"type":["string","null"]}},"required":["keys","next"]}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["keys"],"summary":"Create a key (e.g. a budgeted key for an agent)","security":[{"bearer":[]}],"operationId":"createKey","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRequest"}}}},"responses":{"201":{"description":"Created — the secret is in this response only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedKey"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/keys/{id}":{"patch":{"tags":["keys"],"summary":"Rename a key or change its budget / confirmation threshold","security":[{"bearer":[]}],"operationId":"updateKey","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyPatch"}}}},"responses":{"200":{"description":"Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Key"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["keys"],"summary":"Revoke a key immediately (it can't be restored)","security":[{"bearer":[]}],"operationId":"revokeKey","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Revoked"},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/usage":{"get":{"tags":["account"],"summary":"Credits used, by day, customer, project, key, kind or engine (free)","description":"For billing your own customers. Answers and actions count on the UTC day they were requested; analytics on the day they were charged. Up to 92 days and 10,000 rows per call. Add format=csv for a spreadsheet. Keys locked to a customer only see that customer.","security":[{"bearer":[]}],"operationId":"getUsage","parameters":[{"schema":{"type":"string","description":"First UTC day (default: 29 days before to)."},"required":false,"description":"First UTC day (default: 29 days before to).","name":"from","in":"query"},{"schema":{"type":"string","description":"Last UTC day, included (default: today)."},"required":false,"description":"Last UTC day, included (default: today).","name":"to","in":"query"},{"schema":{"type":"string","description":"Comma-separated: day, month, customer, project, key, kind, engine. Default: day. Empty string = one total.","example":"day,customer"},"required":false,"description":"Comma-separated: day, month, customer, project, key, kind, engine. Default: day. Empty string = one total.","name":"group_by","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Only this customer."},"required":false,"description":"Only this customer.","name":"customer","in":"query"},{"schema":{"type":"string"},"required":false,"name":"project_id","in":"query"},{"schema":{"type":"string","enum":["json","csv"]},"required":false,"name":"format","in":"query"}],"responses":{"200":{"description":"Usage (JSON, or text/csv with format=csv)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks":{"get":{"tags":["webhooks"],"summary":"Your webhook endpoints (free)","security":[{"bearer":[]}],"operationId":"listWebhooks","responses":{"200":{"description":"Endpoints","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}},"required":["webhooks"]}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["webhooks"],"summary":"Add an endpoint that receives signed events (free)","description":"We POST JSON to your URL when a check completes or fails, an action finishes, a scheduled run is skipped, or your balance runs low. Each request is signed (Standard Webhooks: webhook-id, webhook-timestamp, webhook-signature). Retried for about 2.7 days; an endpoint failing for 2.5 days is paused and you're emailed. At most 10 endpoints per account.","security":[{"bearer":[]}],"operationId":"createWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRequest"}}}},"responses":{"201":{"description":"Created; the secret is in this response only","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedWebhook"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks/{id}":{"get":{"tags":["webhooks"],"summary":"One endpoint (free)","security":[{"bearer":[]}],"operationId":"getWebhook","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"tags":["webhooks"],"summary":"Change an endpoint's URL, events or description, or turn it off or on (free)","security":[{"bearer":[]}],"operationId":"updateWebhook","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPatch"}}}},"responses":{"200":{"description":"Endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["webhooks"],"summary":"Delete an endpoint; nothing more is sent to it (free)","security":[{"bearer":[]}],"operationId":"deleteWebhook","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks/{id}/rotate-secret":{"post":{"tags":["webhooks"],"summary":"New signing secret; the old one keeps signing for up to 24 h (free)","security":[{"bearer":[]}],"operationId":"rotateWebhookSecret","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"expire_previous_in_hours":{"type":"number","minimum":0,"maximum":24,"description":"0 = the old secret stops now. Default 24."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Endpoint with its new secret (shown once)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedWebhook"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks/{id}/test":{"post":{"tags":["webhooks"],"summary":"Send a test event (ping) to an endpoint now (free)","description":"Works on a paused endpoint too, so you can check a fix before turning it back on. Tried once, never counts against the endpoint. Waits up to `wait` seconds for the result.","security":[{"bearer":[]}],"operationId":"testWebhook","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"wait":{"type":"integer","minimum":0,"maximum":25,"description":"Default 10."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Delivered or failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryDetail"}}}},"202":{"description":"Still being delivered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryDetail"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks/{id}/deliveries":{"get":{"tags":["webhooks"],"summary":"Delivery log, newest first (last 30 days; free)","security":[{"bearer":[]}],"operationId":"listWebhookDeliveries","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["pending","succeeded","failed","skipped"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: a delivery id from the previous page."},"required":false,"description":"Cursor: a delivery id from the previous page.","name":"before","in":"query"}],"responses":{"200":{"description":"Deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"next":{"type":["string","null"]}},"required":["deliveries","next"]}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks/{id}/deliveries/{delivery_id}":{"get":{"tags":["webhooks"],"summary":"One delivery: every attempt and the event body (free)","security":[{"bearer":[]}],"operationId":"getWebhookDelivery","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"delivery_id","in":"path"}],"responses":{"200":{"description":"Delivery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryDetail"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks/{id}/deliveries/{delivery_id}/resend":{"post":{"tags":["webhooks"],"summary":"Send a delivery again, with a fresh set of retries (free)","security":[{"bearer":[]}],"operationId":"resendWebhookDelivery","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string"},"required":true,"name":"delivery_id","in":"path"}],"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/webhooks/{id}/recover":{"post":{"tags":["webhooks"],"summary":"Resend everything an endpoint missed since a time (free)","description":"Failed and skipped deliveries are sent again, and events that happened while the endpoint was off are delivered now. Up to 30 days back, 1,000 per call.","security":[{"bearer":[]}],"operationId":"recoverWebhook","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string","format":"date-time","example":"2026-11-01T00:00:00Z"},"until":{"type":"string","format":"date-time"}},"required":["since"],"additionalProperties":false}}}},"responses":{"202":{"description":"Queued","content":{"application/json":{"schema":{"type":"object","properties":{"recovered":{"type":"integer"}},"required":["recovered"]}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/events":{"get":{"tags":["webhooks"],"summary":"Events, newest first: catch up on anything you missed (last 30 days; free)","security":[{"bearer":[]}],"operationId":"listEvents","parameters":[{"schema":{"type":"string","enum":["check.completed","check.failed","action.completed","action.failed","schedule.skipped","balance.low","batch.completed","batch.stopped","ping"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Your id for your own customer. Tags the job for usage reports, filters and (soon) webhooks; a different customer is never deduplicated with another's request."},"required":false,"description":"Your id for your own customer. Tags the job for usage reports, filters and (soon) webhooks; a different customer is never deduplicated with another's request.","name":"customer","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor: an event id from the previous page."},"required":false,"description":"Cursor: an event id from the previous page.","name":"before","in":"query"},{"schema":{"type":"string","description":"Only events newer than this event id (oldest first)."},"required":false,"description":"Only events newer than this event id (oldest first).","name":"after","in":"query"}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"next":{"type":["string","null"]}},"required":["events","next"]}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/events/{id}":{"get":{"tags":["webhooks"],"summary":"One event, exactly as sent (free)","security":[{"bearer":[]}],"operationId":"getEvent","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/audit-log":{"get":{"tags":["account"],"summary":"Who changed keys, webhooks, settings and projects, newest first (free; kept a year)","security":[{"bearer":[]}],"operationId":"listAuditLog","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Default 50."},"required":false,"description":"Default 50.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"description":"Cursor: an entry id from the previous page."},"required":false,"description":"Cursor: an entry id from the previous page.","name":"before","in":"query"},{"schema":{"type":"string","maxLength":60,"example":"key.revoked"},"required":false,"name":"action","in":"query"},{"schema":{"type":"string","maxLength":80},"required":false,"name":"target_id","in":"query"}],"responses":{"200":{"description":"Entries","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/AuditEntry"}},"next":{"type":["integer","null"]}},"required":["entries","next"]}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/batches":{"post":{"tags":["checks"],"summary":"Run thousands of answers in one request (charged per answer)","description":"Checks the estimate against your balance and key budget, then runs the answers as checks of up to 200 as your plan's concurrency allows. Each check reserves its credits when it starts and failed answers are never charged; if credits or the key's budget run out, the batch stops and nothing more is charged. Follow it with GET /v1/batches/{id} or the batch.completed / batch.stopped webhooks.","security":[{"bearer":[]}],"operationId":"createBatch","parameters":[{"schema":{"type":"string"},"required":false,"name":"idempotency-key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"}}}},"responses":{"200":{"description":"Already finished (test keys, or a replay of a finished batch)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"202":{"description":"Running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"get":{"tags":["checks"],"summary":"Your batches, newest first (free)","security":[{"bearer":[]}],"operationId":"listBatches","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"before","in":"query"},{"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Your id for your own customer. Tags the job for usage reports, filters and (soon) webhooks; a different customer is never deduplicated with another's request."},"required":false,"description":"Your id for your own customer. Tags the job for usage reports, filters and (soon) webhooks; a different customer is never deduplicated with another's request.","name":"customer","in":"query"}],"responses":{"200":{"description":"Batches","content":{"application/json":{"schema":{"type":"object","properties":{"batches":{"type":"array","items":{"$ref":"#/components/schemas/Batch"}},"next":{"type":["string","null"]}},"required":["batches","next"]}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/batches/{id}":{"get":{"tags":["checks"],"summary":"A batch's progress (free)","security":[{"bearer":[]}],"operationId":"getBatch","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/batches/{id}/cancel":{"post":{"tags":["checks"],"summary":"Stop starting new checks (running ones finish; nothing more is charged)","security":[{"bearer":[]}],"operationId":"cancelBatch","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Batch"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/customers/{customer}/delete-data":{"post":{"tags":["account"],"summary":"Delete everything stored for one of your customers (irreversible; free)","description":"Deletes the customer's answers, readings and receipts, projects and their results, events and webhook endpoints, and revokes keys locked to them. Credits and usage totals stay, labelled with a one-way tombstone. Runs in the background (usually minutes); waits for the customer's running checks to finish first. Send confirm: true.","security":[{"bearer":[]}],"operationId":"deleteCustomerData","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9_.:@/+=-]{0,127}$","example":"cus_8421","description":"Your id for your own customer. Tags the job for usage reports, filters and (soon) webhooks; a different customer is never deduplicated with another's request."},"required":true,"description":"Your id for your own customer. Tags the job for usage reports, filters and (soon) webhooks; a different customer is never deduplicated with another's request.","name":"customer","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"boolean","enum":[true]}},"required":["confirm"],"additionalProperties":false}}}},"responses":{"202":{"description":"Deletion started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataDeletion"}}}},"400":{"description":"Invalid request (the detail says what to fix)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"insufficient_credits or budget_exceeded — nothing was charged","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Idempotency-Key reused with a different request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Body larger than 64 KB","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Body isn't JSON","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"428":{"description":"Cost above the key's confirmation threshold — repeat with confirm: true","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Rate limited or too many answers running (see Retry-After)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/data-deletions/{id}":{"get":{"tags":["account"],"summary":"A data deletion's progress (free)","security":[{"bearer":[]}],"operationId":"getDataDeletion","parameters":[{"schema":{"type":"string"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Deletion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataDeletion"}}}},"401":{"description":"Missing, unknown, revoked or expired API key","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Read-only key, suspended account or plan limit","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found on this account","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"webhooks":{"check.completed":{"post":{"summary":"A check finished and its answers were read (brands, sources, facts are ready). After 10 minutes it's sent anyway with reading: partial. Fetch results with GET /v1/jobs/{id}.","tags":["webhooks"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook-id","in":"header"},{"schema":{"type":"string","description":"Unix seconds."},"required":true,"description":"Unix seconds.","name":"webhook-timestamp","in":"header"},{"schema":{"type":"string","description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation."},"required":true,"description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation.","name":"webhook-signature","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckCompletedEvent"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds means received. Anything else is retried."}}}},"check.failed":{"post":{"summary":"Every answer of a check failed. Nothing was charged.","tags":["webhooks"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook-id","in":"header"},{"schema":{"type":"string","description":"Unix seconds."},"required":true,"description":"Unix seconds.","name":"webhook-timestamp","in":"header"},{"schema":{"type":"string","description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation."},"required":true,"description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation.","name":"webhook-signature","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckFailedEvent"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds means received. Anything else is retried."}}}},"action.completed":{"post":{"summary":"A site check, research, opportunity scan, fix brief or verification finished. Fetch it with GET /v1/actions/{id}.","tags":["webhooks"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook-id","in":"header"},{"schema":{"type":"string","description":"Unix seconds."},"required":true,"description":"Unix seconds.","name":"webhook-timestamp","in":"header"},{"schema":{"type":"string","description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation."},"required":true,"description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation.","name":"webhook-signature","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionCompletedEvent"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds means received. Anything else is retried."}}}},"action.failed":{"post":{"summary":"A paid action failed. Nothing was charged.","tags":["webhooks"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook-id","in":"header"},{"schema":{"type":"string","description":"Unix seconds."},"required":true,"description":"Unix seconds.","name":"webhook-timestamp","in":"header"},{"schema":{"type":"string","description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation."},"required":true,"description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation.","name":"webhook-signature","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionFailedEvent"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds means received. Anything else is retried."}}}},"schedule.skipped":{"post":{"summary":"A scheduled project run didn't (fully) happen: no credits, over a key's budget, a revoked key.","tags":["webhooks"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook-id","in":"header"},{"schema":{"type":"string","description":"Unix seconds."},"required":true,"description":"Unix seconds.","name":"webhook-timestamp","in":"header"},{"schema":{"type":"string","description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation."},"required":true,"description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation.","name":"webhook-signature","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleSkippedEvent"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds means received. Anything else is retried."}}}},"balance.low":{"post":{"summary":"The balance dropped below your alert level (PATCH /v1/account balance_alert_below). Once per drop.","tags":["webhooks"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook-id","in":"header"},{"schema":{"type":"string","description":"Unix seconds."},"required":true,"description":"Unix seconds.","name":"webhook-timestamp","in":"header"},{"schema":{"type":"string","description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation."},"required":true,"description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation.","name":"webhook-signature","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceLowEvent"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds means received. Anything else is retried."}}}},"batch.completed":{"post":{"summary":"A bulk batch ran every answer. Read them with GET /v1/batches/{id} and its checks.","tags":["webhooks"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook-id","in":"header"},{"schema":{"type":"string","description":"Unix seconds."},"required":true,"description":"Unix seconds.","name":"webhook-timestamp","in":"header"},{"schema":{"type":"string","description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation."},"required":true,"description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation.","name":"webhook-signature","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCompletedEvent"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds means received. Anything else is retried."}}}},"batch.stopped":{"post":{"summary":"A bulk batch stopped early (insufficient_credits, budget_exceeded, max_credits, key_revoked, account_unavailable, customer_being_deleted, cancelled or internal_error). Answers that didn't start were never charged.","tags":["webhooks"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook-id","in":"header"},{"schema":{"type":"string","description":"Unix seconds."},"required":true,"description":"Unix seconds.","name":"webhook-timestamp","in":"header"},{"schema":{"type":"string","description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation."},"required":true,"description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation.","name":"webhook-signature","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchStoppedEvent"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds means received. Anything else is retried."}}}},"ping":{"post":{"summary":"A test event, sent by POST /v1/webhooks/{id}/test.","tags":["webhooks"],"parameters":[{"schema":{"type":"string"},"required":true,"name":"webhook-id","in":"header"},{"schema":{"type":"string","description":"Unix seconds."},"required":true,"description":"Unix seconds.","name":"webhook-timestamp","in":"header"},{"schema":{"type":"string","description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation."},"required":true,"description":"v1,<base64 HMAC-SHA256 of id.timestamp.body>; two during a secret rotation.","name":"webhook-signature","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PingEvent"}}}},"responses":{"200":{"description":"Any 2xx within 10 seconds means received. Anything else is retried."}}}}}}