@model-match/api 3.19.0 → 3.20.0

package/openapi.json

@@ -215,7 +215,49 @@
                 "type": "string"
               },
               "emailEnabled": {
-                "$ref": "#/components/schemas/AlertEnabled"
+                "deprecated": true,
+                "description": "Deprecated and ignored: accepted for compatibility, but not stored and no longer controls delivery (the response always reports every flag off). Email and in-app channel preferences for alerts live in Notifications settings.",
+                "properties": {
+                  "agent_sale_closed": {
+                    "type": "boolean"
+                  },
+                  "area_new_listing": {
+                    "type": "boolean"
+                  },
+                  "borrower_listed": {
+                    "type": "boolean"
+                  },
+                  "epo_risk": {
+                    "type": "boolean"
+                  },
+                  "rate_term_refi_area": {
+                    "type": "boolean"
+                  },
+                  "watched_agent_pending": {
+                    "type": "boolean"
+                  },
+                  "watched_loan": {
+                    "type": "boolean"
+                  },
+                  "watched_property": {
+                    "type": "boolean"
+                  },
+                  "watched_sale": {
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "area_new_listing",
+                  "watched_agent_pending",
+                  "borrower_listed",
+                  "epo_risk",
+                  "agent_sale_closed",
+                  "rate_term_refi_area",
+                  "watched_sale",
+                  "watched_property",
+                  "watched_loan"
+                ],
+                "type": "object"
               },
               "enabled": {
                 "$ref": "#/components/schemas/AlertEnabled"
@@ -307,6 +349,9 @@
               },
               "userId": {
                 "type": "string"
+              },
+              "via": {
+                "$ref": "#/components/schemas/AdminAlertVia"
               }
             },
             "required": [
@@ -476,6 +521,40 @@
         ],
         "type": "object"
       },
+      "AdminAlertVia": {
+        "description": "Why the alert fired: the matched subject, the granting recipes and the match source. Absent on rows written before it existed.",
+        "properties": {
+          "matchSource": {
+            "description": "Which match source routed the alert: `subscriptions` for every alert fired since the legacy source was retired; `legacy` only on older rows.",
+            "enum": [
+              "legacy",
+              "subscriptions"
+            ],
+            "type": "string"
+          },
+          "parentKey": {
+            "description": "When the match went through a derived child (an auto agent, a borrower property, a manual agent's VRE), the owning subscription's subject key.",
+            "type": "string"
+          },
+          "recipeIds": {
+            "description": "The recipes whose grants enabled this alert type on the matched subscription (empty on alerts fired by the retired legacy match source).",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "subjectKey": {
+            "description": "The watched subject key the alert matched.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "subjectKey",
+          "recipeIds",
+          "matchSource"
+        ],
+        "type": "object"
+      },
       "AdminBulkJob": {
         "properties": {
           "bytes": {
@@ -1015,6 +1094,8 @@
             "type": "string"
           },
           "emailEnabled": {
+            "deprecated": true,
+            "description": "Deprecated and ignored: accepted for compatibility, but not stored and no longer controls delivery (the response always reports every flag off). Email and in-app channel preferences for alerts live in Notifications settings.",
             "properties": {
               "agent_sale_closed": {
                 "type": "boolean"
@@ -2518,7 +2599,49 @@
                 "$ref": "#/components/schemas/AlertConditions"
               },
               "emailEnabled": {
-                "$ref": "#/components/schemas/AlertEnabled"
+                "deprecated": true,
+                "description": "Deprecated and ignored: accepted for compatibility, but not stored and no longer controls delivery (the response always reports every flag off). Email and in-app channel preferences for alerts live in Notifications settings.",
+                "properties": {
+                  "agent_sale_closed": {
+                    "type": "boolean"
+                  },
+                  "area_new_listing": {
+                    "type": "boolean"
+                  },
+                  "borrower_listed": {
+                    "type": "boolean"
+                  },
+                  "epo_risk": {
+                    "type": "boolean"
+                  },
+                  "rate_term_refi_area": {
+                    "type": "boolean"
+                  },
+                  "watched_agent_pending": {
+                    "type": "boolean"
+                  },
+                  "watched_loan": {
+                    "type": "boolean"
+                  },
+                  "watched_property": {
+                    "type": "boolean"
+                  },
+                  "watched_sale": {
+                    "type": "boolean"
+                  }
+                },
+                "required": [
+                  "area_new_listing",
+                  "watched_agent_pending",
+                  "borrower_listed",
+                  "epo_risk",
+                  "agent_sale_closed",
+                  "rate_term_refi_area",
+                  "watched_sale",
+                  "watched_property",
+                  "watched_loan"
+                ],
+                "type": "object"
               },
               "enabled": {
                 "$ref": "#/components/schemas/AlertEnabled"
@@ -2824,16 +2947,246 @@
         ],
         "type": "object"
       },
-      "AlertsOkResponse": {
+      "AlertRecipe": {
+        "properties": {
+          "description": {
+            "type": "string"
+          },
+          "id": {
+            "enum": [
+              "past-clients",
+              "agent-partners",
+              "farm-area",
+              "watch-record"
+            ],
+            "type": "string"
+          },
+          "inputsSchema": {
+            "additionalProperties": {
+              "nullable": true
+            },
+            "description": "JSON Schema of the inputs the recipe needs to subscribe.",
+            "type": "object"
+          },
+          "label": {
+            "type": "string"
+          },
+          "subscribed": {
+            "description": "Whether you are subscribed: at least one of your subscriptions carries this recipe.",
+            "type": "boolean"
+          },
+          "types": {
+            "description": "The alert triggers this recipe turns on.",
+            "items": {
+              "enum": [
+                "area_new_listing",
+                "watched_agent_pending",
+                "borrower_listed",
+                "epo_risk",
+                "agent_sale_closed",
+                "rate_term_refi_area",
+                "watched_sale",
+                "watched_property",
+                "watched_loan"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "id",
+          "label",
+          "description",
+          "types",
+          "inputsSchema",
+          "subscribed"
+        ],
+        "type": "object"
+      },
+      "AlertRecipeInputs": {
+        "properties": {
+          "agents": {
+            "description": "`agent-partners`: the agents to follow.",
+            "items": {
+              "properties": {
+                "agentMmaId": {
+                  "description": "Agent id.",
+                  "minLength": 1,
+                  "type": "string"
+                }
+              },
+              "required": [
+                "agentMmaId"
+              ],
+              "type": "object"
+            },
+            "maxItems": 50,
+            "type": "array"
+          },
+          "areas": {
+            "description": "`farm-area`: areas to farm.",
+            "items": {
+              "$ref": "#/components/schemas/AddWatchedAreaRequest"
+            },
+            "maxItems": 25,
+            "type": "array"
+          },
+          "documentId": {
+            "description": "`watch-record`: the record id.",
+            "minLength": 1,
+            "type": "string"
+          },
+          "documentType": {
+            "description": "`watch-record`: the record type.",
+            "enum": [
+              "sale",
+              "property",
+              "loan"
+            ],
+            "example": "property",
+            "type": "string"
+          },
+          "nmlsId": {
+            "description": "`past-clients`: the loan officer's NMLS id.",
+            "type": "string"
+          },
+          "rules": {
+            "description": "`watch-record`: what change to watch for. Empty or omitted applies the default for the type — property: foreclosure status changes, or sale propensity reaches 50; sale: listing status changes; loan: interest rate moves by 0.125 points or more.",
+            "items": {
+              "properties": {
+                "match": {
+                  "description": "How predicates combine: all (AND, default) or any (OR).",
+                  "enum": [
+                    "all",
+                    "any"
+                  ],
+                  "example": "all",
+                  "type": "string"
+                },
+                "predicates": {
+                  "description": "One or more conditions; combined per match.",
+                  "items": {
+                    "properties": {
+                      "field": {
+                        "description": "Catalog field alias (e.g. avm, current_ltv, loan_type).",
+                        "example": "current_ltv",
+                        "type": "string"
+                      },
+                      "op": {
+                        "description": "Comparison / change / status / guard operator.",
+                        "enum": [
+                          "gt",
+                          "gte",
+                          "lt",
+                          "lte",
+                          "eq",
+                          "between",
+                          "pct_change_gte",
+                          "abs_change_gte",
+                          "changed",
+                          "changed_to"
+                        ],
+                        "example": "lte",
+                        "type": "string"
+                      },
+                      "stringValue": {
+                        "description": "Target keyword for changed_to / eq guard.",
+                        "type": "string"
+                      },
+                      "value": {
+                        "description": "Threshold, or change amount (percent for pct_change_gte).",
+                        "example": 0.8,
+                        "type": "number"
+                      },
+                      "value2": {
+                        "description": "Upper bound for between.",
+                        "type": "number"
+                      }
+                    },
+                    "required": [
+                      "field",
+                      "op"
+                    ],
+                    "type": "object"
+                  },
+                  "minItems": 1,
+                  "type": "array"
+                }
+              },
+              "required": [
+                "predicates"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          }
+        },
+        "type": "object"
+      },
+      "AlertRecipePreviewResponse": {
         "properties": {
           "data": {
             "properties": {
-              "ok": {
-                "type": "boolean"
+              "byType": {
+                "additionalProperties": {
+                  "type": "integer"
+                },
+                "description": "Count per alert trigger.",
+                "type": "object"
+              },
+              "count": {
+                "description": "Alerts the recipe would have fired in the window.",
+                "type": "integer"
+              },
+              "sample": {
+                "description": "The newest few, as digest lines.",
+                "items": {
+                  "properties": {
+                    "description": {
+                      "type": "string"
+                    },
+                    "title": {
+                      "type": "string"
+                    },
+                    "triggeredAt": {
+                      "type": "string"
+                    },
+                    "type": {
+                      "enum": [
+                        "area_new_listing",
+                        "watched_agent_pending",
+                        "borrower_listed",
+                        "epo_risk",
+                        "agent_sale_closed",
+                        "rate_term_refi_area",
+                        "watched_sale",
+                        "watched_property",
+                        "watched_loan"
+                      ],
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "type",
+                    "title",
+                    "description",
+                    "triggeredAt"
+                  ],
+                  "type": "object"
+                },
+                "type": "array"
+              },
+              "since": {
+                "description": "Window start (ISO).",
+                "type": "string"
               }
             },
             "required": [
-              "ok"
+              "count",
+              "byType",
+              "sample",
+              "since"
             ],
             "type": "object"
           }
@@ -2843,103 +3196,500 @@
         ],
         "type": "object"
       },
-      "AnalyticsCompleteness": {
-        "description": "Data-completeness watermark for this response. Present only when it could be measured; absence means it was not measured, NOT that the data is complete.",
+      "AlertRecipeResponse": {
         "properties": {
-          "through": {
-            "description": "The last calendar date (`YYYY-MM-DD`) this query's matching records actually reach. Records arrive after the events they describe, so a period ending today is normally backed by data ending days or weeks earlier, and any bucket extending past this date is built from a partial period. Measured from THIS query's own matched set, not a global figure: the delay varies by geography and moves over time, so two requests with different filters can legitimately report different dates.",
-            "format": "date",
-            "type": "string"
+          "data": {
+            "$ref": "#/components/schemas/AlertRecipe"
           }
         },
         "required": [
-          "through"
+          "data"
         ],
         "type": "object"
       },
-      "AndFilter": {
+      "AlertRecipesResponse": {
         "properties": {
-          "children": {
-            "description": "Array of filter expressions (AND)",
+          "data": {
             "items": {
-              "$ref": "#/components/schemas/FilterNode"
+              "$ref": "#/components/schemas/AlertRecipe"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "type": "object"
+      },
+      "AlertSubscription": {
+        "properties": {
+          "createdAt": {
+            "type": "string"
+          },
+          "display": {
+            "$ref": "#/components/schemas/AlertSubscriptionDisplay"
+          },
+          "expiresAt": {
+            "description": "When the subscription stops firing (ISO 8601).",
+            "type": "string"
+          },
+          "grants": {
+            "items": {
+              "$ref": "#/components/schemas/AlertSubscriptionGrant"
             },
             "type": "array"
           },
-          "type": {
+          "id": {
+            "description": "Opaque subscription id.",
+            "type": "string"
+          },
+          "kinds": {
+            "description": "The alert kinds that fire on this subject (empty = paused).",
+            "items": {
+              "enum": [
+                "area_new_listing",
+                "watched_agent_pending",
+                "borrower_listed",
+                "epo_risk",
+                "agent_sale_closed",
+                "rate_term_refi_area",
+                "watched_sale",
+                "watched_property",
+                "watched_loan"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "rules": {
+            "items": {
+              "$ref": "#/components/schemas/WatchedDocumentRule"
+            },
+            "type": "array"
+          },
+          "subjectType": {
             "enum": [
-              "and"
+              "agent",
+              "area",
+              "nmls",
+              "property",
+              "loan",
+              "sale",
+              "company",
+              "filter"
             ],
             "type": "string"
+          },
+          "updatedAt": {
+            "type": "string"
           }
         },
         "required": [
-          "type",
-          "children"
+          "id",
+          "subjectType",
+          "display",
+          "kinds",
+          "grants",
+          "createdAt",
+          "updatedAt"
         ],
         "type": "object"
       },
-      "BooleanFilterValue": {
-        "nullable": true,
-        "type": "boolean"
+      "AlertSubscriptionDisplay": {
+        "description": "What the subscription watches, for display.",
+        "properties": {
+          "agentMmaId": {
+            "type": "string"
+          },
+          "areaType": {
+            "enum": [
+              "city",
+              "county",
+              "zip",
+              "bbox",
+              "radius"
+            ],
+            "type": "string"
+          },
+          "documentId": {
+            "type": "string"
+          },
+          "documentType": {
+            "enum": [
+              "sale",
+              "property",
+              "loan"
+            ],
+            "type": "string"
+          },
+          "lat": {
+            "type": "number"
+          },
+          "lon": {
+            "type": "number"
+          },
+          "maxLat": {
+            "type": "number"
+          },
+          "maxLon": {
+            "type": "number"
+          },
+          "minLat": {
+            "type": "number"
+          },
+          "minLon": {
+            "type": "number"
+          },
+          "name": {
+            "type": "string"
+          },
+          "nmlsId": {
+            "type": "string"
+          },
+          "radiusMeters": {
+            "type": "number"
+          },
+          "state": {
+            "type": "string"
+          },
+          "value": {
+            "type": "string"
+          }
+        },
+        "type": "object"
       },
-      "BranchChartRequest": {
-        "additionalProperties": false,
+      "AlertSubscriptionError": {
         "properties": {
-          "advancedFilters": {
-            "$ref": "#/components/schemas/FilterNode"
+          "code": {
+            "description": "Machine-readable reason (absent on a generic validation error).",
+            "enum": [
+              "invalid_kind",
+              "kind_not_allowed_for_subject",
+              "subject_type_not_supported",
+              "rules_required",
+              "rule_edge_op_on_event_kind",
+              "unknown_field",
+              "invalid_rule",
+              "invalid_area",
+              "invalid_subject",
+              "invalid_subscription_id",
+              "nmls_mismatch"
+            ],
+            "type": "string"
           },
-          "filters": {
-            "$ref": "#/components/schemas/FilterNode"
+          "error": {
+            "description": "Error message",
+            "type": "string"
+          }
+        },
+        "required": [
+          "error"
+        ],
+        "type": "object"
+      },
+      "AlertSubscriptionGrant": {
+        "properties": {
+          "addedAt": {
+            "type": "string"
           },
-          "flatFilters": {
-            "additionalProperties": false,
+          "kinds": {
+            "items": {
+              "enum": [
+                "area_new_listing",
+                "watched_agent_pending",
+                "borrower_listed",
+                "epo_risk",
+                "agent_sale_closed",
+                "rate_term_refi_area",
+                "watched_sale",
+                "watched_property",
+                "watched_loan"
+              ],
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "recipeId": {
+            "description": "Why the kinds are on: a recipe, `custom` (set directly), or `migration`.",
+            "enum": [
+              "past-clients",
+              "agent-partners",
+              "farm-area",
+              "watch-record",
+              "custom",
+              "migration"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "recipeId",
+          "kinds",
+          "addedAt"
+        ],
+        "type": "object"
+      },
+      "AlertSubscriptionResponse": {
+        "properties": {
+          "data": {
+            "$ref": "#/components/schemas/AlertSubscription"
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "type": "object"
+      },
+      "AlertSubscriptionSubject": {
+        "properties": {
+          "agentMmaId": {
+            "description": "agent: the agent id.",
+            "minLength": 1,
+            "type": "string"
+          },
+          "area": {
+            "description": "Area subject: the same body as POST /watched-areas.",
             "properties": {
-              "borrowerStatus": {
-                "$ref": "#/components/schemas/LoanBorrowerStatusFilterValue"
+              "lat": {
+                "description": "Center latitude (point + radius).",
+                "maximum": 90,
+                "minimum": -90,
+                "type": "number"
               },
-              "broker": {
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/TextFilterValue"
-                  },
-                  {
-                    "description": "Broker shop NMLS id (digits only). A broker is a company — resolve a broker name to its NMLS id via instantSearch (or listCompanies)."
-                  }
-                ]
+              "lon": {
+                "description": "Center longitude.",
+                "maximum": 180,
+                "minimum": -180,
+                "type": "number"
               },
-              "buyerEntityType": {
-                "$ref": "#/components/schemas/BooleanFilterValue"
+              "maxLat": {
+                "description": "Box north edge.",
+                "maximum": 90,
+                "minimum": -90,
+                "type": "number"
               },
-              "city": {
-                "$ref": "#/components/schemas/TextFilterValue"
+              "maxLon": {
+                "description": "Box east edge.",
+                "maximum": 180,
+                "minimum": -180,
+                "type": "number"
               },
-              "conforming": {
-                "$ref": "#/components/schemas/BooleanFilterValue"
+              "minLat": {
+                "description": "Box south edge.",
+                "maximum": 90,
+                "minimum": -90,
+                "type": "number"
               },
-              "county": {
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/TextFilterValue"
-                  },
-                  {
-                    "description": "County name (e.g. \"Broward\") or 5-digit FIPS code. Names resolve to FIPS server-side; include a `state` filter to disambiguate."
-                  }
-                ]
+              "minLon": {
+                "description": "Box west edge.",
+                "maximum": 180,
+                "minimum": -180,
+                "type": "number"
               },
-              "currentBalance": {
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/NumericFilterValue"
-                  },
-                  {
-                    "description": "Estimated remaining principal balance (~19% populated). Approximate current equity as `homeValue` (AVM) minus this."
-                  }
-                ]
+              "radius": {
+                "description": "Radius around the center point.",
+                "example": 10,
+                "exclusiveMinimum": true,
+                "minimum": 0,
+                "type": "number"
               },
-              "employer": {
-                "allOf": [
-                  {
+              "state": {
+                "description": "2-letter state. Ignored for zip + geo areas.",
+                "example": "CA",
+                "type": "string"
+              },
+              "type": {
+                "description": "Named area (city/county/zip) or geo area (bbox = bounding box, radius = point + radius).",
+                "enum": [
+                  "city",
+                  "county",
+                  "zip",
+                  "bbox",
+                  "radius"
+                ],
+                "type": "string"
+              },
+              "unit": {
+                "description": "Radius unit (default mi).",
+                "enum": [
+                  "mi",
+                  "km",
+                  "m"
+                ],
+                "example": "mi",
+                "type": "string"
+              },
+              "value": {
+                "description": "City / county name, or 5-digit zip. Required for named areas.",
+                "example": "Los Angeles",
+                "type": "string"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "type": "object"
+          },
+          "documentId": {
+            "description": "sale / property / loan: the record id.",
+            "minLength": 1,
+            "type": "string"
+          },
+          "nmlsId": {
+            "description": "nmls: your NMLS id.",
+            "minLength": 1,
+            "type": "string"
+          },
+          "type": {
+            "description": "agent, area, nmls (your own NMLS id), sale, property or loan. company and filter are reserved.",
+            "enum": [
+              "agent",
+              "area",
+              "nmls",
+              "property",
+              "loan",
+              "sale",
+              "company",
+              "filter"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "type": "object"
+      },
+      "AlertSubscriptionsResponse": {
+        "properties": {
+          "data": {
+            "items": {
+              "$ref": "#/components/schemas/AlertSubscription"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "type": "object"
+      },
+      "AlertsOkResponse": {
+        "properties": {
+          "data": {
+            "properties": {
+              "ok": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "ok"
+            ],
+            "type": "object"
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "type": "object"
+      },
+      "AnalyticsCompleteness": {
+        "description": "Data-completeness watermark for this response. Present only when it could be measured; absence means it was not measured, NOT that the data is complete.",
+        "properties": {
+          "through": {
+            "description": "The last calendar date (`YYYY-MM-DD`) this query's matching records actually reach. Records arrive after the events they describe, so a period ending today is normally backed by data ending days or weeks earlier, and any bucket extending past this date is built from a partial period. Measured from THIS query's own matched set, not a global figure: the delay varies by geography and moves over time, so two requests with different filters can legitimately report different dates.",
+            "format": "date",
+            "type": "string"
+          }
+        },
+        "required": [
+          "through"
+        ],
+        "type": "object"
+      },
+      "AndFilter": {
+        "properties": {
+          "children": {
+            "description": "Array of filter expressions (AND)",
+            "items": {
+              "$ref": "#/components/schemas/FilterNode"
+            },
+            "type": "array"
+          },
+          "type": {
+            "enum": [
+              "and"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "type",
+          "children"
+        ],
+        "type": "object"
+      },
+      "BooleanFilterValue": {
+        "nullable": true,
+        "type": "boolean"
+      },
+      "BranchChartRequest": {
+        "additionalProperties": false,
+        "properties": {
+          "advancedFilters": {
+            "$ref": "#/components/schemas/FilterNode"
+          },
+          "filters": {
+            "$ref": "#/components/schemas/FilterNode"
+          },
+          "flatFilters": {
+            "additionalProperties": false,
+            "properties": {
+              "borrowerStatus": {
+                "$ref": "#/components/schemas/LoanBorrowerStatusFilterValue"
+              },
+              "broker": {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/TextFilterValue"
+                  },
+                  {
+                    "description": "Broker shop NMLS id (digits only). A broker is a company — resolve a broker name to its NMLS id via instantSearch (or listCompanies)."
+                  }
+                ]
+              },
+              "buyerEntityType": {
+                "$ref": "#/components/schemas/BooleanFilterValue"
+              },
+              "city": {
+                "$ref": "#/components/schemas/TextFilterValue"
+              },
+              "conforming": {
+                "$ref": "#/components/schemas/BooleanFilterValue"
+              },
+              "county": {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/TextFilterValue"
+                  },
+                  {
+                    "description": "County name (e.g. \"Broward\") or 5-digit FIPS code. Names resolve to FIPS server-side; include a `state` filter to disambiguate."
+                  }
+                ]
+              },
+              "currentBalance": {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/NumericFilterValue"
+                  },
+                  {
+                    "description": "Estimated remaining principal balance (~19% populated). Approximate current equity as `homeValue` (AVM) minus this."
+                  }
+                ]
+              },
+              "employer": {
+                "allOf": [
+                  {
                     "$ref": "#/components/schemas/TextFilterValue"
                   },
                   {
@@ -10578,6 +11328,100 @@
         ],
         "type": "object"
       },
+      "CreateAlertSubscriptionRequest": {
+        "properties": {
+          "expiresAt": {
+            "description": "Stop firing after this instant (ISO 8601).",
+            "format": "date-time",
+            "type": "string"
+          },
+          "kinds": {
+            "description": "The alert kinds to turn on for this subject (replaces kinds set directly before; kinds granted by a recipe stay). Empty = paused.",
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "rules": {
+            "description": "Rules (required for sale / property / loan subjects; same shape as POST /watched-documents).",
+            "items": {
+              "properties": {
+                "match": {
+                  "description": "How predicates combine: all (AND, default) or any (OR).",
+                  "enum": [
+                    "all",
+                    "any"
+                  ],
+                  "example": "all",
+                  "type": "string"
+                },
+                "predicates": {
+                  "description": "One or more conditions; combined per match.",
+                  "items": {
+                    "properties": {
+                      "field": {
+                        "description": "Catalog field alias (e.g. avm, current_ltv, loan_type).",
+                        "example": "current_ltv",
+                        "type": "string"
+                      },
+                      "op": {
+                        "description": "Comparison / change / status / guard operator.",
+                        "enum": [
+                          "gt",
+                          "gte",
+                          "lt",
+                          "lte",
+                          "eq",
+                          "between",
+                          "pct_change_gte",
+                          "abs_change_gte",
+                          "changed",
+                          "changed_to"
+                        ],
+                        "example": "lte",
+                        "type": "string"
+                      },
+                      "stringValue": {
+                        "description": "Target keyword for changed_to / eq guard.",
+                        "type": "string"
+                      },
+                      "value": {
+                        "description": "Threshold, or change amount (percent for pct_change_gte).",
+                        "example": 0.8,
+                        "type": "number"
+                      },
+                      "value2": {
+                        "description": "Upper bound for between.",
+                        "type": "number"
+                      }
+                    },
+                    "required": [
+                      "field",
+                      "op"
+                    ],
+                    "type": "object"
+                  },
+                  "minItems": 1,
+                  "type": "array"
+                }
+              },
+              "required": [
+                "predicates"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "subject": {
+            "$ref": "#/components/schemas/AlertSubscriptionSubject"
+          }
+        },
+        "required": [
+          "subject",
+          "kinds"
+        ],
+        "type": "object"
+      },
       "CreateSavedFilterRequest": {
         "additionalProperties": false,
         "properties": {
@@ -25799,12 +26643,18 @@
           "lenderMatchMode": {
             "$ref": "#/components/schemas/LenderMatchMode"
           },
+          "officeGeoPoint": {
+            "$ref": "#/components/schemas/OriginatorOfficeGeoPoint"
+          },
           "pagination": {
             "$ref": "#/components/schemas/Pagination"
           },
           "period": {
             "$ref": "#/components/schemas/Period"
           },
+          "productMix": {
+            "$ref": "#/components/schemas/OriginatorProductMixFilter"
+          },
           "sort": {
             "items": {
               "properties": {
@@ -25826,7 +26676,9 @@
                     "officeState",
                     "officeCity",
                     "licensedSinceDate",
-                    "lastTransactionDate"
+                    "lastTransactionDate",
+                    "purchaseShare",
+                    "refinanceShare"
                   ],
                   "type": "string"
                 },
@@ -26470,6 +27322,114 @@
         ],
         "type": "object"
       },
+      "OriginatorOfficeGeoPoint": {
+        "additionalProperties": false,
+        "description": "Originators whose NMLS-registered OFFICE is within `radiusMiles` of an anchor — the radius form of `officeState` / `officeCity` / `officeZip`, NOT production geography (that is `state` / `city` / `county` / `zip` / `footprint`). Anchor on a coordinate (`{lat, lon, radiusMiles}`) or on another originator's office (`{nmlsId: \"7206\", radiusMiles: 25}` — 'LOs near this LO'; that originator is excluded). Originators with no geocoded office never match. 400 when neither anchor form is complete or both are given; 404 `office_geo_anchor_not_found` for an unknown `nmlsId`; 400 `office_geo_anchor_unlocated` when that originator has no geocoded office.",
+        "properties": {
+          "lat": {
+            "description": "Anchor latitude; pair with `lon`.",
+            "example": 33.4484,
+            "maximum": 90,
+            "minimum": -90,
+            "type": "number"
+          },
+          "lon": {
+            "description": "Anchor longitude; pair with `lat`.",
+            "example": -112.074,
+            "maximum": 180,
+            "minimum": -180,
+            "type": "number"
+          },
+          "nmlsId": {
+            "description": "Anchor on another originator's office instead: their NMLS id (resolved server-side; they are excluded from the result). Exclusive with `lat`/`lon`.",
+            "example": "7206",
+            "minLength": 1,
+            "type": "string"
+          },
+          "radiusMiles": {
+            "description": "Radius in miles, > 0 and ≤ 1000.",
+            "example": 50,
+            "exclusiveMinimum": true,
+            "maximum": 1000,
+            "minimum": 0,
+            "type": "number"
+          }
+        },
+        "required": [
+          "radiusMiles"
+        ],
+        "type": "object"
+      },
+      "OriginatorProductMixEntry": {
+        "additionalProperties": false,
+        "properties": {
+          "basis": {
+            "description": "`volume` (default — what the row's `fhaPct` / `vaPct` / `conventionalPct` report) or `units` (loan count).",
+            "enum": [
+              "volume",
+              "units"
+            ],
+            "type": "string"
+          },
+          "maxShare": {
+            "description": "Upper bound, 0–100 percent. An originator who wrote none of the product has a 0% share and passes.",
+            "example": 60,
+            "maximum": 100,
+            "minimum": 0,
+            "type": "number"
+          },
+          "minShare": {
+            "description": "Lower bound on the product's share of the period book, 0–100 percent.",
+            "example": 25,
+            "maximum": 100,
+            "minimum": 0,
+            "type": "number"
+          },
+          "product": {
+            "description": "Loan product (case-insensitive).",
+            "enum": [
+              "conventional",
+              "fha",
+              "va",
+              "he",
+              "heloc",
+              "building",
+              "commercial",
+              "stand_alone_refi",
+              "closed_end",
+              "reverse",
+              "usda",
+              "stand_alone_second",
+              "aggregate",
+              "seller_take_back",
+              "sba_participation_trust_deed",
+              "balloon",
+              "opened_end",
+              "assumption",
+              "negative_amortization",
+              "land_contract",
+              "trade",
+              "modification",
+              "unknown"
+            ],
+            "example": "fha",
+            "type": "string"
+          }
+        },
+        "required": [
+          "product"
+        ],
+        "type": "object"
+      },
+      "OriginatorProductMixFilter": {
+        "description": "Whole-book product-share bands for the selected period, ANDed: `[{product: \"fha\", minShare: 30}, {product: \"va\", maxShare: 10}]` = FHA is at least 30% of their period volume AND VA at most 10%. Shares are 0–100 percents of TOTAL period production across all markets (not scoped by any geography filter), the same per-product figures the row reports as `fhaPct` / `vaPct` / `conventionalPct`. No bucket for a product = 0% (fails any `minShare` > 0, passes any `maxShare`). Pair with `units: {gte: N}` so a 100% share off two loans does not read as a specialty.",
+        "items": {
+          "$ref": "#/components/schemas/OriginatorProductMixEntry"
+        },
+        "maxItems": 10,
+        "minItems": 1,
+        "type": "array"
+      },
       "OriginatorProfileInsights": {
         "description": "Profile read-outs computed server-side from the LO's production in the requested `period` (default `last12Months`) — the same `volume` / `units` this response reports. Labels and descriptions are display copy; branch on the enum fields.",
         "properties": {
@@ -26845,6 +27805,12 @@
             "nullable": true,
             "type": "number"
           },
+          "purchaseShare": {
+            "description": "Purchase loans as a 0–100 percent of the originator's period loan COUNT — the value `sort: [{field: \"purchaseShare\"}]` orders by. `null` when the originator wrote no purchase loans in the period (sorts as 0).",
+            "example": 72.5,
+            "nullable": true,
+            "type": "number"
+          },
           "purchaseUnits": {
             "nullable": true,
             "type": "number"
@@ -26853,6 +27819,12 @@
             "nullable": true,
             "type": "number"
           },
+          "refinanceShare": {
+            "description": "Refinance loans as a 0–100 percent of the originator's period loan COUNT — the value `sort: [{field: \"refinanceShare\"}]` orders by. `null` when none (sorts as 0).",
+            "example": 18.2,
+            "nullable": true,
+            "type": "number"
+          },
           "refinanceUnits": {
             "nullable": true,
             "type": "number"
@@ -32376,7 +33348,8 @@
             "type": "string"
           },
           "emailEnabled": {
-            "description": "Per-trigger email opt-ins to change (others keep their value). Off by default — turn one on to also receive an email when it fires.",
+            "deprecated": true,
+            "description": "Deprecated and ignored: accepted for compatibility, but not stored and no longer controls delivery (the response always reports every flag off). Email and in-app channel preferences for alerts live in Notifications settings.",
             "properties": {
               "agent_sale_closed": {
                 "type": "boolean"
@@ -32409,7 +33382,8 @@
             "type": "object"
           },
           "enabled": {
-            "description": "Per-trigger on/off flags to change (others keep their value).",
+            "deprecated": true,
+            "description": "Deprecated: use the alert recipes (POST/DELETE /recipes/{id}) or /subscriptions instead. Still honoured: `true` turns the trigger on for every watched subject that supports it (and for your NMLS id when one is on file); `false` turns it off everywhere. Omitted triggers are unchanged. A trigger with nothing watched that supports it stays off.",
             "properties": {
               "agent_sale_closed": {
                 "type": "boolean"
@@ -32767,7 +33741,7 @@
   "info": {
     "description": "ModelMatch API — mortgage and real-estate market data.\n\n## Bulk delivery limits\n\nThe `POST /{entity}/bulk-delivery` endpoints export a full result set to\nS3 as NDJSON, JSON, CSV, or Parquet.\n\n- **Up to 5,000 rows per delivery: no entitlement required.** Available to\n  every authenticated caller.\n- **Above 5,000 rows: requires the entity's `bulk-delivery.{entity}`\n  entitlement** (e.g. `bulk-delivery.loans`). The grant's scope sets your\n  row ceiling and may also restrict which rows and fields you receive.\n\nA delivery that would exceed the limit available to you is rejected with\n`403 entitlement_missing`, reporting the matched row count and the ceiling\nthat applied. To stay under the limit, pass `limit` — the job then delivers\n(and bills for) only the first `limit` rows of a broader query.\n\n**Need a higher limit?** Email support@modelmatch.com to request the\nentitlement. Limits are raised per organization and per entity.\n\nBulk delivery is billed at 1 credit per delivered row whether or not\nan entitlement is held.\n\nInstead of a download, a delivery can be sent to a push target configured\non your workspace: pass `destination: { type: \"push-target\", targetId }`.\nThe same limits and billing apply.",
     "title": "ModelMatch API",
-    "version": "3.67.0"
+    "version": "3.68.0"
   },
   "openapi": "3.1.0",
   "paths": {
@@ -33205,20 +34179,739 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Configurable chart (measure × slice) over the agent's sales",
+        "summary": "Configurable chart (measure × slice) over the agent's sales",
+        "tags": [
+          "Agents"
+        ]
+      }
+    },
+    "/v1/agents/analytics/summary": {
+      "post": {
+        "operationId": "agentAnalyticsSummary",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AgentSummaryRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SidedSummaryResponse"
+                }
+              }
+            },
+            "description": "Sided summary with previous-period comparison"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Validation error"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Unauthorized"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Forbidden (authenticated, but missing required context — e.g. no active organization)"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Not found"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PayloadTooLarge"
+                }
+              }
+            },
+            "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
+          }
+        },
+        "summary": "Production summary with buyer/seller/dual split + previous period",
+        "tags": [
+          "Agents"
+        ]
+      }
+    },
+    "/v1/agents/analytics/time-series": {
+      "post": {
+        "operationId": "agentAnalyticsTimeSeries",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AgentTimeSeriesRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SidedTimeSeriesResponse"
+                }
+              }
+            },
+            "description": "Time-series with side splits + previous period"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Validation error"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Unauthorized"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Forbidden (authenticated, but missing required context — e.g. no active organization)"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Not found"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PayloadTooLarge"
+                }
+              }
+            },
+            "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
+          }
+        },
+        "summary": "Agent volume/units over time with buyer/seller/dual split",
+        "tags": [
+          "Agents"
+        ]
+      }
+    },
+    "/v1/agents/bulk-delivery": {
+      "post": {
+        "description": "Queues an ECS task that dumps every matching agents document to S3 in the requested format. Returns 202 with a jobId; poll `GET /v1/agents/bulk-delivery/{jobId}` for status + the signed download URL.\n\n**Row limit.** Deliveries of up to 5,000 rows need no entitlement. Above that, the org's `bulk-delivery.agents` entitlement is required and its scope (row ceiling, row filters, allowed fields) governs the delivery; without it the request is rejected with 403 `entitlement_missing`. Pass `limit` at or below the ceiling to deliver a capped subset of a broader query. Email support@modelmatch.com to request a limit increase.\n\nDelivery is billed at 1 credit per row regardless of entitlement.\n\n**Push-target destination.** Pass `destination: { type: \"push-target\", targetId }` to have the finished rows sent to a configured push target instead of downloaded. The target is checked before anything is queued; a refusal returns the push target's status and `code` (`TARGET_NOT_FOUND` 404, `FORBIDDEN` 403, `PLAN_REQUIRED` 402, `TARGET_DISABLED` 409, `ENTITY_MISMATCH` 400). Limits and billing are the same as a file delivery, except that push-target deliveries from the ModelMatch web app are not billed.",
+        "operationId": "submitAgentsBulkDelivery",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/AgentListRequest"
+                  },
+                  {
+                    "additionalProperties": false,
+                    "properties": {
+                      "destination": {
+                        "$ref": "#/components/schemas/BulkDeliveryDestination"
+                      },
+                      "fields": {
+                        "description": "Optional output column projection, named by the response DTO fields (the same camelCase fields the list endpoint returns, e.g. `city`, `interestRate`). Intersected with the entitlement scope's allowedFields and the entity's full column set. If empty after intersection, falls back to all columns. It also SELECTS the opt-in columns, which are not part of the list DTO and are never delivered unless named here: `communityLending` (properties, originators, companies, branches) — the Community Lending neighborhood profile, identical to the block on the entity's detail endpoint; `parties` (properties) — the mortgage parties attributed to the parcel, by attribution scope; and `marketCount` / `countyCount` / `stateCount` / `zipCount` / `lenderCount` (originators) — the market-breadth rollups you can already filter on. In `csv` and `parquet` the two block columns are JSON-encoded cells; in `json` and `ndjson` they are nested objects. Windowed production (originators, agents, companies, branches): name `<field>_<n>mo` for n in 3, 6, 12, 14, 18, 24 to get a production field for that trailing window regardless of `period` — e.g. `volume_3mo`, `units_6mo`, `purchaseVolume_24mo`. Available for originators `volume`, `units`, `avgLoanAmount`, `purchaseVolume`, `purchaseUnits`, `refinanceVolume`, `refinanceUnits`, `conventionalPct`, `fhaPct`, `vaPct`; agents `volume`, `units`, `avgSoldPrice`, `buyerVolume`, `buyerUnits`, `sellerVolume`, `sellerUnits`, `totalOriginatorsWorkedWith`, `totalCompaniesWorkedWith`, `totalLendersWorkedWith`; companies `volume`, `units`, `avgLoanAmount`, `loCount`; branches `volume`, `units`, `avgLoanAmount`, `purchasePct`, `refinancePct`, `loCount`. Numbers (null when the window has no data); an entitlement that allows a field allows every window of it.",
+                        "items": {
+                          "minLength": 1,
+                          "type": "string"
+                        },
+                        "type": "array"
+                      },
+                      "format": {
+                        "$ref": "#/components/schemas/BulkDeliveryFormat"
+                      },
+                      "limit": {
+                        "description": "Optional hard cap on the number of rows delivered — and therefore billed (1 credit / row). The job delivers the first `limit` rows in sort order (default newest-first) and bills only for those. If the query matches fewer than `limit`, all matches are delivered. Distinct from the page-size `size` field, which is ignored on this endpoint. The row ceiling still applies — 5,000 without the entity's bulk-delivery entitlement, or the entitlement's `maxRows` with it. A `limit` above the ceiling is rejected, but a `limit` at or below it lets you export a capped top-N even when the full match exceeds the ceiling — which is the intended way to run a broad query under the 5,000-row allowance.",
+                        "example": 5000,
+                        "exclusiveMinimum": true,
+                        "minimum": 0,
+                        "type": "integer"
+                      }
+                    },
+                    "type": "object"
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BulkDeliverySubmitResponse"
+                }
+              }
+            },
+            "description": "Job queued; ECS task launched"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "$ref": "#/components/schemas/BulkDeliveryPreflightExceeded"
+                    },
+                    {
+                      "$ref": "#/components/schemas/BulkDeliveryPushTargetError"
+                    }
+                  ]
+                }
+              }
+            },
+            "description": "Validation failure (incl. `format_required`: a file delivery needs `format`), delivery would exceed the entitlement's maxRows, OR the push target does not accept this entity (`ENTITY_MISMATCH`)"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Authentication required"
+          },
+          "402": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/BulkDeliveryInsufficientCredits"
+                    },
+                    {
+                      "$ref": "#/components/schemas/BulkDeliveryPushTargetError"
+                    }
+                  ]
+                }
+              }
+            },
+            "description": "Insufficient credits (balance < estimatedTotal, at 1 credit per row), OR the plan does not include push targets (`PLAN_REQUIRED`)"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "anyOf": [
+                    {
+                      "$ref": "#/components/schemas/BulkDeliveryForbidden"
+                    },
+                    {
+                      "$ref": "#/components/schemas/BulkDeliveryPushTargetError"
+                    },
+                    {
+                      "$ref": "#/components/schemas/BulkDeliveryInsufficientScope"
+                    }
+                  ]
+                }
+              }
+            },
+            "description": "Delivery exceeds the 5,000-row limit available without the `bulk-delivery.agents` entitlement (lower `limit`, narrow the filters, or contact support for a limit increase), OR you may not use the push target (`FORBIDDEN`), OR a scoped token named a push-target destination without `push-targets:send` (`insufficient_scope`)."
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BulkDeliveryPushTargetError"
+                }
+              }
+            },
+            "description": "Push target not found (`TARGET_NOT_FOUND`)"
+          },
+          "409": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BulkDeliveryPushTargetError"
+                }
+              }
+            },
+            "description": "Push target is disabled (`TARGET_DISABLED`)"
+          },
+          "502": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Preflight / S3 / DDB / ECS launch failure, or the push-target check could not reach the auth server"
+          }
+        },
+        "summary": "Submit a bulk-delivery job for agents",
+        "tags": [
+          "Agents"
+        ]
+      }
+    },
+    "/v1/agents/bulk-delivery/{jobId}": {
+      "delete": {
+        "description": "Cancels a queued or running agents delivery job.\n\nThe job is marked `cancelled` immediately; the container running it notices on its next page boundary and stops. Because a delivery is billed once, at the end, **a cancelled job is never charged** — no credits are debited and there is nothing to refund. No partial file is written.\n\nIdempotent-ish: cancelling a job that has already finished (or was already cancelled) returns 409 and changes nothing. Poll `GET /v1/agents/bulk-delivery/{jobId}` for the settled state.",
+        "operationId": "cancelAgentsBulkDeliveryJob",
+        "parameters": [
+          {
+            "description": "Job ID returned by `POST /v1/agents/bulk-delivery`",
+            "in": "path",
+            "name": "jobId",
+            "required": true,
+            "schema": {
+              "description": "Job ID returned by `POST /v1/agents/bulk-delivery`",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BulkDeliveryStatusResponse"
+                }
+              }
+            },
+            "description": "Job cancelled; body is its settled status"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Authentication required"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Caller does not own this job"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Job not found (or expired past 30d TTL)"
+          },
+          "409": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Job already finished — nothing to cancel"
+          }
+        },
+        "summary": "Cancel a bulk-delivery job for agents",
+        "tags": [
+          "Agents"
+        ]
+      },
+      "get": {
+        "operationId": "getAgentsBulkDeliveryJob",
+        "parameters": [
+          {
+            "description": "Job ID returned by `POST /v1/agents/bulk-delivery`",
+            "in": "path",
+            "name": "jobId",
+            "required": true,
+            "schema": {
+              "description": "Job ID returned by `POST /v1/agents/bulk-delivery`",
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BulkDeliveryStatusResponse"
+                }
+              }
+            },
+            "description": "Job status (resultsUrl re-signed if completed)"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Authentication required"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Caller does not own this job"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Job not found (or expired past 30d TTL)"
+          }
+        },
+        "summary": "Get bulk-delivery job status for agents",
+        "tags": [
+          "Agents"
+        ]
+      }
+    },
+    "/v1/agents/count": {
+      "post": {
+        "description": "Return the exact number of agents matching the given filters. Accepts the same request body as `listAgents` (pagination and sort are ignored). Use this when you only need a total; to get the matching agents themselves, send the same request body to `listAgents`.",
+        "operationId": "countAgents",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AgentListRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CountResponse"
+                }
+              }
+            },
+            "description": "Exact count of matching agents"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Validation error"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Unauthorized"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Forbidden (authenticated, but missing required context — e.g. no active organization)"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Not found"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PayloadTooLarge"
+                }
+              }
+            },
+            "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
+          },
+          "503": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Location dictionary temporarily unavailable. Only returned for a NEGATED location filter (`neq`, or `not`), which cannot be honoured without resolving the excluded value — answering anyway would return the records you asked to exclude. Positive location filters are unaffected. Retry shortly; the filter value itself was not rejected."
+          }
+        },
+        "summary": "Count agents matching filters",
+        "tags": [
+          "Agents"
+        ],
+        "x-mm-records-via": "listAgents"
+      }
+    },
+    "/v1/agents/{id}": {
+      "get": {
+        "operationId": "getAgent",
+        "parameters": [
+          {
+            "description": "Agent document ID",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "description": "Agent document ID",
+              "type": "string"
+            }
+          },
+          {
+            "description": "Period for volume/units (default: last12Months)",
+            "in": "query",
+            "name": "period",
+            "required": false,
+            "schema": {
+              "allOf": [
+                {
+                  "$ref": "#/components/schemas/Period"
+                },
+                {
+                  "description": "Period for volume/units (default: last12Months)"
+                }
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AgentDetailResponse"
+                }
+              }
+            },
+            "description": "Agent detail"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Agent not found"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PayloadTooLarge"
+                }
+              }
+            },
+            "description": "Response payload too large"
+          }
+        },
+        "summary": "Get agent by ID",
+        "tags": [
+          "Agents"
+        ]
+      }
+    },
+    "/v1/agents/{id}/breakdowns/cities": {
+      "post": {
+        "operationId": "agentCities",
+        "parameters": [
+          {
+            "description": "Agent document ID",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "description": "Agent document ID",
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BreakdownRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BreakdownResponse"
+                }
+              }
+            },
+            "description": "Breakdown of the agent's sales by cities"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Validation error"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Unauthorized"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Forbidden (authenticated, but missing required context — e.g. no active organization)"
+          },
+          "404": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Not found"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PayloadTooLarge"
+                }
+              }
+            },
+            "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
+          }
+        },
+        "summary": "City volume breakdown across the agent's sales",
         "tags": [
           "Agents"
         ]
       }
     },
-    "/v1/agents/analytics/summary": {
+    "/v1/agents/{id}/breakdowns/companies": {
       "post": {
-        "operationId": "agentAnalyticsSummary",
+        "operationId": "agentCompanies",
+        "parameters": [
+          {
+            "description": "Agent document ID",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "description": "Agent document ID",
+              "type": "string"
+            }
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/AgentSummaryRequest"
+                "$ref": "#/components/schemas/ScoredBreakdownRequest"
               }
             }
           }
@@ -33228,11 +34921,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/SidedSummaryResponse"
+                  "$ref": "#/components/schemas/BreakdownResponse"
                 }
               }
             },
-            "description": "Sided summary with previous-period comparison"
+            "description": "Pre-aggregated companies breakdown from the agent's scored doc"
           },
           "400": {
             "content": {
@@ -33285,20 +34978,32 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Production summary with buyer/seller/dual split + previous period",
+        "summary": "Mortgage companies the agent dealt with (pre-aggregated)",
         "tags": [
           "Agents"
         ]
       }
     },
-    "/v1/agents/analytics/time-series": {
+    "/v1/agents/{id}/breakdowns/counties": {
       "post": {
-        "operationId": "agentAnalyticsTimeSeries",
+        "operationId": "agentCounties",
+        "parameters": [
+          {
+            "description": "Agent document ID",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "description": "Agent document ID",
+              "type": "string"
+            }
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/AgentTimeSeriesRequest"
+                "$ref": "#/components/schemas/BreakdownRequest"
               }
             }
           }
@@ -33308,11 +35013,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/SidedTimeSeriesResponse"
+                  "$ref": "#/components/schemas/BreakdownResponse"
                 }
               }
             },
-            "description": "Time-series with side splits + previous period"
+            "description": "Breakdown of the agent's sales by counties"
           },
           "400": {
             "content": {
@@ -33365,86 +35070,56 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Agent volume/units over time with buyer/seller/dual split",
+        "summary": "County (FIPS) volume breakdown",
         "tags": [
           "Agents"
         ]
       }
     },
-    "/v1/agents/bulk-delivery": {
+    "/v1/agents/{id}/breakdowns/lenders": {
       "post": {
-        "description": "Queues an ECS task that dumps every matching agents document to S3 in the requested format. Returns 202 with a jobId; poll `GET /v1/agents/bulk-delivery/{jobId}` for status + the signed download URL.\n\n**Row limit.** Deliveries of up to 5,000 rows need no entitlement. Above that, the org's `bulk-delivery.agents` entitlement is required and its scope (row ceiling, row filters, allowed fields) governs the delivery; without it the request is rejected with 403 `entitlement_missing`. Pass `limit` at or below the ceiling to deliver a capped subset of a broader query. Email support@modelmatch.com to request a limit increase.\n\nDelivery is billed at 1 credit per row regardless of entitlement.\n\n**Push-target destination.** Pass `destination: { type: \"push-target\", targetId }` to have the finished rows sent to a configured push target instead of downloaded. The target is checked before anything is queued; a refusal returns the push target's status and `code` (`TARGET_NOT_FOUND` 404, `FORBIDDEN` 403, `PLAN_REQUIRED` 402, `TARGET_DISABLED` 409, `ENTITY_MISMATCH` 400). Limits and billing are the same as a file delivery, except that push-target deliveries from the ModelMatch web app are not billed.",
-        "operationId": "submitAgentsBulkDelivery",
+        "operationId": "agentLenders",
+        "parameters": [
+          {
+            "description": "Agent document ID",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "description": "Agent document ID",
+              "type": "string"
+            }
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "allOf": [
-                  {
-                    "$ref": "#/components/schemas/AgentListRequest"
-                  },
-                  {
-                    "additionalProperties": false,
-                    "properties": {
-                      "destination": {
-                        "$ref": "#/components/schemas/BulkDeliveryDestination"
-                      },
-                      "fields": {
-                        "description": "Optional output column projection, named by the response DTO fields (the same camelCase fields the list endpoint returns, e.g. `city`, `interestRate`). Intersected with the entitlement scope's allowedFields and the entity's full column set. If empty after intersection, falls back to all columns. It also SELECTS the opt-in columns, which are not part of the list DTO and are never delivered unless named here: `communityLending` (properties, originators, companies, branches) — the Community Lending neighborhood profile, identical to the block on the entity's detail endpoint; `parties` (properties) — the mortgage parties attributed to the parcel, by attribution scope; and `marketCount` / `countyCount` / `stateCount` / `zipCount` / `lenderCount` (originators) — the market-breadth rollups you can already filter on. In `csv` and `parquet` the two block columns are JSON-encoded cells; in `json` and `ndjson` they are nested objects. Windowed production (originators, agents, companies, branches): name `<field>_<n>mo` for n in 3, 6, 12, 14, 18, 24 to get a production field for that trailing window regardless of `period` — e.g. `volume_3mo`, `units_6mo`, `purchaseVolume_24mo`. Available for originators `volume`, `units`, `avgLoanAmount`, `purchaseVolume`, `purchaseUnits`, `refinanceVolume`, `refinanceUnits`, `conventionalPct`, `fhaPct`, `vaPct`; agents `volume`, `units`, `avgSoldPrice`, `buyerVolume`, `buyerUnits`, `sellerVolume`, `sellerUnits`, `totalOriginatorsWorkedWith`, `totalCompaniesWorkedWith`, `totalLendersWorkedWith`; companies `volume`, `units`, `avgLoanAmount`, `loCount`; branches `volume`, `units`, `avgLoanAmount`, `purchasePct`, `refinancePct`, `loCount`. Numbers (null when the window has no data); an entitlement that allows a field allows every window of it.",
-                        "items": {
-                          "minLength": 1,
-                          "type": "string"
-                        },
-                        "type": "array"
-                      },
-                      "format": {
-                        "$ref": "#/components/schemas/BulkDeliveryFormat"
-                      },
-                      "limit": {
-                        "description": "Optional hard cap on the number of rows delivered — and therefore billed (1 credit / row). The job delivers the first `limit` rows in sort order (default newest-first) and bills only for those. If the query matches fewer than `limit`, all matches are delivered. Distinct from the page-size `size` field, which is ignored on this endpoint. The row ceiling still applies — 5,000 without the entity's bulk-delivery entitlement, or the entitlement's `maxRows` with it. A `limit` above the ceiling is rejected, but a `limit` at or below it lets you export a capped top-N even when the full match exceeds the ceiling — which is the intended way to run a broad query under the 5,000-row allowance.",
-                        "example": 5000,
-                        "exclusiveMinimum": true,
-                        "minimum": 0,
-                        "type": "integer"
-                      }
-                    },
-                    "type": "object"
-                  }
-                ]
+                "$ref": "#/components/schemas/ScoredBreakdownRequest"
               }
             }
           }
         },
         "responses": {
-          "202": {
+          "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BulkDeliverySubmitResponse"
+                  "$ref": "#/components/schemas/BreakdownResponse"
                 }
               }
             },
-            "description": "Job queued; ECS task launched"
+            "description": "Pre-aggregated lenders breakdown from the agent's scored doc"
           },
           "400": {
             "content": {
               "application/json": {
                 "schema": {
-                  "anyOf": [
-                    {
-                      "$ref": "#/components/schemas/ErrorResponse"
-                    },
-                    {
-                      "$ref": "#/components/schemas/BulkDeliveryPreflightExceeded"
-                    },
-                    {
-                      "$ref": "#/components/schemas/BulkDeliveryPushTargetError"
-                    }
-                  ]
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             },
-            "description": "Validation failure (incl. `format_required`: a file delivery needs `format`), delivery would exceed the entitlement's maxRows, OR the push target does not accept this entity (`ENTITY_MISMATCH`)"
+            "description": "Validation error"
           },
           "401": {
             "content": {
@@ -33454,108 +35129,89 @@
                 }
               }
             },
-            "description": "Authentication required"
-          },
-          "402": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "anyOf": [
-                    {
-                      "$ref": "#/components/schemas/BulkDeliveryInsufficientCredits"
-                    },
-                    {
-                      "$ref": "#/components/schemas/BulkDeliveryPushTargetError"
-                    }
-                  ]
-                }
-              }
-            },
-            "description": "Insufficient credits (balance < estimatedTotal, at 1 credit per row), OR the plan does not include push targets (`PLAN_REQUIRED`)"
+            "description": "Unauthorized"
           },
           "403": {
             "content": {
               "application/json": {
                 "schema": {
-                  "anyOf": [
-                    {
-                      "$ref": "#/components/schemas/BulkDeliveryForbidden"
-                    },
-                    {
-                      "$ref": "#/components/schemas/BulkDeliveryPushTargetError"
-                    },
-                    {
-                      "$ref": "#/components/schemas/BulkDeliveryInsufficientScope"
-                    }
-                  ]
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             },
-            "description": "Delivery exceeds the 5,000-row limit available without the `bulk-delivery.agents` entitlement (lower `limit`, narrow the filters, or contact support for a limit increase), OR you may not use the push target (`FORBIDDEN`), OR a scoped token named a push-target destination without `push-targets:send` (`insufficient_scope`)."
+            "description": "Forbidden (authenticated, but missing required context — e.g. no active organization)"
           },
           "404": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BulkDeliveryPushTargetError"
-                }
-              }
-            },
-            "description": "Push target not found (`TARGET_NOT_FOUND`)"
-          },
-          "409": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/BulkDeliveryPushTargetError"
+                  "$ref": "#/components/schemas/ErrorResponse"
                 }
               }
             },
-            "description": "Push target is disabled (`TARGET_DISABLED`)"
+            "description": "Not found"
           },
-          "502": {
+          "413": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
+                  "$ref": "#/components/schemas/PayloadTooLarge"
                 }
               }
             },
-            "description": "Preflight / S3 / DDB / ECS launch failure, or the push-target check could not reach the auth server"
+            "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Submit a bulk-delivery job for agents",
+        "summary": "Raw-name lenders encountered (pre-aggregated)",
         "tags": [
           "Agents"
         ]
       }
     },
-    "/v1/agents/bulk-delivery/{jobId}": {
-      "delete": {
-        "description": "Cancels a queued or running agents delivery job.\n\nThe job is marked `cancelled` immediately; the container running it notices on its next page boundary and stops. Because a delivery is billed once, at the end, **a cancelled job is never charged** — no credits are debited and there is nothing to refund. No partial file is written.\n\nIdempotent-ish: cancelling a job that has already finished (or was already cancelled) returns 409 and changes nothing. Poll `GET /v1/agents/bulk-delivery/{jobId}` for the settled state.",
-        "operationId": "cancelAgentsBulkDeliveryJob",
+    "/v1/agents/{id}/breakdowns/offices": {
+      "post": {
+        "operationId": "agentOffices",
         "parameters": [
           {
-            "description": "Job ID returned by `POST /v1/agents/bulk-delivery`",
+            "description": "Agent document ID",
             "in": "path",
-            "name": "jobId",
+            "name": "id",
             "required": true,
             "schema": {
-              "description": "Job ID returned by `POST /v1/agents/bulk-delivery`",
+              "description": "Agent document ID",
               "type": "string"
             }
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BreakdownRequest"
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BulkDeliveryStatusResponse"
+                  "$ref": "#/components/schemas/BreakdownResponse"
                 }
               }
             },
-            "description": "Job cancelled; body is its settled status"
+            "description": "Breakdown of the agent's sales by offices"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Validation error"
           },
           "401": {
             "content": {
@@ -33565,7 +35221,7 @@
                 }
               }
             },
-            "description": "Authentication required"
+            "description": "Unauthorized"
           },
           "403": {
             "content": {
@@ -33575,7 +35231,7 @@
                 }
               }
             },
-            "description": "Caller does not own this job"
+            "description": "Forbidden (authenticated, but missing required context — e.g. no active organization)"
           },
           "404": {
             "content": {
@@ -33585,48 +35241,69 @@
                 }
               }
             },
-            "description": "Job not found (or expired past 30d TTL)"
+            "description": "Not found"
           },
-          "409": {
+          "413": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
+                  "$ref": "#/components/schemas/PayloadTooLarge"
                 }
               }
             },
-            "description": "Job already finished — nothing to cancel"
+            "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Cancel a bulk-delivery job for agents",
+        "summary": "Listing offices the agent has closed through",
         "tags": [
           "Agents"
         ]
-      },
-      "get": {
-        "operationId": "getAgentsBulkDeliveryJob",
+      }
+    },
+    "/v1/agents/{id}/breakdowns/originators": {
+      "post": {
+        "operationId": "agentOriginators",
         "parameters": [
           {
-            "description": "Job ID returned by `POST /v1/agents/bulk-delivery`",
+            "description": "Agent document ID",
             "in": "path",
-            "name": "jobId",
+            "name": "id",
             "required": true,
             "schema": {
-              "description": "Job ID returned by `POST /v1/agents/bulk-delivery`",
+              "description": "Agent document ID",
               "type": "string"
             }
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ScoredBreakdownRequest"
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BulkDeliveryStatusResponse"
+                  "$ref": "#/components/schemas/BreakdownResponse"
                 }
               }
             },
-            "description": "Job status (resultsUrl re-signed if completed)"
+            "description": "Pre-aggregated originators breakdown from the agent's scored doc"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Validation error"
           },
           "401": {
             "content": {
@@ -33636,7 +35313,7 @@
                 }
               }
             },
-            "description": "Authentication required"
+            "description": "Unauthorized"
           },
           "403": {
             "content": {
@@ -33646,7 +35323,7 @@
                 }
               }
             },
-            "description": "Caller does not own this job"
+            "description": "Forbidden (authenticated, but missing required context — e.g. no active organization)"
           },
           "404": {
             "content": {
@@ -33656,24 +35333,45 @@
                 }
               }
             },
-            "description": "Job not found (or expired past 30d TTL)"
+            "description": "Not found"
+          },
+          "413": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PayloadTooLarge"
+                }
+              }
+            },
+            "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Get bulk-delivery job status for agents",
+        "summary": "Loan officers the agent worked with (pre-aggregated)",
         "tags": [
           "Agents"
         ]
       }
     },
-    "/v1/agents/count": {
+    "/v1/agents/{id}/breakdowns/states": {
       "post": {
-        "description": "Return the exact number of agents matching the given filters. Accepts the same request body as `listAgents` (pagination and sort are ignored). Use this when you only need a total; to get the matching agents themselves, send the same request body to `listAgents`.",
-        "operationId": "countAgents",
+        "operationId": "agentStates",
+        "parameters": [
+          {
+            "description": "Agent document ID",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "description": "Agent document ID",
+              "type": "string"
+            }
+          }
+        ],
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/AgentListRequest"
+                "$ref": "#/components/schemas/BreakdownRequest"
               }
             }
           }
@@ -33683,11 +35381,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/CountResponse"
+                  "$ref": "#/components/schemas/BreakdownResponse"
                 }
               }
             },
-            "description": "Exact count of matching agents"
+            "description": "Breakdown of the agent's sales by states"
           },
           "400": {
             "content": {
@@ -33738,28 +35436,17 @@
               }
             },
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
-          },
-          "503": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            },
-            "description": "Location dictionary temporarily unavailable. Only returned for a NEGATED location filter (`neq`, or `not`), which cannot be honoured without resolving the excluded value — answering anyway would return the records you asked to exclude. Positive location filters are unaffected. Retry shortly; the filter value itself was not rejected."
           }
         },
-        "summary": "Count agents matching filters",
+        "summary": "State volume breakdown",
         "tags": [
           "Agents"
-        ],
-        "x-mm-records-via": "listAgents"
+        ]
       }
     },
-    "/v1/agents/{id}": {
-      "get": {
-        "operationId": "getAgent",
+    "/v1/agents/{id}/breakdowns/zip-codes": {
+      "post": {
+        "operationId": "agentZipCodes",
         "parameters": [
           {
             "description": "Agent document ID",
@@ -33770,34 +35457,57 @@
               "description": "Agent document ID",
               "type": "string"
             }
-          },
-          {
-            "description": "Period for volume/units (default: last12Months)",
-            "in": "query",
-            "name": "period",
-            "required": false,
-            "schema": {
-              "allOf": [
-                {
-                  "$ref": "#/components/schemas/Period"
-                },
-                {
-                  "description": "Period for volume/units (default: last12Months)"
-                }
-              ]
-            }
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BreakdownRequest"
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AgentDetailResponse"
+                  "$ref": "#/components/schemas/BreakdownResponse"
                 }
               }
             },
-            "description": "Agent detail"
+            "description": "Breakdown of the agent's sales by zip-codes"
+          },
+          "400": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Validation error"
+          },
+          "401": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Unauthorized"
+          },
+          "403": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            },
+            "description": "Forbidden (authenticated, but missing required context — e.g. no active organization)"
           },
           "404": {
             "content": {
@@ -33807,7 +35517,7 @@
                 }
               }
             },
-            "description": "Agent not found"
+            "description": "Not found"
           },
           "413": {
             "content": {
@@ -33817,26 +35527,27 @@
                 }
               }
             },
-            "description": "Response payload too large"
+            "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Get agent by ID",
+        "summary": "Zip-code volume breakdown",
         "tags": [
           "Agents"
         ]
       }
     },
-    "/v1/agents/{id}/breakdowns/cities": {
+    "/v1/agents/{id}/markets": {
       "post": {
-        "operationId": "agentCities",
+        "description": "Rank the ZIP markets one real-estate agent works, with volume, transaction counts and mean sale price per market, plus a weighted summary across the whole footprint. Optionally narrow to a ZIP list or a date window. REACH, NOT MARKET SHARE: an agent belongs to every market they touch — where their office is AND everywhere they have transacted — so one agent is counted in several markets at once. Per-market agent counts therefore over-sum: they cannot be added together, and dividing one into a total does not produce a market share. The only percentage returned, `shareOfScope`, is each market's share of this agent's volume across the scope requested and sums to 100 over that scope; there is no share-of-whole-book figure, because the transaction records carry no per-agent total to divide by. TWO COUNTS, ON PURPOSE: `transactions` counts transaction records; `units` counts the ones carrying a price, which are the records behind `volume` and `avgSalePrice`. Roughly half of an agent's records are priced, so dividing volume by `transactions` understates the average by about 2×. Figures are computed live from the agent's transaction records — an agent record carries no stored market rollup — and are ranked across their busiest ZIP markets. When a ZIP scope returns no markets, `reach.presentInScope` distinguishes 'works there, nothing closed in the window' from 'not present at all'. The summary also carries a Community Lending mix: what kind of neighborhood these markets are, weighted by the agent's activity in each. These are U.S. Census tract-level aggregates describing whole neighborhoods — never an individual, household or client attribute — and on this surface the basis is always the markets in scope, since an agent record carries no stored neighborhood rollup.",
+        "operationId": "agentMarkets",
         "parameters": [
           {
-            "description": "Agent document ID",
+            "description": "Agent ID",
             "in": "path",
             "name": "id",
             "required": true,
             "schema": {
-              "description": "Agent document ID",
+              "description": "Agent ID",
               "type": "string"
             }
           }
@@ -33845,7 +35556,7 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/BreakdownRequest"
+                "$ref": "#/components/schemas/AgentMarketsRequest"
               }
             }
           }
@@ -33855,11 +35566,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BreakdownResponse"
+                  "$ref": "#/components/schemas/AgentMarketsResponse"
                 }
               }
             },
-            "description": "Breakdown of the agent's sales by cities"
+            "description": "The agent's blended market footprint"
           },
           "400": {
             "content": {
@@ -33912,15 +35623,15 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "City volume breakdown across the agent's sales",
+        "summary": "The ZIP markets this agent works, blended",
         "tags": [
           "Agents"
         ]
       }
     },
-    "/v1/agents/{id}/breakdowns/companies": {
+    "/v1/agents/{id}/properties": {
       "post": {
-        "operationId": "agentCompanies",
+        "operationId": "agentProperties",
         "parameters": [
           {
             "description": "Agent document ID",
@@ -33937,7 +35648,7 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/ScoredBreakdownRequest"
+                "$ref": "#/components/schemas/AgentRelationRequest"
               }
             }
           }
@@ -33947,11 +35658,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BreakdownResponse"
+                  "$ref": "#/components/schemas/AgentPropertiesResponse"
                 }
               }
             },
-            "description": "Pre-aggregated companies breakdown from the agent's scored doc"
+            "description": "Paginated list of properties for this agent"
           },
           "400": {
             "content": {
@@ -34004,46 +35715,64 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Mortgage companies the agent dealt with (pre-aggregated)",
+        "summary": "Properties this agent has transacted on",
         "tags": [
           "Agents"
         ]
       }
     },
-    "/v1/agents/{id}/breakdowns/counties": {
-      "post": {
-        "operationId": "agentCounties",
+    "/v1/agents/{id}/related": {
+      "get": {
+        "description": "Return the ids of records of another type that are linked to this record. Links resolve by identifier, strongest identifier first, and equally-trusted identifiers are combined — a company's linked loans cover every role it holds on a loan, not just the first one found. The response reports which strength was used: `primary` is the canonical identifier for that pair, `secondary` is a real but weaker alternate used only when the record carries nothing better. This is a lightweight index: it returns ids and a count, not full records. For filtering, sorting, pagination and full detail, use the named endpoint for the pair (for example the originator loans endpoint) and fetch records by id.",
+        "operationId": "agentRelated",
         "parameters": [
           {
-            "description": "Agent document ID",
+            "description": "Agent id",
             "in": "path",
             "name": "id",
             "required": true,
             "schema": {
-              "description": "Agent document ID",
+              "description": "Agent id",
               "type": "string"
             }
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/BreakdownRequest"
-              }
+          },
+          {
+            "description": "Type of record to link to",
+            "in": "query",
+            "name": "to",
+            "required": true,
+            "schema": {
+              "description": "Type of record to link to",
+              "enum": [
+                "loans",
+                "sales"
+              ],
+              "type": "string"
+            }
+          },
+          {
+            "description": "Maximum ids to return (default 25, max 200)",
+            "in": "query",
+            "name": "limit",
+            "required": false,
+            "schema": {
+              "description": "Maximum ids to return (default 25, max 200)",
+              "maximum": 200,
+              "minimum": 1,
+              "type": "integer"
             }
           }
-        },
+        ],
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BreakdownResponse"
+                  "$ref": "#/components/schemas/RelatedResponse"
                 }
               }
             },
-            "description": "Breakdown of the agent's sales by counties"
+            "description": "Linked record ids"
           },
           "400": {
             "content": {
@@ -34083,7 +35812,7 @@
                 }
               }
             },
-            "description": "Not found"
+            "description": "Record not found"
           },
           "413": {
             "content": {
@@ -34096,15 +35825,15 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "County (FIPS) volume breakdown",
+        "summary": "Records linked to this one",
         "tags": [
-          "Agents"
+          "Related"
         ]
       }
     },
-    "/v1/agents/{id}/breakdowns/lenders": {
+    "/v1/agents/{id}/sales": {
       "post": {
-        "operationId": "agentLenders",
+        "operationId": "agentSales",
         "parameters": [
           {
             "description": "Agent document ID",
@@ -34121,7 +35850,7 @@
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/ScoredBreakdownRequest"
+                "$ref": "#/components/schemas/AgentRelationRequest"
               }
             }
           }
@@ -34131,11 +35860,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BreakdownResponse"
+                  "$ref": "#/components/schemas/AgentSalesResponse"
                 }
               }
             },
-            "description": "Pre-aggregated lenders breakdown from the agent's scored doc"
+            "description": "Paginated list of sales for this agent"
           },
           "400": {
             "content": {
@@ -34188,46 +35917,25 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Raw-name lenders encountered (pre-aggregated)",
+        "summary": "Sales transactions where this agent was listing or selling side",
         "tags": [
           "Agents"
         ]
       }
     },
-    "/v1/agents/{id}/breakdowns/offices": {
-      "post": {
-        "operationId": "agentOffices",
-        "parameters": [
-          {
-            "description": "Agent document ID",
-            "in": "path",
-            "name": "id",
-            "required": true,
-            "schema": {
-              "description": "Agent document ID",
-              "type": "string"
-            }
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/BreakdownRequest"
-              }
-            }
-          }
-        },
+    "/v1/alerts/conditions": {
+      "get": {
+        "operationId": "getAlertConditions",
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BreakdownResponse"
+                  "$ref": "#/components/schemas/AlertConditionsResponse"
                 }
               }
             },
-            "description": "Breakdown of the agent's sales by offices"
+            "description": "Per-trigger flags + tunables (defaults if none saved)"
           },
           "400": {
             "content": {
@@ -34280,32 +35988,19 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Listing offices the agent has closed through",
+        "summary": "Get your alert settings",
         "tags": [
-          "Agents"
+          "Alerts"
         ]
-      }
-    },
-    "/v1/agents/{id}/breakdowns/originators": {
-      "post": {
-        "operationId": "agentOriginators",
-        "parameters": [
-          {
-            "description": "Agent document ID",
-            "in": "path",
-            "name": "id",
-            "required": true,
-            "schema": {
-              "description": "Agent document ID",
-              "type": "string"
-            }
-          }
-        ],
+      },
+      "put": {
+        "description": "Saves your NMLS id, contact identity and tunables. The per-trigger `enabled` flags are deprecated: subscribe to alert recipes or manage subscriptions instead. While still accepted, `enabled[type]: true` turns the trigger on for every watched subject that supports it, and `false` turns it off everywhere.",
+        "operationId": "updateAlertConditions",
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/ScoredBreakdownRequest"
+                "$ref": "#/components/schemas/UpdateAlertConditionsRequest"
               }
             }
           }
@@ -34315,11 +36010,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BreakdownResponse"
+                  "$ref": "#/components/schemas/AlertConditionsResponse"
                 }
               }
             },
-            "description": "Pre-aggregated originators breakdown from the agent's scored doc"
+            "description": "The saved settings"
           },
           "400": {
             "content": {
@@ -34372,46 +36067,49 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Loan officers the agent worked with (pre-aggregated)",
+        "summary": "Update your alert settings",
         "tags": [
-          "Agents"
+          "Alerts"
         ]
       }
     },
-    "/v1/agents/{id}/breakdowns/states": {
-      "post": {
-        "operationId": "agentStates",
+    "/v1/alerts/digests": {
+      "get": {
+        "operationId": "listAlertDigests",
         "parameters": [
           {
-            "description": "Agent document ID",
-            "in": "path",
-            "name": "id",
-            "required": true,
+            "description": "Max items to return (default 25).",
+            "in": "query",
+            "name": "limit",
+            "required": false,
             "schema": {
-              "description": "Agent document ID",
+              "description": "Max items to return (default 25).",
+              "maximum": 100,
+              "minimum": 1,
+              "type": "integer"
+            }
+          },
+          {
+            "description": "Pagination cursor from a previous response.",
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "schema": {
+              "description": "Pagination cursor from a previous response.",
               "type": "string"
             }
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/BreakdownRequest"
-              }
-            }
-          }
-        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BreakdownResponse"
+                  "$ref": "#/components/schemas/AlertDigestResponse"
                 }
               }
             },
-            "description": "Breakdown of the agent's sales by states"
+            "description": "Paginated digest feed"
           },
           "400": {
             "content": {
@@ -34464,46 +36162,37 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "State volume breakdown",
+        "summary": "List your alert digests (newest first)",
         "tags": [
-          "Agents"
+          "Alerts"
         ]
       }
     },
-    "/v1/agents/{id}/breakdowns/zip-codes": {
+    "/v1/alerts/digests/{id}/read": {
       "post": {
-        "operationId": "agentZipCodes",
+        "operationId": "markAlertDigestRead",
         "parameters": [
           {
-            "description": "Agent document ID",
+            "description": "Digest id (from the feed).",
             "in": "path",
             "name": "id",
             "required": true,
             "schema": {
-              "description": "Agent document ID",
+              "description": "Digest id (from the feed).",
               "type": "string"
             }
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/BreakdownRequest"
-              }
-            }
-          }
-        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BreakdownResponse"
+                  "$ref": "#/components/schemas/AlertsOkResponse"
                 }
               }
             },
-            "description": "Breakdown of the agent's sales by zip-codes"
+            "description": "Marked read (idempotent)"
           },
           "400": {
             "content": {
@@ -34556,47 +36245,49 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Zip-code volume breakdown",
+        "summary": "Mark one digest read",
         "tags": [
-          "Agents"
+          "Alerts"
         ]
       }
     },
-    "/v1/agents/{id}/markets": {
-      "post": {
-        "description": "Rank the ZIP markets one real-estate agent works, with volume, transaction counts and mean sale price per market, plus a weighted summary across the whole footprint. Optionally narrow to a ZIP list or a date window. REACH, NOT MARKET SHARE: an agent belongs to every market they touch — where their office is AND everywhere they have transacted — so one agent is counted in several markets at once. Per-market agent counts therefore over-sum: they cannot be added together, and dividing one into a total does not produce a market share. The only percentage returned, `shareOfScope`, is each market's share of this agent's volume across the scope requested and sums to 100 over that scope; there is no share-of-whole-book figure, because the transaction records carry no per-agent total to divide by. TWO COUNTS, ON PURPOSE: `transactions` counts transaction records; `units` counts the ones carrying a price, which are the records behind `volume` and `avgSalePrice`. Roughly half of an agent's records are priced, so dividing volume by `transactions` understates the average by about 2×. Figures are computed live from the agent's transaction records — an agent record carries no stored market rollup — and are ranked across their busiest ZIP markets. When a ZIP scope returns no markets, `reach.presentInScope` distinguishes 'works there, nothing closed in the window' from 'not present at all'. The summary also carries a Community Lending mix: what kind of neighborhood these markets are, weighted by the agent's activity in each. These are U.S. Census tract-level aggregates describing whole neighborhoods — never an individual, household or client attribute — and on this surface the basis is always the markets in scope, since an agent record carries no stored neighborhood rollup.",
-        "operationId": "agentMarkets",
+    "/v1/alerts/log": {
+      "get": {
+        "operationId": "listAlertLog",
         "parameters": [
           {
-            "description": "Agent ID",
-            "in": "path",
-            "name": "id",
-            "required": true,
+            "description": "Max items to return (default 25).",
+            "in": "query",
+            "name": "limit",
+            "required": false,
             "schema": {
-              "description": "Agent ID",
+              "description": "Max items to return (default 25).",
+              "maximum": 100,
+              "minimum": 1,
+              "type": "integer"
+            }
+          },
+          {
+            "description": "Pagination cursor from a previous response.",
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "schema": {
+              "description": "Pagination cursor from a previous response.",
               "type": "string"
             }
           }
         ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/AgentMarketsRequest"
-              }
-            }
-          }
-        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AgentMarketsResponse"
+                  "$ref": "#/components/schemas/AlertLogResponse"
                 }
               }
             },
-            "description": "The agent's blended market footprint"
+            "description": "Paginated alert feed"
           },
           "400": {
             "content": {
@@ -34649,46 +36340,25 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "The ZIP markets this agent works, blended",
+        "summary": "List your alerts (newest first)",
         "tags": [
-          "Agents"
+          "Alerts"
         ]
       }
     },
-    "/v1/agents/{id}/properties": {
+    "/v1/alerts/log/mark-all-read": {
       "post": {
-        "operationId": "agentProperties",
-        "parameters": [
-          {
-            "description": "Agent document ID",
-            "in": "path",
-            "name": "id",
-            "required": true,
-            "schema": {
-              "description": "Agent document ID",
-              "type": "string"
-            }
-          }
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/AgentRelationRequest"
-              }
-            }
-          }
-        },
+        "operationId": "markAllAlertsRead",
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AgentPropertiesResponse"
+                  "$ref": "#/components/schemas/AlertsOkResponse"
                 }
               }
             },
-            "description": "Paginated list of properties for this agent"
+            "description": "Unread count reset to 0"
           },
           "400": {
             "content": {
@@ -34741,52 +36411,25 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Properties this agent has transacted on",
+        "summary": "Clear the unread badge",
         "tags": [
-          "Agents"
+          "Alerts"
         ]
       }
     },
-    "/v1/agents/{id}/related": {
-      "get": {
-        "description": "Return the ids of records of another type that are linked to this record. Links resolve by identifier, strongest identifier first, and equally-trusted identifiers are combined — a company's linked loans cover every role it holds on a loan, not just the first one found. The response reports which strength was used: `primary` is the canonical identifier for that pair, `secondary` is a real but weaker alternate used only when the record carries nothing better. This is a lightweight index: it returns ids and a count, not full records. For filtering, sorting, pagination and full detail, use the named endpoint for the pair (for example the originator loans endpoint) and fetch records by id.",
-        "operationId": "agentRelated",
+    "/v1/alerts/log/{id}/read": {
+      "post": {
+        "operationId": "markAlertRead",
         "parameters": [
           {
-            "description": "Agent id",
+            "description": "Alert id (from the feed).",
             "in": "path",
             "name": "id",
             "required": true,
             "schema": {
-              "description": "Agent id",
-              "type": "string"
-            }
-          },
-          {
-            "description": "Type of record to link to",
-            "in": "query",
-            "name": "to",
-            "required": true,
-            "schema": {
-              "description": "Type of record to link to",
-              "enum": [
-                "loans",
-                "sales"
-              ],
+              "description": "Alert id (from the feed).",
               "type": "string"
             }
-          },
-          {
-            "description": "Maximum ids to return (default 25, max 200)",
-            "in": "query",
-            "name": "limit",
-            "required": false,
-            "schema": {
-              "description": "Maximum ids to return (default 25, max 200)",
-              "maximum": 200,
-              "minimum": 1,
-              "type": "integer"
-            }
           }
         ],
         "responses": {
@@ -34794,11 +36437,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/RelatedResponse"
+                  "$ref": "#/components/schemas/AlertsOkResponse"
                 }
               }
             },
-            "description": "Linked record ids"
+            "description": "Marked read (idempotent)"
           },
           "400": {
             "content": {
@@ -34838,7 +36481,7 @@
                 }
               }
             },
-            "description": "Record not found"
+            "description": "Not found"
           },
           "413": {
             "content": {
@@ -34851,46 +36494,36 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Records linked to this one",
+        "summary": "Mark one alert read",
         "tags": [
-          "Related"
+          "Alerts"
         ]
       }
     },
-    "/v1/agents/{id}/sales": {
+    "/v1/alerts/preview": {
       "post": {
-        "operationId": "agentSales",
-        "parameters": [
-          {
-            "description": "Agent document ID",
-            "in": "path",
-            "name": "id",
-            "required": true,
-            "schema": {
-              "description": "Agent document ID",
-              "type": "string"
-            }
-          }
-        ],
+        "description": "Runs all six detectors scoped to your own token, in-process and synchronously, as a dry-run: returns the alerts that WOULD fire (per detector, with the decision payloads) without writing the feed, publishing events, or sending email.",
+        "operationId": "previewAlerts",
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/AgentRelationRequest"
+                "$ref": "#/components/schemas/PreviewAlertsRequest"
               }
             }
-          }
+          },
+          "required": false
         },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AgentSalesResponse"
+                  "$ref": "#/components/schemas/RunUserDetectorResponse"
                 }
               }
             },
-            "description": "Paginated list of sales for this agent"
+            "description": "Per-detector dry-run summary (the decisions that would fire)"
           },
           "400": {
             "content": {
@@ -34943,25 +36576,26 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Sales transactions where this agent was listing or selling side",
+        "summary": "Preview the alerts that would fire for you",
         "tags": [
-          "Agents"
+          "Alerts"
         ]
       }
     },
-    "/v1/alerts/conditions": {
+    "/v1/alerts/recipes": {
       "get": {
-        "operationId": "getAlertConditions",
+        "description": "The alert recipes — named bundles of alert triggers — with the inputs each needs and whether you are subscribed.",
+        "operationId": "listAlertRecipes",
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AlertConditionsResponse"
+                  "$ref": "#/components/schemas/AlertRecipesResponse"
                 }
               }
             },
-            "description": "Per-trigger flags + tunables (defaults if none saved)"
+            "description": "Recipes"
           },
           "400": {
             "content": {
@@ -35014,32 +36648,45 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Get your alert settings",
+        "summary": "List alert recipes",
         "tags": [
           "Alerts"
         ]
-      },
-      "put": {
-        "operationId": "updateAlertConditions",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/UpdateAlertConditionsRequest"
-              }
+      }
+    },
+    "/v1/alerts/recipes/{id}": {
+      "delete": {
+        "description": "Turns the recipe's alert triggers off. Saved agents, areas and records stay; remove them with the watch-list endpoints.",
+        "operationId": "unsubscribeAlertRecipe",
+        "parameters": [
+          {
+            "description": "Recipe id.",
+            "in": "path",
+            "name": "id",
+            "required": true,
+            "schema": {
+              "description": "Recipe id.",
+              "enum": [
+                "past-clients",
+                "agent-partners",
+                "farm-area",
+                "watch-record"
+              ],
+              "example": "farm-area",
+              "type": "string"
             }
           }
-        },
+        ],
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AlertConditionsResponse"
+                  "$ref": "#/components/schemas/AlertRecipeResponse"
                 }
               }
             },
-            "description": "The saved settings"
+            "description": "Unsubscribed"
           },
           "400": {
             "content": {
@@ -35092,49 +36739,53 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Update your alert settings",
+        "summary": "Unsubscribe from an alert recipe",
         "tags": [
           "Alerts"
         ]
-      }
-    },
-    "/v1/alerts/digests": {
-      "get": {
-        "operationId": "listAlertDigests",
+      },
+      "post": {
+        "description": "Turns on the recipe's alert triggers, saves its inputs (NMLS id, agents, areas or a record), and backfills recent matches. For watch-record, empty rules apply the default for the record type: property — foreclosure status changes, or sale propensity reaches 50; sale — listing status changes; loan — interest rate moves by 0.125 points or more.",
+        "operationId": "subscribeAlertRecipe",
         "parameters": [
           {
-            "description": "Max items to return (default 25).",
-            "in": "query",
-            "name": "limit",
-            "required": false,
-            "schema": {
-              "description": "Max items to return (default 25).",
-              "maximum": 100,
-              "minimum": 1,
-              "type": "integer"
-            }
-          },
-          {
-            "description": "Pagination cursor from a previous response.",
-            "in": "query",
-            "name": "cursor",
-            "required": false,
+            "description": "Recipe id.",
+            "in": "path",
+            "name": "id",
+            "required": true,
             "schema": {
-              "description": "Pagination cursor from a previous response.",
+              "description": "Recipe id.",
+              "enum": [
+                "past-clients",
+                "agent-partners",
+                "farm-area",
+                "watch-record"
+              ],
+              "example": "farm-area",
               "type": "string"
             }
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertRecipeInputs"
+              }
+            }
+          },
+          "required": false
+        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AlertDigestResponse"
+                  "$ref": "#/components/schemas/AlertRecipeResponse"
                 }
               }
             },
-            "description": "Paginated digest feed"
+            "description": "Subscribed"
           },
           "400": {
             "content": {
@@ -35187,37 +36838,55 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "List your alert digests (newest first)",
+        "summary": "Subscribe to an alert recipe",
         "tags": [
           "Alerts"
         ]
       }
     },
-    "/v1/alerts/digests/{id}/read": {
+    "/v1/alerts/recipes/{id}/preview": {
       "post": {
-        "operationId": "markAlertDigestRead",
+        "description": "Dry-run the recipe over the last 30 days for you, with the given inputs applied on top of your saved ones. Writes nothing.",
+        "operationId": "previewAlertRecipe",
         "parameters": [
           {
-            "description": "Digest id (from the feed).",
+            "description": "Recipe id.",
             "in": "path",
             "name": "id",
             "required": true,
             "schema": {
-              "description": "Digest id (from the feed).",
+              "description": "Recipe id.",
+              "enum": [
+                "past-clients",
+                "agent-partners",
+                "farm-area",
+                "watch-record"
+              ],
+              "example": "farm-area",
               "type": "string"
             }
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/AlertRecipeInputs"
+              }
+            }
+          },
+          "required": false
+        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AlertsOkResponse"
+                  "$ref": "#/components/schemas/AlertRecipePreviewResponse"
                 }
               }
             },
-            "description": "Marked read (idempotent)"
+            "description": "What the recipe would have fired"
           },
           "400": {
             "content": {
@@ -35270,35 +36939,55 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Mark one digest read",
+        "summary": "Preview an alert recipe",
         "tags": [
           "Alerts"
         ]
       }
     },
-    "/v1/alerts/log": {
+    "/v1/alerts/subscriptions": {
       "get": {
-        "operationId": "listAlertLog",
+        "description": "Every subject you watch — agents, areas, your NMLS id, records — with the alert kinds that fire on it and the recipes that turned them on.",
+        "operationId": "listAlertSubscriptions",
         "parameters": [
           {
-            "description": "Max items to return (default 25).",
+            "description": "Only subscriptions of this subject type.",
             "in": "query",
-            "name": "limit",
+            "name": "subjectType",
             "required": false,
             "schema": {
-              "description": "Max items to return (default 25).",
-              "maximum": 100,
-              "minimum": 1,
-              "type": "integer"
+              "description": "Only subscriptions of this subject type.",
+              "enum": [
+                "agent",
+                "area",
+                "nmls",
+                "property",
+                "loan",
+                "sale",
+                "company",
+                "filter"
+              ],
+              "type": "string"
             }
           },
           {
-            "description": "Pagination cursor from a previous response.",
+            "description": "Only subscriptions carrying this alert kind.",
             "in": "query",
-            "name": "cursor",
+            "name": "kind",
             "required": false,
             "schema": {
-              "description": "Pagination cursor from a previous response.",
+              "description": "Only subscriptions carrying this alert kind.",
+              "enum": [
+                "area_new_listing",
+                "watched_agent_pending",
+                "borrower_listed",
+                "epo_risk",
+                "agent_sale_closed",
+                "rate_term_refi_area",
+                "watched_sale",
+                "watched_property",
+                "watched_loan"
+              ],
               "type": "string"
             }
           }
@@ -35308,11 +36997,11 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AlertLogResponse"
+                  "$ref": "#/components/schemas/AlertSubscriptionsResponse"
                 }
               }
             },
-            "description": "Paginated alert feed"
+            "description": "Subscriptions"
           },
           "400": {
             "content": {
@@ -35365,35 +37054,43 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "List your alerts (newest first)",
+        "summary": "List your alert subscriptions",
         "tags": [
           "Alerts"
         ]
-      }
-    },
-    "/v1/alerts/log/mark-all-read": {
+      },
       "post": {
-        "operationId": "markAllAlertsRead",
+        "description": "Watch a subject (an agent, an area, your NMLS id, or a sale / property / loan with rules) for the given alert kinds. Re-posting the same subject replaces the kinds you set directly; kinds a recipe turned on stay. Recent matches are backfilled when kinds are added.",
+        "operationId": "createAlertSubscription",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateAlertSubscriptionRequest"
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/AlertsOkResponse"
+                  "$ref": "#/components/schemas/AlertSubscriptionResponse"
                 }
               }
             },
-            "description": "Unread count reset to 0"
+            "description": "The subscription as saved"
           },
           "400": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
+                  "$ref": "#/components/schemas/AlertSubscriptionError"
                 }
               }
             },
-            "description": "Validation error"
+            "description": "Invalid subscription (see `code`)"
           },
           "401": {
             "content": {
@@ -35436,23 +37133,24 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Clear the unread badge",
+        "summary": "Subscribe to alerts on a subject",
         "tags": [
           "Alerts"
         ]
       }
     },
-    "/v1/alerts/log/{id}/read": {
-      "post": {
-        "operationId": "markAlertRead",
+    "/v1/alerts/subscriptions/{id}": {
+      "delete": {
+        "description": "Stops watching the subject (idempotent). For a record watch this also forgets its baseline, so watching it again starts fresh.",
+        "operationId": "deleteAlertSubscription",
         "parameters": [
           {
-            "description": "Alert id (from the feed).",
+            "description": "Opaque subscription id.",
             "in": "path",
             "name": "id",
             "required": true,
             "schema": {
-              "description": "Alert id (from the feed).",
+              "description": "Opaque subscription id.",
               "type": "string"
             }
           }
@@ -35466,17 +37164,17 @@
                 }
               }
             },
-            "description": "Marked read (idempotent)"
+            "description": "Removed"
           },
           "400": {
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
+                  "$ref": "#/components/schemas/AlertSubscriptionError"
                 }
               }
             },
-            "description": "Validation error"
+            "description": "Invalid subscription (see `code`)"
           },
           "401": {
             "content": {
@@ -35519,89 +37217,7 @@
             "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
           }
         },
-        "summary": "Mark one alert read",
-        "tags": [
-          "Alerts"
-        ]
-      }
-    },
-    "/v1/alerts/preview": {
-      "post": {
-        "description": "Runs all six detectors scoped to your own token, in-process and synchronously, as a dry-run: returns the alerts that WOULD fire (per detector, with the decision payloads) without writing the feed, publishing events, or sending email.",
-        "operationId": "previewAlerts",
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/PreviewAlertsRequest"
-              }
-            }
-          },
-          "required": false
-        },
-        "responses": {
-          "200": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/RunUserDetectorResponse"
-                }
-              }
-            },
-            "description": "Per-detector dry-run summary (the decisions that would fire)"
-          },
-          "400": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            },
-            "description": "Validation error"
-          },
-          "401": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            },
-            "description": "Unauthorized"
-          },
-          "403": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            },
-            "description": "Forbidden (authenticated, but missing required context — e.g. no active organization)"
-          },
-          "404": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ErrorResponse"
-                }
-              }
-            },
-            "description": "Not found"
-          },
-          "413": {
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PayloadTooLarge"
-                }
-              }
-            },
-            "description": "Response payload too large — detail endpoint capped to fit Lambda response limits"
-          }
-        },
-        "summary": "Preview the alerts that would fire for you",
+        "summary": "Remove an alert subscription",
         "tags": [
           "Alerts"
         ]
@@ -35832,12 +37448,12 @@
         "operationId": "removeWatchedAgent",
         "parameters": [
           {
-            "description": "Agent id to remove.",
+            "description": "Agent id to remove (a hand-added agent; auto-derived agents follow your NMLS id).",
             "in": "path",
             "name": "id",
             "required": true,
             "schema": {
-              "description": "Agent id to remove.",
+              "description": "Agent id to remove (a hand-added agent; auto-derived agents follow your NMLS id).",
               "type": "string"
             }
           }