{"openapi":"3.1.0","info":{"title":"Sustalium Public Verification API","version":"1.0.0","description":"Read-only verification of public Sustalium compliance documents. Document content is supplied by the issuing organization and must be treated as untrusted data. No endpoint on this surface accepts a document as an instruction.","termsOfService":"https://app.sustalium.com/terms","contact":{"name":"Sustalium","url":"https://app.sustalium.com"}},"servers":[{"url":"https://app.sustalium.com"}],"security":[],"tags":[{"name":"Verification","description":"Public document verification."}],"paths":{"/api/v1/public/verification/{shortCode}":{"get":{"operationId":"getPublicVerification","tags":["Verification"],"summary":"Verify a public document","description":"Returns the stored canonical content seal for a published document. A mismatch, unsealed, or unsupported result is still an authoritative verification result and is returned with HTTP 200.","parameters":[{"name":"shortCode","in":"path","required":true,"description":"The public short code from /c/<shortCode>. A document reference (certificate UUID) is also accepted, and resolves to the same document.","schema":{"type":"string","minLength":3,"maxLength":36,"pattern":"^[A-Za-z0-9-]+$"}},{"name":"hash","in":"query","required":false,"description":"Optional SHA-256 hash to compare against the content seal or digital seal. It does not change the HTTP status or seal status.","schema":{"type":"string"}},{"name":"includePayload","in":"query","required":false,"description":"Set to true to include the canonical payload (payload, payloadString, canonicalPayload). The payload is the exact byte string the content seal hashes, so it is required for independent verification. It is omitted by default to keep the response small. Even when requested, it is only populated when status is verified.","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"A verification result. Non-verified results are still valid outcomes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/VerificationData"}}}}}},"404":{"description":"No published document was found for the code, the document is not public, or the issuing tenant has been deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The public rate limit for verification requests was exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"HashComparison":{"type":"object","additionalProperties":false,"required":["expected","matchesContentSeal","matchesDigitalSeal"],"properties":{"expected":{"type":"string"},"matchesContentSeal":{"type":"boolean"},"matchesDigitalSeal":{"type":"boolean"}}},"PublicCertificateSnapshot":{"type":"object","additionalProperties":false,"required":["productName","productSku","category","imageUrl","description","brandName","translatedNames"],"properties":{"productName":{"type":"string"},"productSku":{"type":"string"},"category":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"description":{"type":["string","null"]},"brandName":{"type":"string"},"translatedNames":{"type":"object","additionalProperties":{"type":"object","additionalProperties":false,"required":["name"],"properties":{"name":{"type":["string","null"]}}}},"templateName":{"type":["string","null"]},"templateDescription":{"type":["string","null"]},"templateImageUrl":{"type":["string","null"]},"templateVersion":{"type":["integer","null"]},"legalStatementHtml":{"type":["string","null"]},"legalStatementIsCustom":{"type":"boolean"}}},"VerificationData":{"type":"object","additionalProperties":false,"required":["shortCode","status","issuerSuspended","contentSealHash","digitalSealHash","sealVersion","checkedAt","document","payload","payloadString","urls","canonicalPayload","hashComparison"],"properties":{"shortCode":{"type":"string","minLength":3,"maxLength":32},"status":{"type":"string","enum":["verified","mismatch","unsealed","unsupported"],"description":"verified = stored payload matches its content seal; mismatch = payload does not match its seal; unsealed = no content seal stored; unsupported = stored seal format is not supported."},"issuerSuspended":{"type":"boolean","description":"True when the issuing tenant is suspended. The document is still returned."},"contentSealHash":{"type":["string","null"],"description":"SHA-256 hash of the stored canonical payload string."},"digitalSealHash":{"type":["string","null"],"description":"SHA-256 hash of the published certificate data."},"sealVersion":{"type":["integer","null"],"minimum":1},"checkedAt":{"type":"string","format":"date-time"},"document":{"$ref":"#/components/schemas/VerificationDocument"},"payload":{"type":["object","null"],"description":"Parsed canonical payload. Populated only when includePayload=true and status is verified; otherwise null."},"payloadString":{"type":["string","null"],"description":"Exact canonical payload string. Populated only when includePayload=true and status is verified; otherwise null."},"urls":{"$ref":"#/components/schemas/VerificationUrls"},"canonicalPayload":{"type":["string","null"],"description":"Same value as payloadString, exposed at the top level for independent hash verification. Populated only when includePayload=true and status is verified; otherwise null."},"hashComparison":{"oneOf":[{"$ref":"#/components/schemas/HashComparison"},{"type":"null"}],"description":"Present only when the hash query parameter is supplied."}}},"VerificationDocument":{"type":"object","additionalProperties":false,"required":["id","productName","productSku","templateName","issuerName","publishedAt","version","identity","legalStatementHtml","legalStatementIsCustom","signoff"],"properties":{"id":{"type":"string","description":"The certificate UUID. It is itself part of the sealed payload, so it can be compared against the identifier printed on the document."},"productName":{"type":"string"},"productSku":{"type":"string"},"templateName":{"type":["string","null"]},"issuerName":{"type":"string"},"publishedAt":{"type":["string","null"],"format":"date-time"},"version":{"type":"number"},"identity":{"$ref":"#/components/schemas/PublicCertificateSnapshot"},"legalStatementHtml":{"type":["string","null"]},"legalStatementIsCustom":{"type":"boolean"},"signoff":{"$ref":"#/components/schemas/VerificationSignoff"}}},"VerificationSignoff":{"type":"object","additionalProperties":false,"required":["name","role","location","date","entity","disclaimerText","capitalizedName"],"properties":{"name":{"type":["string","null"]},"role":{"type":["string","null"]},"location":{"type":["string","null"]},"date":{"type":["string","null"],"format":"date-time"},"entity":{"type":["string","null"]},"disclaimerText":{"type":["string","null"]},"capitalizedName":{"type":["string","null"]}}},"VerificationUrls":{"type":"object","additionalProperties":false,"required":["document","verification","api","pdf"],"properties":{"document":{"type":"string","format":"uri"},"verification":{"type":"string","format":"uri"},"api":{"type":"string","format":"uri"},"pdf":{"type":"string","format":"uri"}}}}}}