{"openapi":"3.0.3","info":{"title":"Validex","description":"Startup health and validation API providing automated security, trust, web presence, and engineering analysis, individually or as a comprehensive report with AI interpretation.","version":"1.0.0","contact":{"url":"https://api.validex.space"}},"servers":[{"url":"https://api.validex.space"}],"paths":{"/v1/validate/security":{"post":{"operationId":"validateSecurity","summary":"Audits SSL and TLS certificates, HTTP security headers such as HSTS and CSP, SPF, DMARC, MX email records, and DNS configuration.","description":"Audits SSL and TLS certificates, HTTP security headers such as HSTS and CSP, SPF, DMARC, MX email records, and DNS configuration. Price: $0.05 per call via x402 (Algorand USDC).","tags":["security"],"x-x402-payment":{"protocol":"x402","version":2,"network":"algorand","asset":"USDC","pricingManifest":"https://api.validex.space/.well-known/x402","flow":"Call without PAYMENT-SIGNATURE header to receive 402 with PAYMENT-REQUIRED header. Sign and retry with PAYMENT-SIGNATURE."},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetRequest"}}}},"responses":{"200":{"description":"Analysis report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"402":{"description":"Payment required. Read the PAYMENT-REQUIRED response header for machine-readable x402 requirements.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 payment requirements."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredError"}}}},"422":{"description":"Request body validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}},"/v1/validate/trust":{"post":{"operationId":"validateTrust","summary":"Evaluates HTTPS enforcement, domain registration age, WHOIS records, privacy policy, and terms of service documentation.","description":"Evaluates HTTPS enforcement, domain registration age, WHOIS records, privacy policy, and terms of service documentation. Price: $0.05 per call via x402 (Algorand USDC).","tags":["trust"],"x-x402-payment":{"protocol":"x402","version":2,"network":"algorand","asset":"USDC","pricingManifest":"https://api.validex.space/.well-known/x402","flow":"Call without PAYMENT-SIGNATURE header to receive 402 with PAYMENT-REQUIRED header. Sign and retry with PAYMENT-SIGNATURE."},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetRequest"}}}},"responses":{"200":{"description":"Analysis report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"402":{"description":"Payment required. Read the PAYMENT-REQUIRED response header for machine-readable x402 requirements.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 payment requirements."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredError"}}}},"422":{"description":"Request body validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}},"/v1/validate/web":{"post":{"operationId":"validateWeb","summary":"Inspects online presence including pricing transparency, developer documentation, engineering blog, careers page, and contact channels.","description":"Inspects online presence including pricing transparency, developer documentation, engineering blog, careers page, and contact channels. Price: $0.06 per call via x402 (Algorand USDC).","tags":["web"],"x-x402-payment":{"protocol":"x402","version":2,"network":"algorand","asset":"USDC","pricingManifest":"https://api.validex.space/.well-known/x402","flow":"Call without PAYMENT-SIGNATURE header to receive 402 with PAYMENT-REQUIRED header. Sign and retry with PAYMENT-SIGNATURE."},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetRequest"}}}},"responses":{"200":{"description":"Analysis report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"402":{"description":"Payment required. Read the PAYMENT-REQUIRED response header for machine-readable x402 requirements.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 payment requirements."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredError"}}}},"422":{"description":"Request body validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}},"/v1/validate/engineering":{"post":{"operationId":"validateEngineering","summary":"Analyzes public GitHub repository activity, commit frequency, contributor diversity, release cadence, and OSV known vulnerabilities.","description":"Analyzes public GitHub repository activity, commit frequency, contributor diversity, release cadence, and OSV known vulnerabilities. Price: $0.08 per call via x402 (Algorand USDC).","tags":["engineering"],"x-x402-payment":{"protocol":"x402","version":2,"network":"algorand","asset":"USDC","pricingManifest":"https://api.validex.space/.well-known/x402","flow":"Call without PAYMENT-SIGNATURE header to receive 402 with PAYMENT-REQUIRED header. Sign and retry with PAYMENT-SIGNATURE."},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetRequest"}}}},"responses":{"200":{"description":"Analysis report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"402":{"description":"Payment required. Read the PAYMENT-REQUIRED response header for machine-readable x402 requirements.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 payment requirements."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredError"}}}},"422":{"description":"Request body validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}},"/v1/validate/ai":{"post":{"operationId":"validateAi","summary":"Executes full multi-category validation with an AI-generated startup health verdict, risk factor analysis, and integration recommendations.","description":"Executes full multi-category validation with an AI-generated startup health verdict, risk factor analysis, and integration recommendations. Price: $0.15 per call via x402 (Algorand USDC).","tags":["ai"],"x-x402-payment":{"protocol":"x402","version":2,"network":"algorand","asset":"USDC","pricingManifest":"https://api.validex.space/.well-known/x402","flow":"Call without PAYMENT-SIGNATURE header to receive 402 with PAYMENT-REQUIRED header. Sign and retry with PAYMENT-SIGNATURE."},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetRequest"}}}},"responses":{"200":{"description":"Analysis report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"402":{"description":"Payment required. Read the PAYMENT-REQUIRED response header for machine-readable x402 requirements.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 payment requirements."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredError"}}}},"422":{"description":"Request body validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}},"/v1/validate/compare":{"post":{"operationId":"validateCompare","summary":"Performs comparative analysis and health ranking across 2 to 5 startup domains with relative scoring across all categories.","description":"Performs comparative analysis and health ranking across 2 to 5 startup domains with relative scoring across all categories. Price: $0.15 per call via x402 (Algorand USDC).","tags":["compare"],"x-x402-payment":{"protocol":"x402","version":2,"network":"algorand","asset":"USDC","pricingManifest":"https://api.validex.space/.well-known/x402","flow":"Call without PAYMENT-SIGNATURE header to receive 402 with PAYMENT-REQUIRED header. Sign and retry with PAYMENT-SIGNATURE."},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareRequest"}}}},"responses":{"200":{"description":"Analysis report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"402":{"description":"Payment required. Read the PAYMENT-REQUIRED response header for machine-readable x402 requirements.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 payment requirements."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredError"}}}},"422":{"description":"Request body validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}},"/v1/validate/quick":{"post":{"operationId":"validateQuick","summary":"Performs fast-path network connectivity, TLS certificate, security header, and domain trust validation combined with an AI summary.","description":"Performs fast-path network connectivity, TLS certificate, security header, and domain trust validation combined with an AI summary. Price: $0.20 per call via x402 (Algorand USDC).","tags":["quick"],"x-x402-payment":{"protocol":"x402","version":2,"network":"algorand","asset":"USDC","pricingManifest":"https://api.validex.space/.well-known/x402","flow":"Call without PAYMENT-SIGNATURE header to receive 402 with PAYMENT-REQUIRED header. Sign and retry with PAYMENT-SIGNATURE."},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetRequest"}}}},"responses":{"200":{"description":"Analysis report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"402":{"description":"Payment required. Read the PAYMENT-REQUIRED response header for machine-readable x402 requirements.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 payment requirements."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredError"}}}},"422":{"description":"Request body validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}},"/v1/validate/full":{"post":{"operationId":"validateFull","summary":"Conducts a deep audit across all six signal categories including security, trust, web, and engineering with full evidence and AI interpretation.","description":"Conducts a deep audit across all six signal categories including security, trust, web, and engineering with full evidence and AI interpretation. Price: $0.35 per call via x402 (Algorand USDC).","tags":["full"],"x-x402-payment":{"protocol":"x402","version":2,"network":"algorand","asset":"USDC","pricingManifest":"https://api.validex.space/.well-known/x402","flow":"Call without PAYMENT-SIGNATURE header to receive 402 with PAYMENT-REQUIRED header. Sign and retry with PAYMENT-SIGNATURE."},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetRequest"}}}},"responses":{"200":{"description":"Analysis report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"402":{"description":"Payment required. Read the PAYMENT-REQUIRED response header for machine-readable x402 requirements.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64-encoded x402 payment requirements."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequiredError"}}}},"422":{"description":"Request body validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}},"/v1/validate/{analysisId}":{"get":{"operationId":"getAnalysis","summary":"Retrieve a previously-run analysis","description":"Returns the full AnalysisReport when the analysis is completed or partial. Returns { analysisId, status } when still running or pending. Returns { analysisId, status, error } when failed. Free - no payment required.","tags":["read"],"parameters":[{"name":"analysisId","in":"path","required":true,"schema":{"type":"string"},"description":"analysisId returned in meta.analysisId of a previous POST response."}],"responses":{"200":{"description":"Analysis found.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"$ref":"#/components/schemas/PendingResponse"},{"$ref":"#/components/schemas/FailedResponse"}]}}}},"404":{"description":"Analysis not found."}}}},"/v1/validate/compare/{comparisonId}":{"get":{"operationId":"getComparison","summary":"Retrieve a previously-run comparison","description":"Returns the comparison record including ranking and individual analysisIds. Free - no payment required.","tags":["read"],"parameters":[{"name":"comparisonId","in":"path","required":true,"schema":{"type":"string"},"description":"comparisonId returned in meta.comparisonId of a previous POST compare response."}],"responses":{"200":{"description":"Comparison found.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"comparisonId":{"type":"string"},"targets":{"type":"array","items":{"type":"string"}},"targetCount":{"type":"integer"},"ranking":{"type":"array","items":{"type":"object"}},"analysisIds":{"type":"array","items":{"type":"string"},"description":"analysisIds for each ranked target, retrievable via GET /v1/validate/:analysisId."},"createdAt":{"type":"string","format":"date-time"}}}}}}}},"404":{"description":"Comparison not found."}}}},"/v1/health":{"get":{"operationId":"getHealth","summary":"API health status","description":"Returns current health status, active Algorand network, and facilitator URL.","tags":["infrastructure"],"responses":{"200":{"description":"API is healthy.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"network":{"type":"string","enum":["testnet","mainnet"]},"facilitator":{"type":"string","format":"uri"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}}},"components":{"schemas":{"TargetRequest":{"type":"object","required":["target"],"properties":{"target":{"type":"string","description":"Bare domain or full URL of the startup to validate (e.g. \"stripe.com\" or \"https://stripe.com\"). Normalized during entity resolution.","example":"stripe.com"},"refresh":{"type":"boolean","default":false,"description":"When true, bypasses the per-validator result cache and forces fresh data collection."}}},"CompareRequest":{"type":"object","required":["targets"],"properties":{"targets":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":5,"description":"Array of 2-5 bare domains or full URLs to compare.","example":["stripe.com","github.com"]},"refresh":{"type":"boolean","default":false,"description":"When true, bypasses the per-validator result cache for all targets."}}},"CategoryScore":{"type":"object","properties":{"score":{"type":"number","nullable":true,"description":"Category score 0-100, or null if no validators in this category produced a score."},"confidence":{"type":"number","description":"Average confidence (0-100) across evaluated validators in this category."},"weight":{"type":"number","description":"Effective weight used in the overall score calculation, after redistribution for null categories."},"weightRedistributed":{"type":"boolean","description":"True when this category received redistributed weight from null-scoring categories."},"validatorsEvaluated":{"type":"integer","description":"Total number of validators run in this category."},"validatorsUnavailable":{"type":"integer","description":"Number of validators in this category that returned unavailable or error status."}}},"Evidence":{"type":"object","properties":{"statement":{"type":"string","description":"Human-readable factual statement."},"source":{"type":"string","description":"validatorId that produced this evidence."},"url":{"type":"string","description":"Optional URL the statement was sourced from."}}},"ValidatorResult":{"type":"object","properties":{"validatorId":{"type":"string","description":"Unique identifier for the validator."},"name":{"type":"string","description":"Human-readable validator name."},"category":{"type":"string","enum":["security","trust","engineering","product","growth","website"],"description":"Signal category this validator contributes to."},"status":{"type":"string","enum":["success","unavailable","error"],"description":"success: produced a score. unavailable: data source unreachable. error: validator failed unexpectedly."},"score":{"type":"number","nullable":true,"description":"Raw score on the validator's own scale (0 to maxScore). Null when status is unavailable or error."},"maxScore":{"type":"number","description":"Maximum possible raw score for this validator."},"weight":{"type":"number","description":"Relative weight within its category."},"confidence":{"type":"number","description":"Confidence in this result (0-100)."},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"},"description":"Supporting evidence statements."}}},"AnalysisVerdict":{"type":"object","description":"AI-generated narrative. Only present for ai, quick, and full tiers.","properties":{"recommendation":{"type":"string","enum":["integrate","caution","avoid"],"description":"Deterministic recommendation derived from score. integrate >= 70, caution 40-69, avoid < 40."},"executiveSummary":{"type":"string","nullable":true,"description":"3-5 sentence executive summary."},"insights":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Analytical insights based on evaluation signals."},"suggestions":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Actionable suggestions to address weaknesses."},"opportunities":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Strategic growth opportunities."},"riskFlags":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Short strings naming the most important risks."},"categoryNarrative":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Per-category narrative keyed by category name."}}},"AnalysisReport":{"type":"object","properties":{"meta":{"type":"object","properties":{"analysisId":{"type":"string","description":"Unique analysis ID (val_<cuid2>). Use with GET /v1/validate/:analysisId to retrieve without paying again."},"algorithmVersion":{"type":"string","description":"Version of the scoring algorithm used."},"generatedAt":{"type":"string","format":"date-time"},"cached":{"type":"boolean","description":"True if the report was served from cache."},"tier":{"type":"string","enum":["security","trust","web","engineering","ai","compare","quick","full"]}}},"company":{"type":"object","properties":{"domain":{"type":"string","description":"Normalized domain (no www, lowercase)."},"canonicalUrl":{"type":"string","description":"Full canonical URL (https://domain.com)."},"companyName":{"type":"string","nullable":true},"githubRepo":{"type":"string","nullable":true,"description":"GitHub org/repo if detected."}}},"summary":{"type":"object","properties":{"score":{"type":"number","nullable":true,"description":"Overall weighted score 0-100."},"grade":{"type":"string","description":"Letter grade: A+ >= 90, A >= 80, B+ >= 70, B >= 60, C+ >= 50, C >= 40, D >= 30, F < 30."},"confidence":{"type":"number","description":"Overall confidence 0-100."},"executiveSummary":{"type":"string","description":"AI executive summary, when available."}}},"categories":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CategoryScore"},"description":"Per-category scores keyed by category name."},"verdict":{"$ref":"#/components/schemas/AnalysisVerdict"},"strengths":{"type":"array","items":{"type":"string"},"description":"Top positive evidence statements."},"weaknesses":{"type":"array","items":{"type":"string"},"description":"Top negative evidence statements."},"validators":{"type":"array","items":{"$ref":"#/components/schemas/ValidatorResult"},"description":"Individual validator results."},"sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}}},"description":"Data sources consulted."}}},"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/AnalysisReport"}}},"PendingResponse":{"type":"object","description":"Returned by GET /:analysisId when the analysis is still running.","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"analysisId":{"type":"string"},"status":{"type":"string","enum":["pending","running"]}}}}},"FailedResponse":{"type":"object","description":"Returned by GET /:analysisId when the analysis failed.","properties":{"success":{"type":"boolean","example":false},"data":{"type":"object","properties":{"analysisId":{"type":"string"},"status":{"type":"string","enum":["failed"]},"error":{"type":"string"}}}}},"PaymentRequiredError":{"type":"object","description":"x402 payment required. Read the PAYMENT-REQUIRED response header for machine-readable requirements.","properties":{"x402Version":{"type":"integer","example":2},"requirements":{"type":"array","items":{"type":"object"}}}},"ValidationError":{"type":"object","description":"Request body validation failed.","properties":{"statusCode":{"type":"integer","example":422},"message":{"type":"array","items":{"type":"string"}},"error":{"type":"string","example":"Unprocessable Entity"}}}}}}