{"openapi":"3.1.0","info":{"title":"Agent Visibility Optimizer API","version":"1.0.0","summary":"Analyze how AI agents discover, understand and select a product; get evidence-labelled gaps and implementation-ready metadata.","description":"Machine-first service operated by Active Life Hub LLC. Submit a product URL (and optional context). The service fetches a bounded set of public surfaces (homepage, llms.txt, robots.txt, OpenAPI, A2A agent card, MCP metadata, pricing/docs pages, language alternates), classifies each capability as SUPPORTED / PARTIALLY_SUPPORTED / UNSUPPORTED / UNCLEAR with verbatim evidence, maps legitimate agent intents and multilingual local-market terms, flags unsupported or overbroad claims, runs explainable checks, and returns implementation-ready artifacts (llms.txt, descriptions, JSON-LD, OpenAPI patches, agent-profile export, A2A/MCP templates, x402 description). It does not guarantee ranking, recommendation or traffic in any third-party AI system.\n\nPayment: x402 v2 \"exact\" scheme, USDC on eip155:8453. Prices are fixed before payment: the variable cost of one analysis attempt for the tier (retrieval compute, model tokens for semantic, database, storage, transfer, settlement) × 3, rounded up to the cent, with a 0.05 USDC minimum. No usage surcharge, no subscription.\n\nPolicy: Pay per analysis. A completed report is charged even when it finds few surfaces (that is a finding). If paid analysis fails, resend the identical body with the same Idempotency-Key and Authorization: Bearer <Idempotency-Key> for up to two free retries. No automatic refunds; an uncertain settlement is reconciled manually. Reports are kept 30 days. See /terms.","contact":{"name":"Active Life Hub LLC","url":"https://agentvisibilityoptimizer.online/docs"},"termsOfService":"https://agentvisibilityoptimizer.online/terms","x-operator":"Active Life Hub LLC"},"servers":[{"url":"https://agentvisibilityoptimizer.online"}],"x-pricing":{"currency":"USDC","network":"eip155:8453","version":"avo-cost-plus-2026-09-28-v1","tiers":{"scan":{"amount":"0.05","description":"Deterministic analysis: up to 10 public surfaces fetched directly (homepage, llms.txt, robots.txt, OpenAPI, agent card, MCP metadata, pricing/docs pages, language alternates), curated multilingual capability lexicon, explainable checks, claim linting and generated artifacts. No model, search or browser calls."},"semantic":{"amount":"0.18","description":"Everything in scan, plus one bounded language-model pass over a token-capped excerpt of the same sources: capabilities outside the curated lexicon, jobs-to-be-done, intents, local-market terms for target languages, and rewritten descriptions. Every model claim must quote a retrieved source verbatim or it is downgraded."}}},"paths":{"/api/v1/optimize":{"post":{"operationId":"optimize","summary":"Buy a visibility optimization report (x402)","description":"Without PAYMENT-SIGNATURE returns 402 with x402 v2 requirements (no charge, no database access). Resend the identical body and Idempotency-Key with PAYMENT-SIGNATURE to pay and run. Prices: scan 0.05 USDC, semantic 0.18 USDC. Scan fetches at most 10 URLs with no model call; semantic adds one model call over at most 16000 source tokens. Typical scan latency: seconds.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,128}$"},"description":"Random secret; also the result access token."},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"Base64 x402 v2 payment payload."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"},"description":"Bearer <Idempotency-Key> to resume a paid request without paying again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Provide url, or name and description for a product without a public site. All text fields accept any language (UTF-8).","properties":{"url":{"type":"string","format":"uri","description":"Public http(s) product URL. Internationalized domains are accepted."},"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":4000,"description":"Submitter description. Treated as a claim, not as evidence."},"docs_url":{"type":"string","format":"uri"},"openapi_url":{"type":"string","format":"uri"},"llms_txt_url":{"type":"string","format":"uri"},"mcp_url":{"type":"string","format":"uri"},"agent_card_url":{"type":"string","format":"uri"},"pricing_url":{"type":"string","format":"uri"},"repository_url":{"type":"string","format":"uri"},"capabilities":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":300},"description":"Claimed capabilities; each is checked against public evidence."},"target_customers":{"type":"array","maxItems":10,"items":{"type":"string"}},"target_agent_types":{"type":"array","maxItems":10,"items":{"type":"string"}},"geography":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Declared service area. Never inferred from language."},"languages":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"Declared product languages (BCP 47)."},"target_markets":{"type":"array","maxItems":5,"items":{"type":"object","required":["language"],"properties":{"region":{"type":"string"},"language":{"type":"string","description":"BCP 47"}}},"description":"Markets whose native terminology should be considered (e.g. {\"region\":\"JP\",\"language\":\"ja\"})."},"pricing_model":{"type":"string","maxLength":500},"payment_methods":{"type":"array","maxItems":10,"items":{"type":"string"}},"constraints":{"type":"array","maxItems":20,"items":{"type":"string"}},"exclusions":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Things the product does not do; recorded as UNSUPPORTED."},"preferred_output_language":{"type":"string","description":"BCP 47 language of explanations. Evidence and original terms are never translated."},"tier":{"type":"string","enum":["scan","semantic"],"default":"scan"},"max_price_usdc":{"type":"number","description":"Refuse (HTTP 422, nothing charged) if the tier price is higher."}}},"example":{"url":"https://example.com","target_markets":[{"region":"JP","language":"ja"}],"preferred_output_language":"en","tier":"scan"}},"text/plain":{"schema":{"type":"string","description":"A single product URL."},"example":"https://example.com"}}},"responses":{"200":{"description":"Completed report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"202":{"description":"Paid and processing; poll /api/v1/requests/{id}."},"400":{"description":"Invalid request, URL or Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (x402 v2).","headers":{"PAYMENT-REQUIRED":{"description":"Base64 x402 v2 PaymentRequired","schema":{"type":"string"}}}},"409":{"description":"Idempotency-Key reused with a different body, or payment reused."},"413":{"description":"Body over 16 KiB."},"415":{"description":"Unsupported content type."},"422":{"description":"Price above max_price_usdc, or URL does not resolve (nothing charged)."},"429":{"description":"Rate limited."},"503":{"description":"Not configured, provider unavailable or settlement uncertain."}}}},"/api/v1/quote":{"post":{"operationId":"quote","summary":"Free price quote and x402 requirements for a request body","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Provide url, or name and description for a product without a public site. All text fields accept any language (UTF-8).","properties":{"url":{"type":"string","format":"uri","description":"Public http(s) product URL. Internationalized domains are accepted."},"name":{"type":"string","maxLength":200},"description":{"type":"string","maxLength":4000,"description":"Submitter description. Treated as a claim, not as evidence."},"docs_url":{"type":"string","format":"uri"},"openapi_url":{"type":"string","format":"uri"},"llms_txt_url":{"type":"string","format":"uri"},"mcp_url":{"type":"string","format":"uri"},"agent_card_url":{"type":"string","format":"uri"},"pricing_url":{"type":"string","format":"uri"},"repository_url":{"type":"string","format":"uri"},"capabilities":{"type":"array","maxItems":30,"items":{"type":"string","maxLength":300},"description":"Claimed capabilities; each is checked against public evidence."},"target_customers":{"type":"array","maxItems":10,"items":{"type":"string"}},"target_agent_types":{"type":"array","maxItems":10,"items":{"type":"string"}},"geography":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Declared service area. Never inferred from language."},"languages":{"type":"array","maxItems":30,"items":{"type":"string"},"description":"Declared product languages (BCP 47)."},"target_markets":{"type":"array","maxItems":5,"items":{"type":"object","required":["language"],"properties":{"region":{"type":"string"},"language":{"type":"string","description":"BCP 47"}}},"description":"Markets whose native terminology should be considered (e.g. {\"region\":\"JP\",\"language\":\"ja\"})."},"pricing_model":{"type":"string","maxLength":500},"payment_methods":{"type":"array","maxItems":10,"items":{"type":"string"}},"constraints":{"type":"array","maxItems":20,"items":{"type":"string"}},"exclusions":{"type":"array","maxItems":20,"items":{"type":"string"},"description":"Things the product does not do; recorded as UNSUPPORTED."},"preferred_output_language":{"type":"string","description":"BCP 47 language of explanations. Evidence and original terms are never translated."},"tier":{"type":"string","enum":["scan","semantic"],"default":"scan"},"max_price_usdc":{"type":"number","description":"Refuse (HTTP 422, nothing charged) if the tier price is higher."}}}}}},"responses":{"200":{"description":"Price and payment requirements."},"400":{"description":"Invalid request."},"422":{"description":"Unresolvable URL or price above ceiling."}}}},"/api/v1/requests/{id}":{"get":{"operationId":"getRequest","summary":"Retrieve a report (Authorization: Bearer <Idempotency-Key>)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Report."},"202":{"description":"Processing."},"401":{"description":"Missing token."},"404":{"description":"Not found."},"410":{"description":"Expired after 30 days."}}}},"/api/v1/health":{"get":{"operationId":"health","summary":"Configuration health (no database). ?ready=1 adds a cached database probe.","responses":{"200":{"description":"OK"},"503":{"description":"Not configured"}}}},"/api/v1/pricing":{"get":{"operationId":"pricing","summary":"Machine-readable prices and pricing rule","responses":{"200":{"description":"Pricing"}}}},"/api/v1/capabilities":{"get":{"operationId":"capabilities","summary":"What the service analyzes and generates","responses":{"200":{"description":"Capabilities"}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Evidence":{"type":"object","properties":{"url":{"type":"string"},"surface":{"type":"string"},"quote":{"type":"string","description":"Verbatim source text in its original language and script."},"source_language":{"type":["string","null"]}}},"Report":{"type":"object","description":"Visibility Optimization Report v1.","properties":{"report_version":{"type":"string"},"request_id":{"type":"string"},"analysis_timestamp":{"type":"string","format":"date-time"},"tier":{"type":"string"},"product_identity":{"type":"object"},"analyzed_surfaces":{"type":"array","items":{"type":"object"}},"languages":{"type":"object","description":"request_language, output_language, detected_source_languages, declared_product_languages, evidenced_output_languages, target_market_languages — kept separate."},"market":{"type":"object","description":"Explicit coverage statements vs. signals; geography is never inferred from language."},"product_summary":{"type":"object","description":"current → recommended"},"capabilities":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"canonical_capability":{"type":"string"},"status":{"type":"string","enum":["SUPPORTED","PARTIALLY_SUPPORTED","UNSUPPORTED","UNCLEAR"]},"basis":{"type":"string"},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"}},"jobs_to_be_done":{"type":"array","items":{"type":"string"}},"intents":{"type":"array","items":{"type":"string"}},"aliases":{"type":"array","items":{"type":"string"}},"local_terms":{"type":"array","items":{"type":"object"}},"constraints":{"type":"array","items":{"type":"string"}},"origin":{"type":"string","enum":["deterministic_lexicon","semantic_model","submitter_claim","boundary_rule"]}}}},"jobs_to_be_done":{"type":"array","items":{"type":"string"}},"agent_intents":{"type":"array","items":{"type":"string"}},"aliases":{"type":"array","items":{"type":"string"}},"multilingual_terms":{"type":"array","items":{"type":"object"}},"original_terms":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"}},"constraints":{"type":"object"},"exclusions":{"type":"object"},"claim_findings":{"type":"array","items":{"type":"object"}},"discovery_gaps":{"type":"array","items":{"type":"object"}},"ambiguity_risks":{"type":"array","items":{"type":"object"}},"checks":{"type":"array","items":{"type":"object"},"description":"Explainable yes/partial/no/not_applicable checks."},"score":{"type":"object","description":"Transparent equal-weight count of checks; not a ranking prediction."},"agent_can_determine":{"type":"object"},"recommendations":{"type":"array","items":{"type":"object"}},"before_after":{"type":"array","items":{"type":"object"}},"artifacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":["string","null"]},"media_type":{"type":"string"},"status":{"type":"string"},"note":{"type":"string"},"content":{"type":"string"},"placeholders":{"type":"array","items":{"type":"string"}}}}},"confidence":{"type":"object"},"limitations":{"type":"array","items":{"type":"string"}},"cost":{"type":"object","description":"Work performed (requests, bytes, model calls, tokens)."},"disclaimer":{"type":"string"}}}}}}