{"openapi":"3.1.0","info":{"title":"AOO — Agent Operability Optimizer API","version":"2.0.0","description":"AOO sends a real LLM agent at a website and instruments every tool call — the URL it fetched, how it learned that URL, and what HTTP status came back. The score is derived from that trajectory, not from a static crawl.\n\nVersioning: major = a stable field removed, renamed or changed in meaning; minor = additive fields and goal-catalog membership changes; patch = spec corrections. Pinning the major is safe.\n\nStable within a major: domain, score, score_max, grade, category ids and budgets, goal ids, goal score/evaluated, run_id, audit_id, verdict, outcome, the four instrumented metrics, generated_at. Advisory (may change any release): all prose, finding ordering, and the synthesis object.\n\nAuthentication: none. Every endpoint is keyless and rate limited per IP."},"servers":[{"url":"https://daas-aoo.listeningmind.ai"}],"tags":[{"name":"scan","description":"Run audits and read scores"},{"name":"traces","description":"Single agent tasks and the trace each one leaves"},{"name":"catalog","description":"The goals and categories behind the score"}],"paths":{"/api/v1":{"get":{"tags":["catalog"],"summary":"Service descriptor","description":"Machine-readable index of every endpoint, category and default intent.","responses":{"200":{"description":"Descriptor"}}}},"/api/v1/goals":{"get":{"tags":["catalog"],"summary":"Goal and category catalog","description":"Every goal the score is built from, with its stable id, category and how it is measured. Goal ids are stable within a major version; catalog membership may change on a minor. Gate CI on explicit ids, not on category totals.","responses":{"200":{"description":"Catalog"}}}},"/api/v1/scan":{"post":{"tags":["scan"],"summary":"Run a full site audit","description":"Runs the intent battery against one domain and scores the site. Returns 202 with a poll URL: an audit drives a real agent for minutes, so there is no synchronous variant.\n\nA stored audit inside the freshness window is returned instead of running a new one (served_from_cache: true) and costs no quota. force: true is the only way past it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Domain or URL, e.g. example.com"},"intents":{"type":"array","items":{"type":"string","enum":["pricing","signup","api-docs","get-started","support","shipping","contact","fees","eligibility","booking","locations","stock","careers","policy","compare","latest","docs","civil","processing","products","nutrition","retailers"]},"description":"Which tasks to run. Defaults to the standard battery."},"provider":{"type":"string","enum":["gemini","openai"]},"model":{"type":"string"},"harness":{"type":"string","enum":["fetch-agent","playwright-agent"],"description":"fetch-agent reads raw HTML, which is what most AI assistants see. playwright-agent renders first; the gap between the two scores is the rendering gap. Rejected when the rendering harness is not installed — never silently downgraded, since that would mislabel the run."},"lang":{"type":"string","enum":["ko","en","ja"]},"max_age_seconds":{"type":"integer","description":"Freshness window, 600–86400. Default 21600."},"force":{"type":"boolean","description":"Bypass the freshness window."}}}}}},"responses":{"200":{"description":"Served from the freshness window; no scan was run."},"202":{"description":"Audit accepted. Poll the Location header."},"400":{"description":"INVALID_ARGUMENT"},"403":{"description":"BLOCKLISTED"},"429":{"description":"RATE_LIMIT_EXCEEDED — carries Retry-After."}}}},"/api/v1/scan/stream":{"get":{"tags":["scan"],"summary":"Run an audit and stream progress as SSE","description":"Starts an audit and streams phase, probe, run_update, score, goals, findings, synthesis and result events. Sends a ping every 15s so idle proxies do not drop the connection.","parameters":[{"name":"domain","in":"query","required":true,"schema":{"type":"string"}},{"name":"intents","in":"query","schema":{"type":"string"},"description":"Comma-separated intent ids."},{"name":"provider","in":"query","schema":{"type":"string","enum":["gemini","openai"]}},{"name":"lang","in":"query","schema":{"type":"string","enum":["ko","en","ja"]}}],"responses":{"200":{"description":"text/event-stream"}}}},"/api/v1/score/{domain}":{"get":{"tags":["scan"],"summary":"Latest stored score for a domain","description":"Read-only. Never triggers a scan — a read endpoint that silently spent agent minutes would be a trap. On a miss the 404 body carries next_action pointing at POST /api/v1/scan.","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","schema":{"type":"string","enum":["trend"]},"description":"Pass \"trend\" to add the score history for this domain."}],"responses":{"200":{"description":"Stored score"},"404":{"description":"DOMAIN_NOT_SCANNED, with next_action"}}}},"/api/v1/audits/{audit_id}":{"get":{"tags":["scan"],"summary":"Full audit report","description":"The complete report: categories, goals with their evidence, site probe, findings, synthesis, and per-task results each linking to its recorded trajectory. Returns 202 while the audit is still running.","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Completed audit"},"202":{"description":"Still running"},"404":{"description":"NOT_FOUND"}}}},"/api/v1/traces":{"get":{"tags":["traces"],"summary":"List recorded traces","parameters":[{"name":"domain","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Traces"}}},"post":{"tags":["traces"],"summary":"Run one agent task","description":"Sends an agent at the site on a single task. Either pass an intent_id from /api/v1/goals, or a free-text task. Free-text is used verbatim: the prompt is part of the instrument, so AOO never rewrites it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"intent_id":{"type":"string","enum":["pricing","signup","api-docs","get-started","support","shipping","contact","fees","eligibility","booking","locations","stock","careers","policy","compare","latest","docs","civil","processing","products","nutrition","retailers"]},"task":{"type":"string","description":"Free-text task, used verbatim."},"provider":{"type":"string","enum":["gemini","openai"]},"harness":{"type":"string","enum":["fetch-agent","playwright-agent"]},"lang":{"type":"string","enum":["ko","en","ja"]}}}}}},"responses":{"202":{"description":"Trace accepted"},"400":{"description":"INVALID_ARGUMENT"},"429":{"description":"RATE_LIMIT_EXCEEDED"}}}},"/api/v1/traces/{run_id}":{"get":{"tags":["traces"],"summary":"One recorded trajectory","description":"Every step the agent took, each carrying an attribution object saying how it learned that URL — link, sitemap, llms_txt, robots_txt, earlier_response, web_search, model_recall or other. This is the raw evidence the scores sit on.","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Completed trace"},"202":{"description":"Still running"},"404":{"description":"NOT_FOUND"}}}},"/api/v1/history":{"get":{"tags":["catalog"],"summary":"Domains analysed, or one domain’s score trend","parameters":[{"name":"domain","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"History"}}}},"/api/v1/badge/{domain}":{"get":{"tags":["scan"],"summary":"SVG score badge","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"image/svg+xml"}}}}},"x-goal-catalog":[{"id":"enter","category":"access","kind":"probe"},{"id":"welcome","category":"access","kind":"probe"},{"id":"guidance","category":"discovery","kind":"probe"},{"id":"readable","category":"navigation","kind":"probe"},{"id":"intent:pricing","category":"completion","kind":"trace"},{"id":"intent:signup","category":"completion","kind":"trace"},{"id":"intent:api-docs","category":"navigation","kind":"trace"},{"id":"intent:get-started","category":"navigation","kind":"trace"},{"id":"intent:support","category":"completion","kind":"trace"},{"id":"intent:shipping","category":"completion","kind":"trace"},{"id":"intent:contact","category":"completion","kind":"trace"},{"id":"intent:fees","category":"completion","kind":"trace"},{"id":"intent:eligibility","category":"completion","kind":"trace"},{"id":"intent:booking","category":"completion","kind":"trace"},{"id":"intent:locations","category":"completion","kind":"trace"},{"id":"intent:stock","category":"completion","kind":"trace"},{"id":"intent:careers","category":"completion","kind":"trace"},{"id":"intent:policy","category":"completion","kind":"trace"},{"id":"intent:compare","category":"completion","kind":"trace"},{"id":"intent:latest","category":"completion","kind":"trace"},{"id":"intent:docs","category":"completion","kind":"trace"},{"id":"intent:civil","category":"completion","kind":"trace"},{"id":"intent:processing","category":"completion","kind":"trace"},{"id":"intent:products","category":"completion","kind":"trace"},{"id":"intent:nutrition","category":"completion","kind":"trace"},{"id":"intent:retailers","category":"completion","kind":"trace"}],"x-categories":[{"id":"discovery","max":20},{"id":"access","max":30},{"id":"navigation","max":30},{"id":"completion","max":20}],"x-attribution-kinds":["link","sitemap","llms_txt","robots_txt","earlier_response","web_search","model_recall","other"]}