{"openapi":"3.1.0","info":{"title":"GET /api/v1/credit/scorecard-versions/{from_version_id}/diff/{to_version_id}","version":"1.0.0","description":"Compare two scorecard versions"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/credit/scorecard-versions/{from_version_id}/diff/{to_version_id}":{"get":{"tags":["credit"],"summary":"Compare two scorecard versions","description":"Criteria and manual checks added, removed or changed from the first version to the second, with before and after for each changed field, and whether grade bands or scoring differ. To see which businesses come out differently, run a backtest with `compare_version_id`.","operationId":"diff_scorecard_versions","parameters":[{"name":"from_version_id","in":"path","required":true,"schema":{"type":"string","title":"From Version Id"}},{"name":"to_version_id","in":"path","required":true,"schema":{"type":"string","title":"To Version Id"}},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_ScorecardDiffResponse_"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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"}}}},"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":"diff_scorecard_versions_api_v1_credit_scorecard_versions__from_version_id__diff__to_version_id__get"}}},"components":{"schemas":{"ScorecardDiffResponse":{"properties":{"from_version":{"$ref":"#/components/schemas/ScorecardVersionSummary"},"to_version":{"$ref":"#/components/schemas/ScorecardVersionSummary"},"criteria":{"items":{"$ref":"#/components/schemas/ScorecardDiffRow"},"type":"array","title":"Criteria"},"manual_checks":{"items":{"$ref":"#/components/schemas/ScorecardDiffRow"},"type":"array","title":"Manual Checks"},"grade_bands":{"$ref":"#/components/schemas/ScorecardDiffSection"},"scoring":{"$ref":"#/components/schemas/ScorecardDiffSection"},"summary":{"$ref":"#/components/schemas/ScorecardDiffSummary"}},"type":"object","required":["from_version","to_version","grade_bands","scoring","summary"],"title":"ScorecardDiffResponse","description":"What differs between two versions: `from_version` to `to_version`."},"ScorecardDiffRow":{"properties":{"change":{"type":"string","enum":["added","removed","changed","unchanged"],"title":"Change"},"id":{"type":"string","title":"Id"},"before":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Before"},"after":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"After"},"fields":{"items":{"$ref":"#/components/schemas/ScorecardFieldChange"},"type":"array","title":"Fields"},"moved":{"type":"boolean","title":"Moved","description":"Display order changed. Not a rule change.","default":false}},"type":"object","required":["change","id"],"title":"ScorecardDiffRow","description":"One criterion or manual check, compared across two versions."},"ScorecardDiffSection":{"properties":{"changed":{"type":"boolean","title":"Changed"},"before":{"title":"Before"},"after":{"title":"After"}},"type":"object","required":["changed"],"title":"ScorecardDiffSection"},"ScorecardDiffSummary":{"properties":{"criteria":{"$ref":"#/components/schemas/ScorecardDiffTally"},"manual_checks":{"$ref":"#/components/schemas/ScorecardDiffTally"},"identical":{"type":"boolean","title":"Identical"}},"type":"object","required":["criteria","manual_checks","identical"],"title":"ScorecardDiffSummary"},"ScorecardDiffTally":{"properties":{"added":{"type":"integer","title":"Added","default":0},"removed":{"type":"integer","title":"Removed","default":0},"changed":{"type":"integer","title":"Changed","default":0},"unchanged":{"type":"integer","title":"Unchanged","default":0}},"type":"object","title":"ScorecardDiffTally"},"ScorecardFieldChange":{"properties":{"field":{"type":"string","title":"Field"},"before":{"title":"Before"},"after":{"title":"After"}},"type":"object","required":["field"],"title":"ScorecardFieldChange"},"ScorecardVersionSummary":{"properties":{"id":{"type":"string","title":"Id"},"scorecard_id":{"type":"string","title":"Scorecard Id"},"version_number":{"type":"integer","title":"Version Number"},"status":{"type":"string","enum":["draft","validated","approved","active","retired"],"title":"Status"},"origin":{"type":"string","title":"Origin","description":"editor, migration (the program's criteria before versions), program_patch (set through PATCH /credit/programs), seed, or sandbox_copy (copied from the live business's active version onto its paired sandbox)."},"is_editable":{"type":"boolean","title":"Is Editable","description":"True while a draft; a version never changes once it is not.","default":false},"criteria_count":{"type":"integer","title":"Criteria Count","default":0},"manual_check_count":{"type":"integer","title":"Manual Check Count","default":0},"change_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Change Note"},"copied_from_version_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Copied From Version Id"},"created_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By","description":"Author, as recorded."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Updated At"},"validated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Validated At"},"valid":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Valid","description":"Result of the last validation. Null if never validated."},"approvals_recorded":{"type":"integer","title":"Approvals Recorded","default":0},"approvals_required":{"type":"integer","title":"Approvals Required","default":1},"approver_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Approver Name"},"approved_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Approved By","description":"The operator who recorded the final approval."},"approved_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Approved At"},"approval_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Approval Note"},"approval_attachment_s3_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Approval Attachment S3 Key"},"activated_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Activated By"},"activated_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Activated At"},"retired_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Retired At"}},"type":"object","required":["id","scorecard_id","version_number","status","origin"],"title":"ScorecardVersionSummary","description":"A version without its definition, for lists."},"SuccessEnvelope_ScorecardDiffResponse_":{"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/ScorecardDiffResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[ScorecardDiffResponse]"},"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":[]}]}