{"openapi":"3.1.0","info":{"title":"FINLY public Agent API","version":"finly-agent-access-1"},"paths":{"/agent/v1/reports/tools/analyze_balance_report":{"post":{"operationId":"analyze_balance_report","summary":"Analyze a PDF, JPEG or PNG balance report with current agent-attested user consent and solved challenge. Returns an immediate explicit result without storing the file or result. External OCR is used only with separate consent; do not automatically retry a consumed challenge.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"content_base64":{"type":"string","minLength":4,"maxLength":25165824},"security_challenge":{"type":"string","minLength":1,"maxLength":2048},"security_proof":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9_-]+$"},"authorization":{"type":"object","properties":{"policy_version":{"type":"string","minLength":1,"maxLength":100},"text_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"user_approved_processing":{"type":"boolean","const":true},"user_approved_result_sharing":{"type":"boolean","const":true}},"required":["policy_version","text_sha256","user_approved_processing","user_approved_result_sharing"],"additionalProperties":false},"external_ocr":{"type":"object","properties":{"approved":{"type":"boolean","const":true},"policy_version":{"type":"string","minLength":1,"maxLength":100},"text_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["approved","policy_version","text_sha256"],"additionalProperties":false}},"required":["content_base64","security_challenge","security_proof","authorization"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Validated result or explicit no_action","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"request_id":{"type":"string"},"schema_version":{"const":"finly-agent-access-1"},"tool":{"const":"analyze_balance_report"},"response_kind":{"const":"calculation"},"status":{"type":"string","enum":["success","insufficient_data","needs_review","stale_data","consent_required","approval_required","pending","conflict","unsupported","temporarily_unavailable","rate_limited","not_found_or_not_authorized","revoked","expired","delivery_unknown"]},"as_of":{"type":"string","format":"date-time"},"assumptions":{"type":"array","items":{}},"limitations":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{}},"receipt":{"type":"object"},"evidence":{"type":"array","items":{}},"result":{"type":"object","properties":{"rateBasis":{"type":"string","const":"report"},"trackCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"tracks":{"type":"array","items":{"type":"object","properties":{"labelHe":{"type":"string","enum":["פריים","קבועה לא צמודה","קבועה צמודה","משתנה לא צמודה","משתנה צמודה","מסלול (סוג לא זוהה)"]},"balanceAgorot":{"type":"integer","minimum":0,"maximum":9007199254740991},"ratePct":{"anyOf":[{"type":"number"},{"type":"null"}]},"termMonths":{"type":"integer","minimum":0,"maximum":9007199254740991},"primeSpreadPct":{"type":"number"},"resetIntervalMonths":{"type":"integer","minimum":0,"maximum":9007199254740991,"exclusiveMinimum":0},"anchorSpreadPct":{"type":"number"},"nextResetDate":{"type":"string","pattern":"^\\d{2}\\/\\d{2}\\/\\d{4}$"},"monthlyPaymentAgorot":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["labelHe","balanceAgorot","ratePct","termMonths"],"additionalProperties":false}},"totalBalanceAgorot":{"type":"integer","minimum":0,"maximum":9007199254740991},"weightedRatePct":{"anyOf":[{"type":"number"},{"type":"null"}]},"reportAsOfDate":{"type":"string","pattern":"^\\d{2}\\/\\d{2}\\/\\d{4}$"},"payoffTotalAgorot":{"type":"integer","minimum":0,"maximum":9007199254740991},"payoffFeesAgorot":{"type":"integer","minimum":0,"maximum":9007199254740991},"missingTerm":{"type":"integer","minimum":0,"maximum":9007199254740991},"missingRate":{"type":"integer","minimum":0,"maximum":9007199254740991},"missingType":{"type":"integer","minimum":0,"maximum":9007199254740991},"rateCoveragePct":{"type":"number","minimum":0,"maximum":100},"linkedSharePct":{"type":"number","minimum":0,"maximum":100},"variableSharePct":{"type":"number","minimum":0,"maximum":100},"combinedExposurePct":{"type":"number","minimum":0,"maximum":100},"longestTermMonths":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"attentionScore":{"type":"number","minimum":0,"maximum":100},"attentionLabel":{"type":"string","minLength":1,"maxLength":300},"headlineHe":{"type":"string","minLength":1,"maxLength":500},"nextStepHe":{"type":"string","minLength":1,"maxLength":2000},"comparisonRatePct":{"type":"number"},"forecastRatePct":{"type":"number"},"feeBreakdown":{"type":"object","properties":{"noNoticeAgorot":{"type":"integer","minimum":0,"maximum":9007199254740991},"avgIndexAgorot":{"type":"integer","minimum":0,"maximum":9007199254740991},"discountingAgorot":{"type":"integer","minimum":0,"maximum":9007199254740991},"operationalAgorot":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["noNoticeAgorot","avgIndexAgorot","discountingAgorot","operationalAgorot"],"additionalProperties":false},"monthlyPaymentTotalAgorot":{"type":"integer","minimum":0,"maximum":9007199254740991},"factors":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["attention","positive","missing","fact"]},"title":{"type":"string","minLength":1,"maxLength":300},"detail":{"type":"string","minLength":1,"maxLength":4000}},"required":["kind","title","detail"],"additionalProperties":false}},"marketComparison":{"type":"object","properties":{"effectiveDate":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}]},"weightedFixedGapPct":{"anyOf":[{"type":"number"},{"type":"null"}]},"comparedSharePct":{"type":"number","minimum":0,"maximum":100},"uncomparedFixedCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"entries":{"type":"array","items":{"type":"object","properties":{"labelHe":{"type":"string","enum":["פריים","קבועה לא צמודה","קבועה צמודה","משתנה לא צמודה","משתנה צמודה","מסלול (סוג לא זוהה)"]},"balanceAgorot":{"type":"integer","minimum":0,"maximum":9007199254740991},"kind":{"type":"string","enum":["fixed","prime"]},"gapBasis":{"type":"string","const":"report_spread"},"gapPct":{"type":"number"}},"required":["labelHe","balanceAgorot","kind","gapPct"],"additionalProperties":false}}},"required":["effectiveDate","weightedFixedGapPct","comparedSharePct","uncomparedFixedCount","entries"],"additionalProperties":false}},"required":["trackCount","tracks","totalBalanceAgorot","weightedRatePct","missingTerm","missingRate","rateCoveragePct","linkedSharePct","variableSharePct","combinedExposurePct","longestTermMonths","attentionScore","attentionLabel","headlineHe","nextStepHe","factors"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"no_action":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"code":{"type":"string"},"missing_fields":{"type":"array","items":{"type":"string"}},"retry_after_ms":{"type":"number"}},"required":["code"],"additionalProperties":false}},"required":["request_id","schema_version","tool","response_kind","status","as_of","assumptions","limitations","next_actions","receipt"],"additionalProperties":false,"oneOf":[{"required":["result"],"properties":{"status":{"const":"success"}},"not":{"required":["no_action"]}},{"required":["no_action"],"properties":{"status":{"not":{"const":"success"}}},"not":{"required":["result"]}}]}}}},"401":{"description":"Authentication required"},"404":{"description":"Unavailable capability"},"429":{"description":"Retry after the returned interval"}}}},"/agent/v1/reports/tools/get_report_analysis_requirements":{"post":{"operationId":"get_report_analysis_requirements","summary":"Get the current processing and result-sharing consent, optional external OCR consent, and a single-use proof-of-work challenge. Solve SHA-256(challenge_token + \":\" + proof) so its first two bytes are zero. User approval is attested by the calling agent.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}}},"responses":{"200":{"description":"Validated result or explicit no_action","content":{"application/json":{"schema":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"request_id":{"type":"string"},"schema_version":{"const":"finly-agent-access-1"},"tool":{"const":"get_report_analysis_requirements"},"response_kind":{"const":"workflow"},"status":{"type":"string","enum":["success","insufficient_data","needs_review","stale_data","consent_required","approval_required","pending","conflict","unsupported","temporarily_unavailable","rate_limited","not_found_or_not_authorized","revoked","expired","delivery_unknown"]},"as_of":{"type":"string","format":"date-time"},"assumptions":{"type":"array","items":{}},"limitations":{"type":"array","items":{"type":"string"}},"next_actions":{"type":"array","items":{}},"receipt":{"type":"object"},"evidence":{"type":"array","items":{}},"result":{"type":"object","properties":{"authorization_policy":{"type":"object","properties":{"policy_version":{"type":"string","minLength":1,"maxLength":100},"text":{"type":"string","minLength":1},"text_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"privacy_url":{"type":"string","const":"/privacy"}},"required":["policy_version","text","text_sha256","privacy_url"],"additionalProperties":false},"external_ocr_policy":{"type":"object","properties":{"policy_version":{"type":"string","minLength":1,"maxLength":100},"text":{"type":"string","minLength":1},"text_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"privacy_url":{"type":"string","const":"/privacy"}},"required":["policy_version","text","text_sha256","privacy_url"],"additionalProperties":false},"security_challenge":{"type":"object","properties":{"challenge_token":{"type":"string"},"algorithm":{"type":"string","const":"sha256"},"difficulty_bits":{"type":"number","const":16},"expires_at":{"type":"string","format":"date-time"}},"required":["challenge_token","algorithm","difficulty_bits","expires_at"],"additionalProperties":false},"limits":{"type":"object","properties":{"max_file_bytes":{"type":"number","const":18874368},"allowed_mime_types":{"type":"array","minItems":3,"maxItems":3,"items":[{"type":"string","const":"application/pdf"},{"type":"string","const":"image/jpeg"},{"type":"string","const":"image/png"}]},"analysis_attempts_per_hour":{"type":"number","const":3},"max_concurrent_analyses":{"type":"number","const":2},"analysis_timeout_ms":{"type":"number","const":120000}},"required":["max_file_bytes","allowed_mime_types","analysis_attempts_per_hour","max_concurrent_analyses","analysis_timeout_ms"],"additionalProperties":false},"handling":{"type":"object","properties":{"file_and_result_storage":{"type":"boolean","const":false},"result_delivery":{"type":"string","const":"immediate_response"},"consent_evidence":{"type":"string","const":"calling_agent_attestation"}},"required":["file_and_result_storage","result_delivery","consent_evidence"],"additionalProperties":false}},"required":["authorization_policy","external_ocr_policy","security_challenge","limits","handling"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"},"no_action":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"code":{"type":"string"},"missing_fields":{"type":"array","items":{"type":"string"}},"retry_after_ms":{"type":"number"}},"required":["code"],"additionalProperties":false}},"required":["request_id","schema_version","tool","response_kind","status","as_of","assumptions","limitations","next_actions","receipt"],"additionalProperties":false,"oneOf":[{"required":["result"],"properties":{"status":{"const":"success"}},"not":{"required":["no_action"]}},{"required":["no_action"],"properties":{"status":{"not":{"const":"success"}}},"not":{"required":["result"]}}]}}}},"401":{"description":"Authentication required"},"404":{"description":"Unavailable capability"},"429":{"description":"Retry after the returned interval"}}}}}}