Changelog

Track API changes, new features, and deprecations.

August 2026

v2.1Facts-only detail
  • GET /prospects/:ticker and GET /excerpts no longer return 404 for companies that have not been assessed for the product. Detail returns the facts-only shape: assessment_status "unassessed", null scores, empty findings/excerpts, with company_info, premium, complaints, and hierarchy populated. Excerpts return an empty page (total_count 0). Every ticker visible in a list or hierarchy is now fetchable; 404 means unknown or ambiguous, never “not analysed yet”.

August 2026

v2Breaking — v1 removed
  • All endpoints moved to /api/v2. /api/v1 has been removed and returns 410 Gone with a JSON body naming the new base path. Update your base URL, and if you use the MCP server, upgrade it to 2.0.0 — 0.2.x targets v1 and stops working. Tool names, authentication, and configuration are unchanged.
  • Breaking: framework_category has been removed from the GET /excerpts query parameters and from every excerpt object, including excerpts embedded in prospect detail. Filter with min_impact_score and keyword instead.
  • Breaking: total_count is removed from GET /prospects; use total_groups (corporate families) and total_entities (companies inside them). (total_count on GET /excerpts is unrelated and unchanged.)
  • Breaking: GET /prospects, GET /prospects/:ticker, and GET /excerpts return 503 with { error: "projection_unavailable", reason } and a Retry-After header when the product's prospect data is rebuilding (rebuilding) or has not been rebuilt since a keywords edit (stale_keywords). Callers that read an empty v1 list as “nothing matched” must handle the error path.
  • GET /prospects now lists the full candidate universe, not only assessed companies. Rows carry assessment_status (assessed, pending_score, unassessed); unassessed rows have null deal_score / buying_signal_score and rank last under the default relevance ordering.
  • GET /prospects accepts new filters: assessment_status, entity_type, ownership, min_premium / max_premium, lines_of_business (any-match), min_licensed_states (0–50), states_licensed_in (all-match), q (name search, matching subsidiary names too), and include_children; plus sort_by / sort_dir with nulls-last semantics. Insurance filters are strict — a family with no premium data does not match a premium filter — and excluded_no_data_groups counts how many were dropped for lacking the data a filter required.
  • GET /prospects rows add NAIC premium summaries (with the report_years that contributed), family complaint summaries with complaint_index, lines_of_business, licensed_states, ownership, insurance_entity_types, and entity_count / matched_entity_count.
  • GET /prospects/:ticker adds company_info firmographics, entity-level premium and complaints (full per-year, per-line NAIC series, narrowable with report_year), hierarchy with child tickers you can pass straight back to the endpoint, narrative_scope, and excerpt_count. Embedded excerpts are capped at 20 (highest impact first); use GET /excerpts for the rest.
  • GET /products and GET /products/:id now return segment_targeting (all or selected) and target_segments: the insurance entity types a product sells to, with ownership, per-line premium bands, and licensed-footprint range. Segments are read-only; product setup stays in the UI.
  • Subsidiary tickers passed to the DealMap and outreach endpoints now resolve upward to the corporate family's DealMap (the response names the family) instead of failing. A generate that resolves to a cached family map is not charged.
  • PATCH /dealmap/node-top-pick is now documented (body { product_id, ticker, node_id, is_top_pick }). It was already implemented; it also gains an MCP tool, set_top_pick.

May 2026

v1Product visibility
  • GET /products and GET /products/:id now hide disabled products by default. Pass include_disabled=true to retrieve disabled product metadata.
  • Operational endpoints, including prospects, excerpts, outreach, and DealMap routes, continue to reject disabled product IDs.

March 2026

v1Initial release
  • GET /products and GET /products/:id — list and retrieve active products with keywords, sources, and industries. Disabled product metadata is available only through an explicit opt-in.
  • GET /prospects and GET /prospects/:ticker — list ranked prospects and get detailed company analysis.
  • GET /excerpts — search and filter evidence excerpts by impact score, framework category, and keywords.
  • GET /dealmap, POST /dealmap/generate, PATCH /dealmap/node-role — buying committee DealMap with AI-assigned stakeholder roles and org hierarchy.
  • POST /outreach — generate evidence-backed email and LinkedIn outreach messages.
  • Bearer token authentication with read and outreach scopes.
  • Per-key rate limiting with dedicated caps for DealMap generation and outreach.
  • Monthly credit system with per-plan allowances.
API ReferenceWorking with Products
Changelog | DealSurface Docs