{"openapi":"3.1.0","info":{"title":"GET /api/v1/public/trust/{token}","version":"1.0.0","description":"Public trust scorecard viewer (unauthenticated)"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/public/trust/{token}":{"get":{"tags":["trust-public"],"summary":"Public trust scorecard viewer (unauthenticated)","description":"Resolve a share token to a business's trust scorecard: the current month's grade, the cards and the 12-month history. Returns 404 for unknown, expired or revoked tokens, indistinguishably. Rate-limited per IP and cached for 60 seconds.","operationId":"fetch_public_trust_scorecard","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_PublicTrustScorecardResponse_"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded; back off and retry","content":{"application/json":{"example":{"error":"rate_limited","message":"Too many requests. Please slow down.","code":"GEN_005","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"fetch_public_trust_scorecard_api_v1_public_trust__token__get"}}},"components":{"schemas":{"AnomaliesSection":{"properties":{"raised":{"$ref":"#/components/schemas/NullableMetric","description":"Open findings in the latest scan first detected in the month"},"resolved":{"type":"integer","title":"Resolved","description":"Findings a person dismissed in the month"},"resolved_by_reason":{"additionalProperties":{"type":"integer"},"type":"object","title":"Resolved By Reason"},"open_now":{"$ref":"#/components/schemas/NullableMetric","description":"Open findings in the latest scan"},"open_high":{"$ref":"#/components/schemas/NullableMetric"},"last_scanned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Scanned At"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"How raised and resolved relate to the scan's own records"}},"additionalProperties":false,"type":"object","required":["raised","resolved","open_now","open_high"],"title":"AnomaliesSection","description":"Anomaly findings raised and dismissed in the month."},"ApprovalsSection":{"properties":{"proposed":{"type":"integer","title":"Proposed","description":"Changes proposed in the month"},"approved":{"type":"integer","title":"Approved","description":"Decided approved in the month (applied or not)"},"rejected":{"type":"integer","title":"Rejected"},"expired":{"type":"integer","title":"Expired"},"failed":{"type":"integer","title":"Failed","description":"Approved, but the apply failed"},"still_pending":{"type":"integer","title":"Still Pending","description":"Proposed in the month, not yet decided"},"approval_rate_pct":{"$ref":"#/components/schemas/NullableMetric","description":"approved / (approved + rejected), 0-100; null with no decisions"},"rounds_decided":{"type":"integer","title":"Rounds Decided"},"rounds_expired":{"type":"integer","title":"Rounds Expired"}},"additionalProperties":false,"type":"object","required":["proposed","approved","rejected","expired","failed","still_pending","approval_rate_pct","rounds_decided","rounds_expired"],"title":"ApprovalsSection","description":"Proposed changes and approval rounds decided in the month."},"AutomationKindCount":{"properties":{"kind":{"type":"string","title":"Kind"},"runs":{"type":"integer","title":"Runs"},"items_changed":{"type":"integer","title":"Items Changed"},"items_reverted":{"type":"integer","title":"Items Reverted"}},"additionalProperties":false,"type":"object","required":["kind","runs","items_changed","items_reverted"],"title":"AutomationKindCount","description":"Runs and changed rows of one automation kind."},"AutomationSection":{"properties":{"runs_applied":{"type":"integer","title":"Runs Applied","description":"Runs that started in the month"},"runs_undone":{"type":"integer","title":"Runs Undone"},"runs_partially_undone":{"type":"integer","title":"Runs Partially Undone"},"items_changed":{"type":"integer","title":"Items Changed","description":"Rows the month's runs wrote"},"items_reverted":{"type":"integer","title":"Items Reverted","description":"Of those, rows later put back by an undo"},"reversal_rate_pct":{"$ref":"#/components/schemas/NullableMetric","description":"items_reverted / items_changed, 0-100; null when nothing ran"},"by_kind":{"items":{"$ref":"#/components/schemas/AutomationKindCount"},"type":"array","title":"By Kind"}},"additionalProperties":false,"type":"object","required":["runs_applied","runs_undone","runs_partially_undone","items_changed","items_reverted","reversal_rate_pct"],"title":"AutomationSection","description":"What the unattended automations did in the month and how much was undone."},"CategorizationSourceCount":{"properties":{"source":{"type":"string","title":"Source","description":"Who chose the category: bank_rule, ai, payment_match, human, history, transfer, other_automation, uncategorized"},"count":{"type":"integer","title":"Count"},"share_pct":{"type":"number","title":"Share Pct","description":"Share of the month's transactions, 0-100"}},"additionalProperties":false,"type":"object","required":["source","count","share_pct"],"title":"CategorizationSourceCount","description":"Transactions in the month whose current category came from one source."},"CloseSection":{"properties":{"period_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Id"},"period_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Status","description":"open, closed, locked"},"closed":{"type":"boolean","title":"Closed","description":"The period is closed or locked"},"closed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Closed At"},"close_score":{"$ref":"#/components/schemas/NullableMetric","description":"Latest stored close score, 0-100"},"close_score_color":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Close Score Color"},"business_days_to_close":{"$ref":"#/components/schemas/NullableMetric","description":"Business days (Mon-Fri) from period end to closed_at"},"calendar_days_to_close":{"$ref":"#/components/schemas/NullableMetric","description":"Calendar days from period end to closed_at"},"close_target_business_day":{"type":"integer","title":"Close Target Business Day","description":"The business day the close is due by; default 3"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"not_tracked when no period covers the month"}},"additionalProperties":false,"type":"object","required":["closed","close_score","business_days_to_close","calendar_days_to_close","close_target_business_day"],"title":"CloseSection","description":"The accounting period that covers the month."},"CohortRef":{"properties":{"key":{"type":"string","title":"Key","description":"industry, revenue_band or channel_mix"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value","description":"The business's value for the key; null when unknown"},"description":{"type":"string","title":"Description","description":"Plain-language label for the cell"},"n":{"type":"integer","title":"N","description":"Contributors in the cell this month (0 when unknown)"},"qualifies":{"type":"boolean","title":"Qualifies","description":"n meets the minimum cohort size"}},"additionalProperties":false,"type":"object","required":["key","value","description","n","qualifies"],"title":"CohortRef","description":"One cohort cell the business belongs to and whether it can be shown."},"CorrectionsSection":{"properties":{"total":{"type":"integer","title":"Total","description":"Distinct transactions a person re-categorized after automation"},"rule_overrides":{"type":"integer","title":"Rule Overrides","description":"Rows a person re-categorized after a bank rule booked them"},"post_run_recategorizations":{"type":"integer","title":"Post Run Recategorizations","description":"Rows an automation run categorized in the month that a person re-categorized afterwards"},"ai_recategorizations":{"$ref":"#/components/schemas/NullableMetric","description":"Rows a person re-categorized after an AI pick made outside a run; the books keep no prior-category record, so this is not tracked"}},"additionalProperties":false,"type":"object","required":["total","rule_overrides","post_run_recategorizations","ai_recategorizations"],"title":"CorrectionsSection","description":"Categories a person changed after an automation had chosen them."},"GradeComponent":{"properties":{"name":{"type":"string","title":"Name","description":"auto_coded_share, reversal_rate, close_speed"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"grade":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Grade","description":"Best grade this column allows (A-D); null when left out"},"counted":{"type":"boolean","title":"Counted","description":"False when the column could not be evaluated"},"note":{"type":"string","title":"Note"}},"additionalProperties":false,"type":"object","required":["name","value","grade","counted","note"],"title":"GradeComponent","description":"One column of the rubric and the best grade it alone allows."},"NullableMetric":{"properties":{"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"not_tracked when the books hold no record; else why it is null"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"}},"additionalProperties":false,"type":"object","title":"NullableMetric","description":"A figure that may be unavailable; ``reason`` says why when it is."},"PercentileValue":{"properties":{"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"cohort_too_small, no_cohort, no_value or opted_out when null"}},"additionalProperties":false,"type":"object","title":"PercentileValue","description":"Where the business sits in its cohort for one metric, 0-100."},"ProvenanceSection":{"properties":{"journal_entries":{"type":"integer","title":"Journal Entries"},"with_source":{"type":"integer","title":"With Source","description":"Entries whose origin (source) is recorded"},"coverage_pct":{"$ref":"#/components/schemas/NullableMetric","description":"with_source / journal_entries, 0-100; null with no entries"},"by_source":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Source"}},"additionalProperties":false,"type":"object","required":["journal_entries","with_source","coverage_pct"],"title":"ProvenanceSection","description":"Journal entries in the month that carry their source."},"PublicTrustScorecardResponse":{"properties":{"business_name":{"type":"string","title":"Business Name"},"scorecard":{"$ref":"#/components/schemas/TrustScorecardResponse"},"history":{"items":{"$ref":"#/components/schemas/TrustScorecardHistoryItem"},"type":"array","title":"History"},"cached":{"type":"boolean","title":"Cached","default":false}},"additionalProperties":false,"type":"object","required":["business_name","scorecard"],"title":"PublicTrustScorecardResponse","description":"What an anonymous viewer of a share link sees: grade, counts, history.\n\nEvery field is an aggregate; no transaction, counterparty, amount or person\nappears anywhere in the scorecard."},"SuccessEnvelope_PublicTrustScorecardResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/PublicTrustScorecardResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[PublicTrustScorecardResponse]"},"TransactionsSection":{"properties":{"total":{"type":"integer","title":"Total","description":"Transactions dated in the month, deleted excluded"},"by_source":{"items":{"$ref":"#/components/schemas/CategorizationSourceCount"},"type":"array","title":"By Source"},"auto_coded":{"type":"integer","title":"Auto Coded","description":"Coded by a bank rule, the agent/AI or a payment match"},"auto_coded_pct":{"$ref":"#/components/schemas/NullableMetric","description":"auto_coded / total, 0-100; null when the month has no transactions"},"human_coded":{"type":"integer","title":"Human Coded","description":"Categorized by a person"},"human_coded_pct":{"type":"number","title":"Human Coded Pct"},"uncategorized":{"type":"integer","title":"Uncategorized","description":"Still on an Uncategorized ledger or no entry"},"uncategorized_pct":{"type":"number","title":"Uncategorized Pct"},"unreviewed":{"type":"integer","title":"Unreviewed","description":"Still marked for review"}},"additionalProperties":false,"type":"object","required":["total","auto_coded","auto_coded_pct","human_coded","human_coded_pct","uncategorized","uncategorized_pct","unreviewed"],"title":"TransactionsSection","description":"Who categorized the month's bank transactions."},"TrustRelativeBlock":{"properties":{"cohort":{"anyOf":[{"$ref":"#/components/schemas/CohortRef"},{"type":"null"}]},"auto_coded_share_percentile":{"$ref":"#/components/schemas/PercentileValue"},"close_days_percentile":{"$ref":"#/components/schemas/PercentileValue"}},"additionalProperties":false,"type":"object","required":["auto_coded_share_percentile","close_days_percentile"],"title":"TrustRelativeBlock","description":"Optional Trust Scorecard block: where two of its figures sit among peers.\n\nInformational only; the grade rubric does not read it."},"TrustScorecardHistoryItem":{"properties":{"month":{"type":"string","title":"Month"},"grade":{"type":"string","title":"Grade"},"provisional":{"type":"boolean","title":"Provisional"},"transactions":{"type":"integer","title":"Transactions"},"auto_coded_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Auto Coded Pct"},"reversal_rate_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Reversal Rate Pct"},"corrections":{"type":"integer","title":"Corrections"},"approvals_approved":{"type":"integer","title":"Approvals Approved"},"approvals_rejected":{"type":"integer","title":"Approvals Rejected"},"close_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Close Score"},"business_days_to_close":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Business Days To Close"},"anomalies_resolved":{"type":"integer","title":"Anomalies Resolved"},"provenance_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Provenance Pct"},"computed_at":{"type":"string","format":"date-time","title":"Computed At"}},"additionalProperties":false,"type":"object","required":["month","grade","provisional","transactions","auto_coded_pct","reversal_rate_pct","corrections","approvals_approved","approvals_rejected","close_score","business_days_to_close","anomalies_resolved","provenance_pct","computed_at"],"title":"TrustScorecardHistoryItem","description":"The headline numbers of one month, read from its stored snapshot."},"TrustScorecardResponse":{"properties":{"business_id":{"type":"string","title":"Business Id"},"month":{"type":"string","title":"Month","description":"YYYY-MM"},"period_start":{"type":"string","format":"date","title":"Period Start"},"period_end":{"type":"string","format":"date","title":"Period End"},"month_complete":{"type":"boolean","title":"Month Complete","description":"The month has ended"},"grade":{"type":"string","title":"Grade","description":"A, B, C or D: the lowest of the counted columns"},"provisional":{"type":"boolean","title":"Provisional","description":"The period is not closed yet; graded on the first two columns"},"grade_components":{"items":{"$ref":"#/components/schemas/GradeComponent"},"type":"array","title":"Grade Components"},"transactions":{"$ref":"#/components/schemas/TransactionsSection"},"automation":{"$ref":"#/components/schemas/AutomationSection"},"corrections":{"$ref":"#/components/schemas/CorrectionsSection"},"approvals":{"$ref":"#/components/schemas/ApprovalsSection"},"close":{"$ref":"#/components/schemas/CloseSection"},"anomalies":{"$ref":"#/components/schemas/AnomaliesSection"},"provenance":{"$ref":"#/components/schemas/ProvenanceSection"},"relative":{"anyOf":[{"$ref":"#/components/schemas/TrustRelativeBlock"},{"type":"null"}],"description":"Where the auto-coded share and the close days rank among peer businesses (Peer Benchmarks); informational, not part of the grade"},"computed_at":{"type":"string","format":"date-time","title":"Computed At"}},"additionalProperties":false,"type":"object","required":["business_id","month","period_start","period_end","month_complete","grade","provisional","grade_components","transactions","automation","corrections","approvals","close","anomalies","provenance","computed_at"],"title":"TrustScorecardResponse","description":"One business's scorecard for one calendar month."},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}