{"openapi":"3.0.3","info":{"title":"SupplierClear API","version":"1.0.0","description":"Pre-PO quote comparison — evaluate supplier quotes before deposit or PO. Customer responses use projected DTOs (no paymentReference, pdfStorageKey, or full engine trace).","contact":{"name":"Bacenik","url":"https://bacenik.com"}},"servers":[{"url":"/api"}],"paths":{"/v1/evaluate":{"post":{"summary":"Evaluate a single supplier readiness assessment","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"AssessmentInput (jurisdiction, decisionType, intake, answers)"},"responses":{"200":{"description":"Projected PublicReportDecisionResult","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicReportDecisionResult"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/compare":{"post":{"summary":"Compare up to three supplier assessments","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"{ assessments: AssessmentInput[] }"},"responses":{"200":{"description":"Projected ErrorEnvelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/clarity/explain":{"post":{"summary":"Plain-language readiness explanation for embed and procurement panels","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"{ result: DecisionResult, context?: procurement | engineering }"},"responses":{"200":{"description":"Projected ErrorEnvelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/reports/{reportId}":{"get":{"summary":"Retrieve a paid report by reportId (projected public DTOs)","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Projected PublicReportResponse","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicReportResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/reports/{reportId}":{"get":{"summary":"App report GET — public DTOs + redacted trace","security":[{"SessionCookie":[]}],"responses":{"200":{"description":"Projected PublicReportResponse","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicReportResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/connect/assess":{"post":{"summary":"Persist assessment and return DecisionPackage (Connect)","security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"{ assessment, externalRef?, idempotencyKey? }"},"responses":{"200":{"description":"Projected ConnectAssessmentSummary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectAssessmentSummary"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/connect/assessments/{id}":{"get":{"summary":"Connect assessment summary (tenant-bound)","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Projected ConnectAssessmentSummary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectAssessmentSummary"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/connect/assessments/{id}/decision-package":{"get":{"summary":"Machine-readable DecisionPackage with optional briefs/redTeam","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Projected ErrorEnvelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/connect/assessments/{id}/assurance-package":{"get":{"summary":"Decision Assurance Package with HMAC seal","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Projected ErrorEnvelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key"},"SessionCookie":{"type":"apiKey","in":"cookie","name":"sc_session"}},"schemas":{"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Stable machine code"}},"additionalProperties":true},"PublicCustomerTrace":{"type":"object","description":"Redacted scoring trace — no pillarWeights, inputHash, or engineVersion","properties":{"jurisdiction":{"type":"string"},"decisionType":{"type":"string"},"pillarScores":{"type":"object"},"fatalFlaws":{"type":"array"},"gaps":{"type":"array"},"scoreAdjustments":{"type":"array"},"evidenceProvided":{"type":"array","items":{"type":"string"}},"evidenceMissing":{"type":"array","items":{"type":"string"}},"evidenceItems":{"type":"array"},"provenanceSummary":{"type":"string"},"externalSignals":{"type":"array"}},"additionalProperties":false},"PublicReport":{"type":"object","required":["id","reportId","assessmentId","hasPdf","createdAt"],"properties":{"id":{"type":"string"},"reportId":{"type":"string"},"assessmentId":{"type":"string"},"hasPdf":{"type":"boolean"},"disclaimerVersion":{"type":"string"},"scoringVersion":{"type":"string"},"engineVersion":{"type":"string"},"paidAmount":{"type":["integer","null"]},"paidCurrency":{"type":["string","null"]},"paymentProvider":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"clarityJson":{"type":"object"}},"additionalProperties":false},"PublicAssessment":{"type":"object","required":["id","jurisdiction","decisionType","createdAt"],"properties":{"id":{"type":"string"},"userId":{"type":["string","null"]},"organizationId":{"type":["string","null"]},"supplierId":{"type":["string","null"]},"jurisdiction":{"type":"string"},"decisionType":{"type":"string"},"scoringVersion":{"type":"string"},"engineVersion":{"type":"string"},"reviewMode":{"type":["string","null"]},"decisionDeadline":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"intakeJson":{"type":"object"},"answersJson":{"type":"object"},"clarityJson":{"type":"object"},"result":{"type":"object"},"supplier":{"type":"object"},"reports":{"type":"array","items":{"$ref":"#/components/schemas/PublicReport"}}},"additionalProperties":true},"PublicReportDecisionResult":{"type":"object","required":["overallScore","band","summary"],"properties":{"overallScore":{"type":"integer"},"band":{"type":"string"},"recommendation":{"type":"string"},"action":{"type":"string"},"summary":{"type":"string"},"pillarScores":{"type":"object"},"majorRisks":{"type":"array"},"missingEvidence":{"type":"array"},"supplierQuestions":{"type":"array"},"trace":{"$ref":"#/components/schemas/PublicCustomerTrace"}},"additionalProperties":false},"PublicReportResponse":{"type":"object","required":["report","assessment","result"],"properties":{"report":{"$ref":"#/components/schemas/PublicReport"},"assessment":{"$ref":"#/components/schemas/PublicAssessment"},"result":{"oneOf":[{"$ref":"#/components/schemas/PublicReportDecisionResult"},{"type":"null"}]}}},"PublicOrganization":{"type":"object","required":["id","name","slug"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"seatCount":{"type":"integer"},"ssoEnabled":{"type":"boolean"},"workosOrgId":{"type":["string","null"]},"dpaAcceptedAt":{"type":["string","null"]},"dpaVersion":{"type":["string","null"]},"siemConfigured":{"type":"boolean"},"isolatedTenant":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false},"ConnectAssessmentSummary":{"type":"object","required":["id","jurisdiction","decisionType"],"properties":{"id":{"type":"string"},"organizationId":{"type":["string","null"]},"jurisdiction":{"type":"string"},"decisionType":{"type":"string"},"scoringVersion":{"type":"string"},"engineVersion":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"additionalProperties":false}}}}