{"openapi":"3.0.3","info":{"title":"Veridexa Fraud Detection API","version":"1.0.0","description":"Server-to-server (S2S) API for the Veridexa Fraud Detection pipeline. Submit one document per request and retrieve the persisted verification report by jobId. Documents are processed and retained according to the Veridexa privacy policy: https://veridexa.io/privacy .","contact":{"name":"Veridexa API access","url":"https://veridexa.io/contact"}},"servers":[{"url":"https://veridexa.io","description":"Production"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"verification","description":"Submit documents and retrieve Fraud Detection reports."}],"paths":{"/api/s2s/verify":{"post":{"operationId":"verifyDocument","tags":["verification"],"summary":"Submit one document to the Fraud Detection pipeline.","description":"Accepts exactly one document per request as multipart/form-data. The pipeline runs synchronously and the response contains the jobId that can then be passed to GET /api/s2s/report/{jobId}. Documents are transferred to Veridexa for Fraud Detection and processed according to https://veridexa.io/privacy .","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"One document. Allowed MIME types: application/pdf, image/png, image/jpeg, image/webp. Maximum file size: 20 MB."}}},"encoding":{"file":{"contentType":"application/pdf, image/png, image/jpeg, image/webp"}}}}},"responses":{"200":{"description":"Verification job created and processed. Use the returned jobId with GET /api/s2s/report/{jobId} to retrieve the persisted productionReport.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResponse"}}}},"400":{"description":"Malformed multipart body, missing 'file' field, unsupported MIME type, invalid file name, or invalid file size."},"401":{"description":"Missing, malformed, or invalid API key."},"405":{"description":"Method not allowed (only POST is supported)."},"415":{"description":"Content-Type is not multipart/form-data."},"500":{"description":"Job creation, verification processing, or job load failed on the server."},"502":{"description":"Server-side upload of the file to storage failed."}}}},"/api/s2s/report/{jobId}":{"get":{"operationId":"getReport","tags":["verification"],"summary":"Fetch the persisted Fraud Detection report for a jobId.","description":"Returns the persisted productionReport for the tenant-scoped jobId. This endpoint never rebuilds or recomputes the report — it returns the value exactly as persisted by the Fraud Detection pipeline.","security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"parameters":[{"name":"jobId","in":"path","required":true,"description":"The jobId returned by POST /api/s2s/verify.","schema":{"type":"string"}}],"responses":{"200":{"description":"The persisted productionReport for this jobId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportResponse"}}}},"400":{"description":"Missing or malformed authentication credential."},"401":{"description":"Invalid API key."},"404":{"description":"Job not found for this tenant, or the productionReport has not been persisted."},"405":{"description":"Method not allowed (only GET is supported)."},"500":{"description":"Failed to load the job."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Send the API key as: Authorization: Bearer <API_KEY>"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternative to Authorization: Bearer. Send the API key as: X-API-Key: <API_KEY>"}},"schemas":{"VerifyResponse":{"type":"object","required":["jobId"],"properties":{"jobId":{"type":"string","description":"Opaque identifier for the verification job. Pass to GET /api/s2s/report/{jobId} to retrieve the persisted report."}}},"ReportResponse":{"type":"object","required":["productionReport"],"properties":{"productionReport":{"$ref":"#/components/schemas/ProductionReport"}}},"RiskLevel":{"type":"string","enum":["MINIMAL","LOW","MEDIUM","HIGH","CRITICAL"]},"FindingSeverity":{"type":"string","enum":["INFO","LOW","MEDIUM","HIGH","CRITICAL"]},"FindingRef":{"type":"object","required":["id","label","severity","confidence","source"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"severity":{"$ref":"#/components/schemas/FindingSeverity"},"confidence":{"type":"number","minimum":0,"maximum":1},"source":{"type":"string"}}},"FinalReportFindings":{"type":"object","required":["metadata","ocr","qr","digitalSignature","securityFeatures","forensic","documentStructure"],"properties":{"metadata":{"type":"array","items":{"$ref":"#/components/schemas/FindingRef"}},"ocr":{"type":"array","items":{"$ref":"#/components/schemas/FindingRef"}},"qr":{"type":"array","items":{"$ref":"#/components/schemas/FindingRef"}},"digitalSignature":{"type":"array","items":{"$ref":"#/components/schemas/FindingRef"}},"securityFeatures":{"type":"array","items":{"$ref":"#/components/schemas/FindingRef"}},"forensic":{"type":"array","items":{"$ref":"#/components/schemas/FindingRef"}},"documentStructure":{"type":"array","items":{"$ref":"#/components/schemas/FindingRef"}}}},"Recommendation":{"type":"object","required":["id","action","rationale"],"properties":{"id":{"type":"string"},"action":{"type":"string"},"rationale":{"type":"string"}}},"AiSummary":{"type":"object","required":["used","providerId","output","error"],"properties":{"used":{"type":"boolean"},"providerId":{"type":"string","nullable":true},"output":{"type":"object","nullable":true,"additionalProperties":true,"description":"AI reasoning output when used=true; null otherwise."},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"PipelineSummary":{"type":"object","required":["pipelineId","pipelineVersion","stages","telemetry","evidence"],"properties":{"pipelineId":{"type":"string"},"pipelineVersion":{"type":"string"},"stages":{"type":"array","items":{"type":"object","additionalProperties":true}},"telemetry":{"type":"object","additionalProperties":true},"evidence":{"type":"object","additionalProperties":true}}},"ProductionReport":{"type":"object","description":"Persisted FinalVerificationReport as produced by the Fraud Detection pipeline (src/lib/verification/infrastructure/production/types.ts).","required":["reportId","reportVersion","verificationId","generatedAt","ok","authenticityScore","fraudProbability","confidence","riskLevel","detectedManipulations","findings","reasoningSummary","recommendations","pipeline","ai"],"properties":{"reportId":{"type":"string"},"reportVersion":{"type":"string"},"verificationId":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"ok":{"type":"boolean"},"authenticityScore":{"type":"number","minimum":0,"maximum":1},"fraudProbability":{"type":"number","minimum":0,"maximum":1},"confidence":{"type":"number","minimum":0,"maximum":1},"riskLevel":{"$ref":"#/components/schemas/RiskLevel"},"detectedManipulations":{"type":"array","items":{"$ref":"#/components/schemas/FindingRef"}},"findings":{"$ref":"#/components/schemas/FinalReportFindings"},"reasoningSummary":{"type":"string"},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/Recommendation"}},"pipeline":{"$ref":"#/components/schemas/PipelineSummary"},"ai":{"$ref":"#/components/schemas/AiSummary"}}}}}}