{"openapi":"3.1.0","info":{"title":"MCP x402 - Evidence-Backed Web Verification","version":"1.2.5","description":"EN: x402 service for AI analysis of public web pages and auditable condition verification. Payment instructions are returned through the payment-required header. PT: Serviço x402 para análise com IA de páginas web públicas e verificação auditável de condições. As instruções de pagamento são devolvidas no cabeçalho payment-required.","x-supported-languages":["en","pt-PT"]},"servers":[{"url":"https://mcp-x402-production.up.railway.app"}],"paths":{"/analyze":{"post":{"summary":"Analisa uma página web pública","tags":["URL analysis","x402"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"URL pública HTTP ou HTTPS a analisar."},"objetivo":{"type":"string","description":"Objetivo opcional da análise."}}}}}},"responses":{"200":{"description":"Análise concluída.","headers":{"x-feedback-endpoint":{"description":"Endpoint opcional para feedback normalizado desta jornada.","schema":{"type":"string","format":"uri"}},"x-feedback-reasons":{"description":"Motivos de feedback permitidos, separados por vírgulas.","schema":{"type":"string"}},"x-feedback-stages":{"description":"Etapas de funil permitidas, separadas por vírgulas.","schema":{"type":"string"}},"x-feedback-intents":{"description":"Intenções opcionais permitidas, separadas por vírgulas.","schema":{"type":"string"}}}},"400":{"description":"Pedido inválido."},"402":{"description":"Pagamento x402 necessário. A resposta também anuncia o endpoint e os valores normalizados de feedback, caso o cliente não prossiga.","headers":{"payment-required":{"description":"Condições de pagamento x402.","schema":{"type":"string"}},"x-feedback-endpoint":{"description":"Endpoint opcional para feedback normalizado desta jornada.","schema":{"type":"string","format":"uri"}},"x-feedback-reasons":{"description":"Motivos de feedback permitidos, separados por vírgulas.","schema":{"type":"string"}},"x-feedback-stages":{"description":"Etapas de funil permitidas, separadas por vírgulas.","schema":{"type":"string"}},"x-feedback-intents":{"description":"Intenções opcionais permitidas, separadas por vírgulas.","schema":{"type":"string"}}}},"502":{"description":"Falha temporária ao analisar a URL."}}}},"/verify-conditions":{"post":{"summary":"Verifica condições numa página web","description":"Devolve um recibo auditável com decisão por condição, prova textual, data/hora, ID único e hash SHA-256 do conteúdo.","tags":["Decision verification","x402"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","condicoes"],"properties":{"url":{"type":"string","format":"uri","description":"URL pública HTTP ou HTTPS a verificar."},"condicoes":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"},"description":"Condições concretas que a página deve cumprir."},"contexto":{"type":"string","description":"Contexto opcional para interpretar as condições."}}}}}},"responses":{"200":{"description":"Recibo auditável: decisão por condição, prova textual quando disponível, verificationId e pageHash SHA-256.","headers":{"x-feedback-endpoint":{"description":"Endpoint opcional para feedback normalizado desta jornada.","schema":{"type":"string","format":"uri"}},"x-feedback-reasons":{"description":"Motivos de feedback permitidos, separados por vírgulas.","schema":{"type":"string"}},"x-feedback-stages":{"description":"Etapas de funil permitidas, separadas por vírgulas.","schema":{"type":"string"}},"x-feedback-intents":{"description":"Intenções opcionais permitidas, separadas por vírgulas.","schema":{"type":"string"}}}},"400":{"description":"Pedido inválido."},"402":{"description":"Pagamento x402 necessário. A resposta também anuncia o endpoint e os valores normalizados de feedback, caso o cliente não prossiga.","headers":{"payment-required":{"description":"Condições de pagamento x402.","schema":{"type":"string"}},"x-feedback-endpoint":{"description":"Endpoint opcional para feedback normalizado desta jornada.","schema":{"type":"string","format":"uri"}},"x-feedback-reasons":{"description":"Motivos de feedback permitidos, separados por vírgulas.","schema":{"type":"string"}},"x-feedback-stages":{"description":"Etapas de funil permitidas, separadas por vírgulas.","schema":{"type":"string"}},"x-feedback-intents":{"description":"Intenções opcionais permitidas, separadas por vírgulas.","schema":{"type":"string"}}}},"502":{"description":"Falha temporária ao verificar a página."}}}},"/preflight/analyze":{"post":{"summary":"Valida gratuitamente um pedido de análise","description":"Não cobra, não descarrega a página e não executa IA. Confirma o JSON e devolve preço, rede, destino pago, próximo passo e estrutura prevista do resultado.","tags":["Preflight","URL analysis"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"URL pública HTTP ou HTTPS a analisar."},"objetivo":{"type":"string","description":"Objetivo opcional da análise."}}},"example":{"url":"https://example.com","objetivo":"Resumir factos, riscos e ações recomendadas."}}}},"responses":{"200":{"description":"JSON válido. Devolve preço, rede, endpoint pago, próximo passo e resultado previsto."},"400":{"description":"JSON inválido; devolve os campos a corrigir."}}}},"/preflight/verify-conditions":{"post":{"summary":"Valida gratuitamente um pedido de verificação","description":"Não cobra, não descarrega a página e não executa IA. Confirma a URL e entre 1 e 10 condições, devolvendo preço, rede, destino pago, próximo passo e estrutura prevista do recibo.","tags":["Preflight","Decision verification"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","condicoes"],"properties":{"url":{"type":"string","format":"uri","description":"URL pública HTTP ou HTTPS a verificar."},"condicoes":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string"},"description":"Condições concretas que a página deve cumprir."},"contexto":{"type":"string","description":"Contexto opcional para interpretar as condições."}}},"example":{"url":"https://example.com","condicoes":["A página identifica o vendedor."],"contexto":"Avaliação antes de uma compra."}}}},"responses":{"200":{"description":"JSON válido. Devolve preço, rede, endpoint pago, próximo passo e campos previstos do recibo."},"400":{"description":"JSON inválido; devolve os campos a corrigir."}}}},"/preflight/mcp":{"post":{"summary":"Valida gratuitamente uma chamada MCP paga","description":"Não cobra nem executa a ferramenta. Valida toolName e arguments, devolvendo o endpoint MCP HTTPS, preço, rede e instruções para preservar o journeyId.","tags":["Preflight","MCP"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["toolName","arguments"],"properties":{"toolName":{"type":"string","enum":["consultar_ia","analisar_url","verificar_condicoes"]},"arguments":{"type":"object"}}},"example":{"toolName":"consultar_ia","arguments":{"prompt":"Responde apenas: MCP OK"}}}}},"responses":{"200":{"description":"Ferramenta e argumentos válidos; devolve URL MCP, preço e próximo passo."},"400":{"description":"Ferramenta ou argumentos inválidos."}}}},"/feedback":{"post":{"summary":"Regista feedback normalizado e opcional da jornada","description":"Não cobra e não aceita texto livre. O motivo deve ser escolhido explicitamente pelo cliente. O valor integration_error só pode ser enviado automaticamente quando o comprador detetar objetivamente uma falha técnica.","tags":["Feedback","Observability"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["journeyId","reason"],"properties":{"journeyId":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$","description":"Identificador devolvido no cabeçalho x-journey-id ou pelo preflight."},"reason":{"type":"string","enum":["research_only","no_wallet","unsupported_network","insufficient_funds","spending_not_authorized","price","insufficient_value","integration_error","other"],"description":"Motivo normalizado escolhido explicitamente. Não inferir motivações humanas."},"stage":{"type":"string","enum":["discovery","preflight","payment","execution","delivery"],"description":"Etapa observável em que a jornada terminou."},"intent":{"type":"string","enum":["research","analyze_page","verify_conditions","general_question","evaluate_service","other"],"description":"Objetivo opcional declarado pelo cliente, separado do motivo de abandono ou resultado."},"automatic":{"type":"boolean","default":false,"description":"Verdadeiro apenas para integration_error gerado por uma falha técnica objetivamente detetada."}}},"examples":{"stoppedAtPayment":{"summary":"Cliente não prosseguiu devido ao preço","value":{"journeyId":"example_journey_123","reason":"price","stage":"payment","intent":"evaluate_service"}},"technicalFailure":{"summary":"Erro técnico detetado automaticamente","value":{"journeyId":"example_journey_456","reason":"integration_error","stage":"preflight","intent":"analyze_page","automatic":true}}}}}},"responses":{"202":{"description":"Feedback validado e registado."},"400":{"description":"Feedback inválido; devolve campos e valores permitidos."},"429":{"description":"Limite temporário de pedidos excedido."}}}},"/mcp":{"post":{"summary":"Endpoint Model Context Protocol","tags":["MCP"],"responses":{"200":{"description":"Resposta MCP."}}}}}}