API documentation

One paid endpoint, one retrieval endpoint, free quotes. JSON in, JSON out. Machine-readable: OpenAPI 3.1, llms.txt, pricing, capabilities.

1. Request a report

curl -i https://agentvisibilityoptimizer.online/api/v1/optimize \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7f3c1e0b9a8d4c2e1f0a9b8c7d6e5f40' \
  -d '{"url":"https://example.com","tier":"scan","target_markets":[{"region":"JP","language":"ja"}]}'

The first call returns 402 Payment Required with x402 v2 requirements in the PAYMENT-REQUIRED header (base64) and the body: scheme exact, asset USDC, network eip155:8453, amount in 6-decimal units. Unpaid calls cost nothing and are answered from configuration only.

2. Pay and run

Sign an EIP-3009 USDC authorization with any x402 client (enforce a spending limit) and resend the identical body and Idempotency-Key with PAYMENT-SIGNATURE: <base64>. Payment settles before analysis starts. A scan returns 200 with the report in seconds.

3. Retrieve later

curl https://agentvisibilityoptimizer.online/api/v1/requests/{request_id} -H 'Authorization: Bearer <Idempotency-Key>'

Reports are kept 30 days (then 410).

Input

url (or name + description for products without a site). Optional: docs_url, openapi_url, llms_txt_url, mcp_url, agent_card_url, pricing_url, repository_url, capabilities[] (checked as claims), exclusions[], constraints[], geography[], languages[], target_markets[{region,language}], target_customers[], target_agent_types[], pricing_model, payment_methods[], preferred_output_language, tier (scan | semantic), max_price_usdc. A text/plain body containing only a URL also works. Max 16 KiB. Unknown fields are rejected.

Output

• product_identity, analyzed_surfaces[] (URL, status, HTTP code, bytes, sha256, retrieved_at, language), analysis_timestamp.
• languages: request, output, detected source, declared product, evidenced output and target-market languages — kept separate. market: explicit coverage statements vs. signals (never inferred from language).
• capabilities[]: status SUPPORTED | PARTIALLY_SUPPORTED | UNSUPPORTED | UNCLEAR, basis, verbatim evidence[], jobs_to_be_done, intents, aliases, local_terms (origin: source_verbatim, curated_lexicon or model_suggested), origin.
• claim_findings[], discovery_gaps[], ambiguity_risks[], checks[] (yes/partial/no/not_applicable with explanation), score (transparent formula), agent_can_determine.
• recommendations[], before_after[], artifacts[] (llms.txt, descriptions, JSON-LD, agent-profile.json, OpenAPI patches, x402 description, robots.txt additions, A2A/MCP templates) with [CONFIRM: …] placeholders listed.
• original_terms[], multilingual_terms[], constraints, exclusions, confidence, limitations[], cost, disclaimer.

Tiers and limits

• scan (0.05 USDC): at most 10 URLs fetched directly, 8 s each, 25 s total; deterministic analysis; no model, search or browser.
• semantic (0.18 USDC): scan plus one model call over at most 16000 source tokens. Model statements without a verbatim quote are downgraded to UNCLEAR; generated text with guarantees, superlatives or unevidenced multilingual claims is rejected.

Errors

{"error":{"code","message"}}. 400 invalid request/URL/key · 402 payment required · 409 key or payment reuse · 413 too large · 415 content type · 422 price above ceiling or unresolvable URL (nothing charged) · 429 rate limited · 503 not configured / provider / settlement uncertain.

Retries and refunds

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.

Security

Only public http(s) URLs on default ports are fetched; every DNS answer and every redirect hop is checked against private, loopback, link-local and metadata ranges, and the connection is pinned to the checked address. Pages are treated as untrusted data: instruction-like text is reported and never followed.

Health

GET /api/v1/health checks configuration only (no database). ?ready=1 adds a database probe cached for an hour.