{
 "openapi": "3.1.0",
 "info": {
  "title": "Fundz Agent Data API",
  "version": "2026.09.07",
  "summary": "Primary-filed event evidence for AI sales and GTM agents.",
  "description": "Every signal links to its source, dated. Launch lanes are **funding** (SEC Form D and announcements) and **SEC 8-K**.\n\nEach evidence item carries `source_kind`, which is `sec_filing` or `press_or_news` \u2014 we label which, rather than calling the whole corpus primary-filed. No contact or people data is offered.\n\nUnits: 1 per `why_now`, `events_for_icp` and `predicted_next`; **0.1 per company CHECKED** by `watchlist_diff` \u2014 checked, not returned, so a poll that finds nothing still reflects the work done.",
  "contact": {
   "name": "Fundz",
   "email": "john@fundz.net",
   "url": "https://www.fundz.net"
  }
 },
 "servers": [
  {
   "url": "https://api.fundz.net",
   "description": "Production. A friendlier host on api.fundz.net is intended and NOT yet routed; this URL is what serves today."
  }
 ],
 "security": [
  {
   "bearerAuth": []
  }
 ],
 "components": {
  "securitySchemes": {
   "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "description": "An API key issued by Fundz. `Authorization: Bearer fundz_ak_live_...`, or `X-Api-Key`."
   }
  },
  "schemas": {
   "why_now_response": {
    "type": "object",
    "properties": {
     "company": {
      "type": "object",
      "properties": {
       "org_id": {
        "type": [
         "integer",
         "null"
        ]
       },
       "name": {
        "type": "string"
       },
       "domain": {
        "type": "string"
       },
       "name_agreement": {
        "type": "integer"
       }
      }
     },
     "evidence": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "type": {
         "type": "string"
        },
        "date": {
         "type": "string"
        },
        "summary": {
         "type": "string"
        },
        "source_url": {
         "type": "string"
        },
        "source_kind": {
         "type": "string"
        },
        "sec_items": {
         "type": "array",
         "items": {
          "type": "string"
         }
        }
       }
      }
     },
     "last_event": {
      "type": [
       "null",
       "object"
      ],
      "properties": {
       "type": {
        "type": "string"
       },
       "date": {
        "type": "string"
       },
       "summary": {
        "type": "string"
       },
       "source_url": {
        "type": "string"
       },
       "source_kind": {
        "type": "string"
       },
       "sec_items": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "within_lookback": {
        "type": "boolean"
       }
      }
     },
     "last_event_at": {
      "type": [
       "null",
       "string"
      ]
     },
     "narrative": {
      "type": "null"
     },
     "coverage_note": {
      "type": [
       "null",
       "string"
      ]
     },
     "resolved": {
      "type": "boolean"
     },
     "_usage": {
      "type": "object",
      "properties": {
       "units_charged": {
        "type": "string"
       },
       "units_month_to_date": {
        "type": "string"
       }
      }
     }
    }
   },
   "events_for_icp_response": {
    "type": "object",
    "properties": {
     "results": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "company": {
         "type": "object",
         "properties": {
          "org_id": {
           "type": "integer"
          },
          "name": {
           "type": "string"
          },
          "domain": {
           "type": "string"
          },
          "name_agreement": {
           "type": "integer"
          }
         }
        },
        "signals": {
         "type": "array",
         "items": {
          "type": "object",
          "properties": {
           "type": {
            "type": "string"
           },
           "date": {
            "type": "string"
           },
           "summary": {
            "type": "string"
           },
           "source_url": {
            "type": "string"
           },
           "source_kind": {
            "type": "string"
           }
          }
         }
        },
        "signal_count": {
         "type": "integer"
        },
        "last_event_at": {
         "type": "string"
        },
        "why_now_short": {
         "type": "string"
        }
       }
      }
     },
     "next_cursor": {
      "type": "string"
     },
     "_usage": {
      "type": "object",
      "properties": {
       "units_charged": {
        "type": "string"
       },
       "units_month_to_date": {
        "type": "string"
       }
      }
     }
    }
   },
   "watchlist_diff_response": {
    "type": "object",
    "properties": {
     "changed": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "domain": {
         "type": "string"
        },
        "org_id": {
         "type": "integer"
        },
        "name": {
         "type": "string"
        },
        "new_events": {
         "type": "array",
         "items": {
          "type": "object",
          "properties": {
           "type": {
            "type": "string"
           },
           "date": {
            "type": "string"
           },
           "summary": {
            "type": "string"
           },
           "source_url": {
            "type": "string"
           },
           "source_kind": {
            "type": "string"
           },
           "sec_items": {
            "type": "array",
            "items": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "next_cursor": {
      "type": "string"
     },
     "checked": {
      "type": "integer"
     },
     "unresolved": {
      "type": "array",
      "items": {}
     },
     "served_from": {
      "type": "string"
     },
     "not_checked": {
      "type": "array",
      "items": {}
     },
     "_usage": {
      "type": "object",
      "properties": {
       "units_charged": {
        "type": "string"
       },
       "units_month_to_date": {
        "type": "string"
       }
      }
     }
    }
   },
   "predicted_next_response": {
    "type": "object",
    "properties": {
     "experimental": {
      "type": "boolean"
     },
     "resolved": {
      "type": "boolean"
     },
     "org_id": {
      "type": "integer"
     },
     "model_version": {
      "type": "string"
     },
     "scored_on": {
      "type": "string"
     },
     "predictions": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "target": {
         "type": "string"
        },
        "label": {
         "type": "string"
        },
        "probability": {
         "type": "number"
        },
        "base_rate": {
         "type": "number"
        },
        "lift": {
         "type": "number"
        },
        "window_days": {
         "type": "integer"
        }
       }
      }
     },
     "coverage_note": {
      "type": "string"
     },
     "_usage": {
      "type": "object",
      "properties": {
       "units_charged": {
        "type": "string"
       },
       "units_month_to_date": {
        "type": "string"
       }
      }
     }
    }
   },
   "usage_response": {
    "type": "object",
    "properties": {
     "key_id": {
      "type": "string"
     },
     "tier": {
      "type": "string"
     },
     "units_month_to_date": {
      "type": "string"
     },
     "unit_allowance": {
      "type": "string"
     },
     "rate_per_minute": {
      "type": "string"
     },
     "indicative_usd_month_to_date": {
      "type": "string"
     }
    }
   },
   "events_for_icp_request": {
    "type": "object",
    "properties": {
     "industries": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "states": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "description": "Full state names as stored, e.g. 'California'."
     },
     "min_employees": {
      "type": "integer"
     },
     "max_employees": {
      "type": "integer"
     },
     "lookback_days": {
      "type": "integer",
      "default": 90
     },
     "min_signals": {
      "type": "integer",
      "default": 1
     },
     "limit": {
      "type": "integer",
      "default": 25,
      "maximum": 100
     },
     "cursor": {
      "type": "string"
     }
    }
   },
   "predicted_next_request": {
    "type": "object",
    "properties": {
     "domain": {
      "type": "string"
     },
     "org_id": {
      "type": "integer"
     }
    }
   },
   "watchlist_diff_request": {
    "type": "object",
    "required": [
     "domains"
    ],
    "properties": {
     "domains": {
      "type": "array",
      "items": {
       "type": "string"
      },
      "maxItems": 400
     },
     "since": {
      "type": "string",
      "format": "date",
      "description": "The `next_cursor` from your previous call."
     }
    }
   },
   "why_now_request": {
    "type": "object",
    "properties": {
     "domain": {
      "type": "string",
      "description": "Any spelling: bare, www., scheme, path."
     },
     "org_id": {
      "type": "integer"
     },
     "lookback_days": {
      "type": "integer",
      "default": 365,
      "minimum": 1,
      "maximum": 1825,
      "description": "Window for `evidence[]`, in days. Clamped to 1825. Does not affect `last_event`, which is never age-limited."
     }
    }
   },
   "error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "object",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       }
      }
     }
    }
   }
  }
 },
 "paths": {
  "/v1/agent/events_for_icp": {
   "post": {
    "operationId": "events_for_icp",
    "summary": "Ranked companies matching an ICP, each with evidence",
    "description": "Companies with recent launch-lane events matching an ICP filter. `min_signals` is the compound-signal filter and is applied AFTER evidence suppression, so a returned `signal_count` is always real.",
    "responses": {
     "200": {
      "description": "Success.",
      "headers": {
       "X-Fundz-Key-Id": {
        "schema": {
         "type": "string"
        },
        "description": "Non-secret handle for the key that served the call."
       },
       "X-Fundz-Units-Charged": {
        "schema": {
         "type": "string"
        },
        "description": "Units this call consumed. 1 for why_now, events_for_icp and predicted_next; 0.1 per company CHECKED for watchlist_diff."
       },
       "X-Fundz-Units-Month-To-Date": {
        "schema": {
         "type": "string"
        },
        "description": "Units consumed this calendar month, INCLUDING this call."
       },
       "X-Fundz-Units-Remaining": {
        "schema": {
         "type": "string"
        },
        "description": "Units left against the key's monthly allowance. Absent on a tier with no allowance."
       },
       "X-Fundz-Usage-Warning": {
        "schema": {
         "type": "string"
        },
        "description": "Present once 80% of the allowance is consumed. At 100% calls are refused with 402."
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/events_for_icp_response"
        },
        "example": {
         "results": [
          {
           "company": {
            "org_id": 210248,
            "name": "Superluminal Medicines",
            "domain": "www.superluminalrx.com",
            "name_agreement": 0
           },
           "signals": [
            {
             "type": "funding",
             "date": "2026-09-06",
             "summary": "Superluminal Medicines raised $60M Series B.",
             "source_url": "https://pulse2.com/superluminal-medicines-raises-60-million-series-b-led-by-bvf-partners/",
             "source_kind": "press_or_news"
            },
            {
             "type": "funding",
             "date": "2026-09-03",
             "summary": "Superluminal Medicines raised $65.5M Series B.",
             "source_url": "https://www.sec.gov/Archives/edgar/data/1989478/000198947826000001/primary_doc.xml",
             "source_kind": "sec_filing"
            },
            {
             "type": "funding",
             "date": "2026-09-03",
             "summary": "Superluminal Medicines raised $65.5M Series B.",
             "source_url": "https://www.prnewswire.com/news-releases/superluminal-medicines-announces-oversubscribed-60-million-series-b-financing-to-advance-lead-program-in-rare-genetic-forms-of-obesity-into-the-clinic-302868367.html",
             "source_kind": "press_or_news"
            }
           ],
           "signal_count": 3,
           "last_event_at": "2026-09-06",
           "why_now_short": "Superluminal Medicines raised $60M Series B."
          },
          {
           "company": {
            "org_id": 2155128,
            "name": "Hi Rasmus",
            "domain": "hirasmus.com",
            "name_agreement": 3
           },
           "signals": [
            {
             "type": "funding",
             "date": "2026-09-06",
             "summary": "Hi Rasmus raised $50M.",
             "source_url": "https://pulse2.com/hi-rasmus-raises-50-million-from-updata-partners-to-scale-autism-care-technology-platform/",
             "source_kind": "press_or_news"
            },
            {
             "type": "funding",
             "date": "2026-09-04",
             "summary": "Hi Rasmus secures a strategic minority investment to enhance product innovation and support growth. The investment amount remains undisclosed.",
             "source_url": "https://www.finsmes.com/2026/09/hi-rasmus-receives-investment.html",
             "source_kind": "press_or_news"
            }
           ],
           "signal_count": 2,
           "last_event_at": "2026-09-06",
           "why_now_short": "Hi Rasmus raised $50M."
          }
         ],
         "next_cursor": "2",
         "_usage": {
          "units_charged": "1",
          "units_month_to_date": "5"
         }
        }
       }
      }
     },
     "400": {
      "description": "The request body is not valid JSON, or a parameter is unusable.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "bad_request",
          "message": "The request body is not valid JSON, or a parameter is unusable."
         }
        }
       }
      }
     },
     "401": {
      "description": "No API key, or a key that is unknown, revoked or expired. A human must supply a new key; retrying will not help.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "unauthorized",
          "message": "No API key, or a key that is unknown, revoked or expired. A human must supply a new key; retrying will not help."
         }
        }
       }
      }
     },
     "402": {
      "description": "The key's monthly unit allowance is spent. Valid key, exhausted plan \u2014 a plan change, not a new key.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "allowance_exceeded",
          "message": "The key's monthly unit allowance is spent. Valid key, exhausted plan \u2014 a plan change, not a new key."
         }
        }
       }
      }
     },
     "403": {
      "description": "The tool exists but this key's tier may not call it.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "not_in_sandbox",
          "message": "The tool exists but this key's tier may not call it."
         }
        }
       }
      }
     },
     "404": {
      "description": "No such tool. Check the spelling before checking permissions.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "unknown_tool",
          "message": "No such tool. Check the spelling before checking permissions."
         }
        }
       }
      }
     },
     "429": {
      "description": "Per-minute rate limit exceeded. Back off and retry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "rate_limited",
          "message": "Per-minute rate limit exceeded. Back off and retry."
         }
        }
       }
      }
     },
     "500": {
      "description": "Our fault. The call is recorded at ZERO units \u2014 we do not bill for our own failures.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "internal_error",
          "message": "Our fault. The call is recorded at ZERO units \u2014 we do not bill for our own failures."
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/events_for_icp_request"
       },
       "example": {
        "min_signals": 2,
        "limit": 2
       }
      }
     }
    }
   }
  },
  "/v1/agent/predicted_next": {
   "post": {
    "operationId": "predicted_next",
    "summary": "FundzScore v3 forecasts (experimental)",
    "description": "Experimental. `base_rate` is the mean predicted probability across the scored population, NOT a validated historical event rate, and forward cohorts do not resolve until 2026-10-22 and 2027-02-19. Treat `lift` as a ranking aid, not evidence the model works.",
    "responses": {
     "200": {
      "description": "Success.",
      "headers": {
       "X-Fundz-Key-Id": {
        "schema": {
         "type": "string"
        },
        "description": "Non-secret handle for the key that served the call."
       },
       "X-Fundz-Units-Charged": {
        "schema": {
         "type": "string"
        },
        "description": "Units this call consumed. 1 for why_now, events_for_icp and predicted_next; 0.1 per company CHECKED for watchlist_diff."
       },
       "X-Fundz-Units-Month-To-Date": {
        "schema": {
         "type": "string"
        },
        "description": "Units consumed this calendar month, INCLUDING this call."
       },
       "X-Fundz-Units-Remaining": {
        "schema": {
         "type": "string"
        },
        "description": "Units left against the key's monthly allowance. Absent on a tier with no allowance."
       },
       "X-Fundz-Usage-Warning": {
        "schema": {
         "type": "string"
        },
        "description": "Present once 80% of the allowance is consumed. At 100% calls are refused with 402."
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/predicted_next_response"
        },
        "example": {
         "experimental": true,
         "resolved": true,
         "org_id": 141882,
         "model_version": "fundzscore_v3",
         "scored_on": "2026-09-07",
         "predictions": [
          {
           "target": "acquires",
           "label": "acquire another company",
           "probability": 0.5,
           "base_rate": 0.02216,
           "lift": 22.56,
           "window_days": 180
          },
          {
           "target": "funding",
           "label": "raise a new round",
           "probability": 0.12747,
           "base_rate": 0.02528,
           "lift": 5.04,
           "window_days": 180
          },
          {
           "target": "acquisition",
           "label": "be acquired",
           "probability": 0.00818,
           "base_rate": 0.0065,
           "lift": 1.26,
           "window_days": 90
          }
         ],
         "coverage_note": "Experimental. base_rate is the mean predicted probability across the scored population, not a validated historical event rate; forward cohorts resolve 2026-10-22 and 2027-02-19.",
         "_usage": {
          "units_charged": "1",
          "units_month_to_date": "6.2"
         }
        }
       }
      }
     },
     "400": {
      "description": "The request body is not valid JSON, or a parameter is unusable.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "bad_request",
          "message": "The request body is not valid JSON, or a parameter is unusable."
         }
        }
       }
      }
     },
     "401": {
      "description": "No API key, or a key that is unknown, revoked or expired. A human must supply a new key; retrying will not help.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "unauthorized",
          "message": "No API key, or a key that is unknown, revoked or expired. A human must supply a new key; retrying will not help."
         }
        }
       }
      }
     },
     "402": {
      "description": "The key's monthly unit allowance is spent. Valid key, exhausted plan \u2014 a plan change, not a new key.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "allowance_exceeded",
          "message": "The key's monthly unit allowance is spent. Valid key, exhausted plan \u2014 a plan change, not a new key."
         }
        }
       }
      }
     },
     "403": {
      "description": "The tool exists but this key's tier may not call it.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "not_in_sandbox",
          "message": "The tool exists but this key's tier may not call it."
         }
        }
       }
      }
     },
     "404": {
      "description": "No such tool. Check the spelling before checking permissions.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "unknown_tool",
          "message": "No such tool. Check the spelling before checking permissions."
         }
        }
       }
      }
     },
     "429": {
      "description": "Per-minute rate limit exceeded. Back off and retry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "rate_limited",
          "message": "Per-minute rate limit exceeded. Back off and retry."
         }
        }
       }
      }
     },
     "500": {
      "description": "Our fault. The call is recorded at ZERO units \u2014 we do not bill for our own failures.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "internal_error",
          "message": "Our fault. The call is recorded at ZERO units \u2014 we do not bill for our own failures."
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/predicted_next_request"
       },
       "example": {
        "domain": "snowflake.com"
       }
      }
     }
    }
   }
  },
  "/v1/agent/usage": {
   "get": {
    "operationId": "usage",
    "summary": "This key's month-to-date consumption",
    "description": "Units consumed this calendar month by the calling key.",
    "responses": {
     "200": {
      "description": "Success.",
      "headers": {
       "X-Fundz-Key-Id": {
        "schema": {
         "type": "string"
        },
        "description": "Non-secret handle for the key that served the call."
       },
       "X-Fundz-Units-Charged": {
        "schema": {
         "type": "string"
        },
        "description": "Units this call consumed. 1 for why_now, events_for_icp and predicted_next; 0.1 per company CHECKED for watchlist_diff."
       },
       "X-Fundz-Units-Month-To-Date": {
        "schema": {
         "type": "string"
        },
        "description": "Units consumed this calendar month, INCLUDING this call."
       },
       "X-Fundz-Units-Remaining": {
        "schema": {
         "type": "string"
        },
        "description": "Units left against the key's monthly allowance. Absent on a tier with no allowance."
       },
       "X-Fundz-Usage-Warning": {
        "schema": {
         "type": "string"
        },
        "description": "Present once 80% of the allowance is consumed. At 100% calls are refused with 402."
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/usage_response"
        },
        "example": {
         "key_id": "fundz_ak_live_7aIz46Yc",
         "tier": "sandbox",
         "units_month_to_date": "6.2",
         "unit_allowance": "100",
         "rate_per_minute": "30",
         "indicative_usd_month_to_date": "0.37"
        }
       }
      }
     },
     "400": {
      "description": "The request body is not valid JSON, or a parameter is unusable.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "bad_request",
          "message": "The request body is not valid JSON, or a parameter is unusable."
         }
        }
       }
      }
     },
     "401": {
      "description": "No API key, or a key that is unknown, revoked or expired. A human must supply a new key; retrying will not help.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "unauthorized",
          "message": "No API key, or a key that is unknown, revoked or expired. A human must supply a new key; retrying will not help."
         }
        }
       }
      }
     },
     "402": {
      "description": "The key's monthly unit allowance is spent. Valid key, exhausted plan \u2014 a plan change, not a new key.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "allowance_exceeded",
          "message": "The key's monthly unit allowance is spent. Valid key, exhausted plan \u2014 a plan change, not a new key."
         }
        }
       }
      }
     },
     "403": {
      "description": "The tool exists but this key's tier may not call it.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "not_in_sandbox",
          "message": "The tool exists but this key's tier may not call it."
         }
        }
       }
      }
     },
     "404": {
      "description": "No such tool. Check the spelling before checking permissions.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "unknown_tool",
          "message": "No such tool. Check the spelling before checking permissions."
         }
        }
       }
      }
     },
     "429": {
      "description": "Per-minute rate limit exceeded. Back off and retry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "rate_limited",
          "message": "Per-minute rate limit exceeded. Back off and retry."
         }
        }
       }
      }
     },
     "500": {
      "description": "Our fault. The call is recorded at ZERO units \u2014 we do not bill for our own failures.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "internal_error",
          "message": "Our fault. The call is recorded at ZERO units \u2014 we do not bill for our own failures."
         }
        }
       }
      }
     }
    }
   }
  },
  "/v1/agent/watchlist_diff": {
   "post": {
    "operationId": "watchlist_diff",
    "summary": "Only the companies in your book with new events since a cursor",
    "description": "The recurring primitive: send up to 400 domains and a cursor, get back only those with new evidence. Domains beyond the cap are returned in `not_checked` rather than silently dropped.",
    "responses": {
     "200": {
      "description": "Success.",
      "headers": {
       "X-Fundz-Key-Id": {
        "schema": {
         "type": "string"
        },
        "description": "Non-secret handle for the key that served the call."
       },
       "X-Fundz-Units-Charged": {
        "schema": {
         "type": "string"
        },
        "description": "Units this call consumed. 1 for why_now, events_for_icp and predicted_next; 0.1 per company CHECKED for watchlist_diff."
       },
       "X-Fundz-Units-Month-To-Date": {
        "schema": {
         "type": "string"
        },
        "description": "Units consumed this calendar month, INCLUDING this call."
       },
       "X-Fundz-Units-Remaining": {
        "schema": {
         "type": "string"
        },
        "description": "Units left against the key's monthly allowance. Absent on a tier with no allowance."
       },
       "X-Fundz-Usage-Warning": {
        "schema": {
         "type": "string"
        },
        "description": "Present once 80% of the allowance is consumed. At 100% calls are refused with 402."
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/watchlist_diff_response"
        },
        "example": {
         "changed": [
          {
           "domain": "figma.com",
           "org_id": 174227,
           "name": "FIGMA, INC.",
           "new_events": [
            {
             "type": "sec_8k",
             "date": "2026-04-14",
             "summary": "FIGMA, INC. changed directors or principal officers (8-K item 5.02).",
             "source_url": "https://www.sec.gov/Archives/edgar/data/1579878/000162828026025127/0001628280-26-025127-index.htm",
             "source_kind": "sec_filing",
             "sec_items": [
              "5.02"
             ]
            }
           ]
          },
          {
           "domain": "snowflake.com",
           "org_id": 141882,
           "name": "Snowflake",
           "new_events": [
            {
             "type": "funding",
             "date": "2026-02-02",
             "summary": "Snowflake raised $376.1M.",
             "source_url": "https://www.sec.gov/Archives/edgar/data/1640147/000164014726000001/primary_doc.xml",
             "source_kind": "sec_filing"
            },
            {
             "type": "sec_8k",
             "date": "2026-01-28",
             "summary": "Snowflake Inc. changed directors or principal officers (8-K item 5.02).",
             "source_url": "https://www.sec.gov/Archives/edgar/data/1640147/000162828026004606/0001628280-26-004606-index.htm",
             "source_kind": "sec_filing",
             "sec_items": [
              "5.02"
             ]
            }
           ]
          }
         ],
         "next_cursor": "2026-09-07",
         "checked": 2,
         "unresolved": [],
         "served_from": "live",
         "not_checked": [],
         "_usage": {
          "units_charged": "0.2",
          "units_month_to_date": "5.2"
         }
        }
       }
      }
     },
     "400": {
      "description": "The request body is not valid JSON, or a parameter is unusable.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "bad_request",
          "message": "The request body is not valid JSON, or a parameter is unusable."
         }
        }
       }
      }
     },
     "401": {
      "description": "No API key, or a key that is unknown, revoked or expired. A human must supply a new key; retrying will not help.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "unauthorized",
          "message": "No API key, or a key that is unknown, revoked or expired. A human must supply a new key; retrying will not help."
         }
        }
       }
      }
     },
     "402": {
      "description": "The key's monthly unit allowance is spent. Valid key, exhausted plan \u2014 a plan change, not a new key.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "allowance_exceeded",
          "message": "The key's monthly unit allowance is spent. Valid key, exhausted plan \u2014 a plan change, not a new key."
         }
        }
       }
      }
     },
     "403": {
      "description": "The tool exists but this key's tier may not call it.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "not_in_sandbox",
          "message": "The tool exists but this key's tier may not call it."
         }
        }
       }
      }
     },
     "404": {
      "description": "No such tool. Check the spelling before checking permissions.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "unknown_tool",
          "message": "No such tool. Check the spelling before checking permissions."
         }
        }
       }
      }
     },
     "429": {
      "description": "Per-minute rate limit exceeded. Back off and retry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "rate_limited",
          "message": "Per-minute rate limit exceeded. Back off and retry."
         }
        }
       }
      }
     },
     "500": {
      "description": "Our fault. The call is recorded at ZERO units \u2014 we do not bill for our own failures.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "internal_error",
          "message": "Our fault. The call is recorded at ZERO units \u2014 we do not bill for our own failures."
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/watchlist_diff_request"
       },
       "example": {
        "domains": [
         "figma.com",
         "snowflake.com"
        ],
        "since": "2026-01-01"
       }
      }
     }
    }
   }
  },
  "/v1/agent/why_now": {
   "post": {
    "operationId": "why_now",
    "summary": "Dated evidence for one company",
    "description": "Resolve a domain to a company and return its dated evidence, newest first. `resolved: false` means no company on the Fundz spine matches \u2014 different from a company with no recent events, which returns `resolved: true` and a `coverage_note`.",
    "responses": {
     "200": {
      "description": "Success.",
      "headers": {
       "X-Fundz-Key-Id": {
        "schema": {
         "type": "string"
        },
        "description": "Non-secret handle for the key that served the call."
       },
       "X-Fundz-Units-Charged": {
        "schema": {
         "type": "string"
        },
        "description": "Units this call consumed. 1 for why_now, events_for_icp and predicted_next; 0.1 per company CHECKED for watchlist_diff."
       },
       "X-Fundz-Units-Month-To-Date": {
        "schema": {
         "type": "string"
        },
        "description": "Units consumed this calendar month, INCLUDING this call."
       },
       "X-Fundz-Units-Remaining": {
        "schema": {
         "type": "string"
        },
        "description": "Units left against the key's monthly allowance. Absent on a tier with no allowance."
       },
       "X-Fundz-Usage-Warning": {
        "schema": {
         "type": "string"
        },
        "description": "Present once 80% of the allowance is consumed. At 100% calls are refused with 402."
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/why_now_response"
        },
        "example": {
         "company": {
          "org_id": 174227,
          "name": "Figma",
          "domain": "figma.com",
          "name_agreement": 3
         },
         "evidence": [
          {
           "type": "sec_8k",
           "date": "2026-04-14",
           "summary": "FIGMA, INC. changed directors or principal officers (8-K item 5.02).",
           "source_url": "https://www.sec.gov/Archives/edgar/data/1579878/000162828026025127/0001628280-26-025127-index.htm",
           "source_kind": "sec_filing",
           "sec_items": [
            "5.02"
           ]
          }
         ],
         "last_event": {
          "type": "sec_8k",
          "date": "2026-04-14",
          "summary": "FIGMA, INC. changed directors or principal officers (8-K item 5.02).",
          "source_url": "https://www.sec.gov/Archives/edgar/data/1579878/000162828026025127/0001628280-26-025127-index.htm",
          "source_kind": "sec_filing",
          "sec_items": [
           "5.02"
          ],
          "within_lookback": true
         },
         "last_event_at": "2026-04-14",
         "narrative": null,
         "coverage_note": null,
         "resolved": true,
         "_usage": {
          "units_charged": "1",
          "units_month_to_date": "1"
         }
        }
       }
      }
     },
     "400": {
      "description": "The request body is not valid JSON, or a parameter is unusable.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "bad_request",
          "message": "The request body is not valid JSON, or a parameter is unusable."
         }
        }
       }
      }
     },
     "401": {
      "description": "No API key, or a key that is unknown, revoked or expired. A human must supply a new key; retrying will not help.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "unauthorized",
          "message": "No API key, or a key that is unknown, revoked or expired. A human must supply a new key; retrying will not help."
         }
        }
       }
      }
     },
     "402": {
      "description": "The key's monthly unit allowance is spent. Valid key, exhausted plan \u2014 a plan change, not a new key.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "allowance_exceeded",
          "message": "The key's monthly unit allowance is spent. Valid key, exhausted plan \u2014 a plan change, not a new key."
         }
        }
       }
      }
     },
     "403": {
      "description": "The tool exists but this key's tier may not call it.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "not_in_sandbox",
          "message": "The tool exists but this key's tier may not call it."
         }
        }
       }
      }
     },
     "404": {
      "description": "No such tool. Check the spelling before checking permissions.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "unknown_tool",
          "message": "No such tool. Check the spelling before checking permissions."
         }
        }
       }
      }
     },
     "429": {
      "description": "Per-minute rate limit exceeded. Back off and retry.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "rate_limited",
          "message": "Per-minute rate limit exceeded. Back off and retry."
         }
        }
       }
      }
     },
     "500": {
      "description": "Our fault. The call is recorded at ZERO units \u2014 we do not bill for our own failures.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/error"
        },
        "example": {
         "error": {
          "code": "internal_error",
          "message": "Our fault. The call is recorded at ZERO units \u2014 we do not bill for our own failures."
         }
        }
       }
      }
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/why_now_request"
       },
       "example": {
        "domain": "figma.com"
       }
      }
     }
    }
   }
  }
 },
 "x-stub-tools": {
  "lookalikes_after_event": {
   "status": "not implemented",
   "description": "Companies resembling one that just had an event. Documented so integrators know the shape is coming; it is NOT callable and returns 404 today."
  }
 }
}