{
  "openapi": "3.1.0",
  "info": {
    "title": "YC Founder Credentials API",
    "version": "1.0.0",
    "description": "Privacy-safe derived data for YC companies from Summer 2022 onward. Read /metadata.md before analysis. False signal values mean not disclosed under the classifier, not proven absent."
  },
  "servers": [
    {
      "url": "https://yc-founders.sherpa-core.com"
    }
  ],
  "security": [],
  "paths": {
    "/healthz": {
      "get": {
        "summary": "Check service health and loaded row counts",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "The service is ready",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          }
        }
      }
    },
    "/metadata.md": {
      "get": {
        "summary": "Read dataset definitions and evidence limits",
        "operationId": "getMetadata",
        "responses": {
          "200": {
            "description": "Markdown metadata",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "summary": "Get exact report totals and signal counts",
        "operationId": "getStats",
        "responses": {
          "200": {
            "description": "Aggregate statistics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/founders": {
      "get": {
        "summary": "List current active founder-company ties",
        "description": "Returns paginated derived founder data without biography text or email data.",
        "operationId": "listFounders",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Offset"
          },
          {
            "$ref": "#/components/parameters/Batch"
          },
          {
            "$ref": "#/components/parameters/AITagged"
          },
          {
            "$ref": "#/components/parameters/ProfileMatchState"
          },
          {
            "$ref": "#/components/parameters/Search"
          },
          {
            "name": "signal",
            "in": "query",
            "description": "Return founder rows where this disclosed signal is true.",
            "schema": {
              "$ref": "#/components/schemas/SignalName"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Founder rows and pagination metadata",
            "headers": {
              "X-Total-Count": {
                "description": "Total rows after filters",
                "schema": {
                  "type": "integer"
                }
              },
              "Link": {
                "description": "Previous and next page links when available",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FounderList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/v1/companies": {
      "get": {
        "summary": "List AI-era YC companies",
        "operationId": "listCompanies",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Offset"
          },
          {
            "$ref": "#/components/parameters/Batch"
          },
          {
            "$ref": "#/components/parameters/AITagged"
          },
          {
            "$ref": "#/components/parameters/ProfileMatchState"
          },
          {
            "$ref": "#/components/parameters/Search"
          }
        ],
        "responses": {
          "200": {
            "description": "Company rows and pagination metadata",
            "headers": {
              "X-Total-Count": {
                "description": "Total rows after filters",
                "schema": {
                  "type": "integer"
                }
              },
              "Link": {
                "description": "Previous and next page links when available",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompanyList"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/report.pdf": {
      "get": {
        "summary": "Open the two-page report",
        "operationId": "getReport",
        "responses": {
          "200": {
            "description": "Tagged PDF with embedded data attachments",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "contentEncoding": "binary"
                }
              }
            }
          }
        }
      }
    },
    "/data/founders.csv": {
      "get": {
        "summary": "Download all founder-company rows",
        "operationId": "downloadFounders",
        "responses": {
          "200": {
            "description": "Founder CSV",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/data/companies.csv": {
      "get": {
        "summary": "Download all company rows",
        "operationId": "downloadCompanies",
        "responses": {
          "200": {
            "description": "Company CSV",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Limit": {
        "name": "limit",
        "in": "query",
        "description": "Rows to return. The maximum is 1000.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000,
          "default": 100
        }
      },
      "Offset": {
        "name": "offset",
        "in": "query",
        "description": "Zero-based row offset.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "default": 0
        }
      },
      "Batch": {
        "name": "batch",
        "in": "query",
        "description": "Exact YC batch label, such as Summer 2025.",
        "schema": {
          "type": "string"
        }
      },
      "AITagged": {
        "name": "ai_tagged",
        "in": "query",
        "description": "Filter by the frozen YC source-tag rule.",
        "schema": {
          "type": "boolean"
        }
      },
      "ProfileMatchState": {
        "name": "profile_match_state",
        "in": "query",
        "description": "Known matches and known non-matches are separate from unknown records.",
        "schema": {
          "$ref": "#/components/schemas/ProfileMatchState"
        }
      },
      "Search": {
        "name": "q",
        "in": "query",
        "description": "Case-insensitive name search.",
        "schema": {
          "type": "string",
          "minLength": 1
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid filter or pagination value",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "ProfileMatchState": {
        "type": "string",
        "enum": [
          "matches_profile",
          "does_not_match_profile",
          "unknown"
        ]
      },
      "SignalName": {
        "type": "string",
        "enum": [
          "ivy_league_present",
          "other_selective_university_present",
          "advanced_degree_present",
          "major_technology_employer_present",
          "major_finance_or_consulting_employer_present",
          "internship_present",
          "research_present",
          "publication_present",
          "patent_present",
          "open_source_present",
          "award_present",
          "prior_startup_present",
          "prior_exit_present"
        ]
      },
      "Health": {
        "type": "object",
        "required": [
          "status",
          "founders",
          "companies"
        ],
        "properties": {
          "status": {
            "const": "ok"
          },
          "founders": {
            "type": "integer",
            "const": 4545
          },
          "companies": {
            "type": "integer",
            "const": 2506
          }
        }
      },
      "Pagination": {
        "type": "object",
        "required": [
          "limit",
          "offset",
          "count",
          "total"
        ],
        "properties": {
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "count": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          }
        }
      },
      "Founder": {
        "type": "object",
        "required": [
          "founder_company_key",
          "startup_id",
          "company_name",
          "batch",
          "ai_tagged",
          "founder_name",
          "biography_present",
          "biography_source_url",
          "biography_checked_at",
          "profile_match_state",
          "selective_university_present"
        ],
        "properties": {
          "founder_company_key": {
            "type": "string"
          },
          "startup_id": {
            "type": "string"
          },
          "company_name": {
            "type": "string"
          },
          "batch": {
            "type": "string"
          },
          "ai_tagged": {
            "type": "boolean"
          },
          "founder_name": {
            "type": "string"
          },
          "biography_present": {
            "type": "boolean"
          },
          "biography_source_url": {
            "type": "string",
            "format": "uri"
          },
          "biography_checked_at": {
            "type": "string"
          },
          "profile_match_state": {
            "$ref": "#/components/schemas/ProfileMatchState"
          },
          "selective_university_present": {
            "type": "boolean"
          },
          "ivy_league_present": {
            "type": "boolean"
          },
          "other_selective_university_present": {
            "type": "boolean"
          },
          "advanced_degree_present": {
            "type": "boolean"
          },
          "major_technology_employer_present": {
            "type": "boolean"
          },
          "major_finance_or_consulting_employer_present": {
            "type": "boolean"
          },
          "internship_present": {
            "type": "boolean"
          },
          "research_present": {
            "type": "boolean"
          },
          "publication_present": {
            "type": "boolean"
          },
          "patent_present": {
            "type": "boolean"
          },
          "open_source_present": {
            "type": "boolean"
          },
          "award_present": {
            "type": "boolean"
          },
          "prior_startup_present": {
            "type": "boolean"
          },
          "prior_exit_present": {
            "type": "boolean"
          }
        }
      },
      "Company": {
        "type": "object",
        "required": [
          "startup_id",
          "company_name",
          "batch",
          "ai_tagged",
          "source_url",
          "active_founder_count",
          "founders_with_biography",
          "profile_match_founder_count",
          "profile_match_state"
        ],
        "properties": {
          "startup_id": {
            "type": "string"
          },
          "company_name": {
            "type": "string"
          },
          "batch": {
            "type": "string"
          },
          "ai_tagged": {
            "type": "boolean"
          },
          "source_url": {
            "type": "string",
            "format": "uri"
          },
          "active_founder_count": {
            "type": "integer"
          },
          "founders_with_biography": {
            "type": "integer"
          },
          "profile_match_founder_count": {
            "type": "integer"
          },
          "profile_match_state": {
            "$ref": "#/components/schemas/ProfileMatchState"
          }
        }
      },
      "FounderList": {
        "type": "object",
        "required": [
          "data",
          "pagination"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Founder"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "CompanyList": {
        "type": "object",
        "required": [
          "data",
          "pagination"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Company"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}