{
  "components": {
    "schemas": {
      "ComparisonResult": {
        "examples": [
          {
            "actual_holdings_change": "cannot_be_inferred",
            "answer": "The aggregate reported range's lower and upper bounds both increased, but actual holdings change cannot be inferred.",
            "answer_basis": "Each bound is the sum of matching Schedule A common-stock value-band bounds.",
            "calculation": {
              "difference": {
                "minimum_usd": 359003,
                "upper_floor_usd": 785000
              },
              "from": {
                "minimum_usd": 851005,
                "upper_floor_usd": 1765000,
                "year": 2024
              },
              "to": {
                "minimum_usd": 1210008,
                "upper_floor_usd": 2550000,
                "year": 2025
              }
            },
            "conservative_range_relation": "overlapping_reported_ranges",
            "directly_comparable": false,
            "evidence": [
              {
                "id": "asset:2024:000231",
                "url": "https://www.rokhanna.money/api/v1/evidence?id=asset:2024:000231",
                "year": 2024
              }
            ],
            "from_year": 2024,
            "limitations": [
              "Reported values are statutory ranges, not exact market values or share counts."
            ],
            "reported_bounds_direction": "both_increased",
            "to_year": 2025
          }
        ],
        "properties": {
          "actual_holdings_change": {
            "enum": [
              "cannot_be_inferred"
            ],
            "type": "string"
          },
          "answer": {
            "description": "Concise answer that preserves the comparison warning.",
            "type": "string"
          },
          "answer_basis": {
            "type": "string"
          },
          "calculation": {
            "description": "Input bounds and arithmetic differences used for the answer.",
            "type": "object"
          },
          "conservative_range_relation": {
            "type": "string"
          },
          "directly_comparable": {
            "type": "boolean"
          },
          "evidence": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "from_year": {
            "type": "integer"
          },
          "limitations": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "lower_bound_direction": {
            "enum": [
              "increased",
              "decreased",
              "unchanged",
              "not_comparable"
            ],
            "type": "string"
          },
          "reported_bounds_direction": {
            "type": "string"
          },
          "to_year": {
            "type": "integer"
          },
          "upper_bound_direction": {
            "enum": [
              "increased",
              "decreased",
              "unchanged",
              "not_comparable"
            ],
            "type": "string"
          },
          "warnings": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "from_year",
          "to_year",
          "answer",
          "answer_basis",
          "reported_bounds_direction",
          "conservative_range_relation",
          "directly_comparable",
          "actual_holdings_change",
          "calculation",
          "limitations",
          "evidence"
        ],
        "type": "object"
      },
      "EvidenceRecord": {
        "properties": {
          "cls": {
            "description": "Normalized asset class.",
            "type": [
              "string",
              "null"
            ]
          },
          "desc": {
            "description": "Plain-language instrument description.",
            "type": [
              "string",
              "null"
            ]
          },
          "doc": {
            "description": "Source document ID.",
            "type": "string"
          },
          "evidence_path": {
            "description": "Stable lookup path for the evidence record.",
            "type": "string"
          },
          "house_filing_id": {
            "description": "House Clerk filing identifier when identified.",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Deterministic dataset record ID.",
            "type": "string"
          },
          "issuer": {
            "description": "Reviewed issuer identity when available; separate from the raw reported name.",
            "type": [
              "object",
              "null"
            ]
          },
          "label": {
            "description": "Printed filing page label.",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "description": "Reported asset or security name.",
            "type": "string"
          },
          "official_source_url": {
            "description": "Original House Clerk PDF URL when identified.",
            "format": "uri",
            "type": [
              "string",
              "null"
            ]
          },
          "owner": {
            "description": "Owner code printed on the filing.",
            "type": [
              "string",
              "null"
            ]
          },
          "page": {
            "description": "Page position in the filing-year collection.",
            "type": "integer"
          },
          "source_document_mirror_url": {
            "description": "Project-hosted byte-preserving mirror of the source disclosure PDF.",
            "format": "uri",
            "type": "string"
          },
          "source_document_url": {
            "description": "Source disclosure PDF; present on lookup/search responses.",
            "format": "uri",
            "type": "string"
          },
          "source_page_url": {
            "description": "Explorer URL for the filed page; present on lookup/search responses.",
            "format": "uri",
            "type": "string"
          },
          "url": {
            "description": "Absolute evidence lookup URL; present on lookup/search responses.",
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "id",
          "doc",
          "page",
          "name"
        ],
        "type": "object"
      },
      "IssuerIdentity": {
        "properties": {
          "aliases": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "comparison_url_template": {
            "type": "string"
          },
          "data_url": {
            "format": "uri",
            "type": "string"
          },
          "featured_comparison_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "text_url": {
            "format": "uri",
            "type": "string"
          },
          "ticker": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "id",
          "slug",
          "name",
          "aliases",
          "url",
          "data_url",
          "text_url",
          "comparison_url_template"
        ],
        "type": "object"
      },
      "IssuerResponse": {
        "properties": {
          "answer": {
            "description": "Present on comparison responses.",
            "type": [
              "string",
              "array"
            ]
          },
          "canonical_url": {
            "format": "uri",
            "type": "string"
          },
          "comparisons": {
            "items": {
              "$ref": "#/components/schemas/ComparisonResult"
            },
            "type": "array"
          },
          "dataset_version": {
            "format": "date",
            "type": "string"
          },
          "described_by": {
            "format": "uri",
            "type": "string"
          },
          "entity": {
            "$ref": "#/components/schemas/IssuerIdentity"
          },
          "evidence": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "interpretation": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "limitations": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "links": {
            "type": "object"
          },
          "methodology_url": {
            "format": "uri",
            "type": "string"
          },
          "schema_version": {
            "type": "string"
          },
          "scope": {
            "type": "string"
          },
          "years": {
            "items": {
              "properties": {
                "holding_count": {
                  "type": "integer"
                },
                "records": {
                  "items": {
                    "$ref": "#/components/schemas/EvidenceRecord"
                  },
                  "type": "array"
                },
                "reported_value": {
                  "$ref": "#/components/schemas/ReportedValue"
                },
                "year": {
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "schema_version",
          "dataset_version",
          "generated_at",
          "canonical_url",
          "described_by",
          "entity",
          "years",
          "comparisons",
          "links",
          "interpretation"
        ],
        "type": "object"
      },
      "ReportedValue": {
        "properties": {
          "calculated_upper_floor_usd": {
            "type": [
              "integer",
              "null"
            ]
          },
          "display": {
            "type": "string"
          },
          "maximum_usd": {
            "description": "Null when one or more bands have no upper bound.",
            "type": [
              "integer",
              "null"
            ]
          },
          "minimum_usd": {
            "type": [
              "integer",
              "null"
            ]
          },
          "open_ended": {
            "type": "boolean"
          },
          "open_ended_entries": {
            "type": "integer"
          }
        },
        "required": [
          "minimum_usd",
          "calculated_upper_floor_usd",
          "maximum_usd",
          "display"
        ],
        "type": "object"
      },
      "SearchResults": {
        "properties": {
          "kind": {
            "enum": [
              "assets",
              "transactions"
            ],
            "type": "string"
          },
          "next_offset": {
            "type": [
              "integer",
              "null"
            ]
          },
          "results": {
            "items": {
              "$ref": "#/components/schemas/EvidenceRecord"
            },
            "type": "array"
          },
          "returned": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "year": {
            "type": "integer"
          }
        },
        "required": [
          "year",
          "kind",
          "total",
          "returned",
          "results"
        ],
        "type": "object"
      },
      "YearFacts": {
        "properties": {
          "caveats": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "comparability": {
            "description": "Machine-readable warning status for cross-year holdings interpretation.",
            "type": "object"
          },
          "dataset_version": {
            "format": "date",
            "type": "string"
          },
          "filing_type": {
            "type": "string"
          },
          "metrics": {
            "type": "object"
          },
          "schema_version": {
            "type": "string"
          },
          "sources": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "year": {
            "type": "integer"
          }
        },
        "required": [
          "schema_version",
          "dataset_version",
          "year",
          "metrics",
          "sources",
          "caveats"
        ],
        "type": "object"
      }
    }
  },
  "info": {
    "description": "Read-only, source-linked access to Ro Khanna financial-disclosure transcriptions. Statutory ranges are not exact values.",
    "license": {
      "name": "CC0-1.0 with source-material notice",
      "url": "https://github.com/kanetronv2/khanna-disclosure-explorer/blob/main/DATA_LICENSE.md"
    },
    "title": "Khanna Disclosure Explorer API",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/compare": {
      "get": {
        "deprecated": true,
        "description": "Use /issuers/{slug}/comparisons/{range}.json for stable reviewed-issuer resources. This endpoint also supports unregistered name searches and 2–11 filing years.",
        "operationId": "compareIssuerHoldingsLegacy",
        "parameters": [
          {
            "example": "NVDA",
            "in": "query",
            "name": "entity",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "example": "2024,2025",
            "in": "query",
            "name": "years",
            "required": false,
            "schema": {
              "default": "2024,2025",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "format",
            "required": false,
            "schema": {
              "enum": [
                "text",
                "txt"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IssuerResponse"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Source-linked issuer comparison"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Invalid entity or filing years"
          }
        },
        "summary": "Compatibility query endpoint for issuer comparisons"
      }
    },
    "/evidence": {
      "get": {
        "operationId": "getEvidence",
        "parameters": [
          {
            "in": "query",
            "name": "id",
            "required": true,
            "schema": {
              "pattern": "^(asset|transaction):20[0-9]{2}:[0-9]{6}$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EvidenceRecord"
                }
              }
            },
            "description": "Evidence record"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Unknown record"
          }
        },
        "summary": "Resolve a deterministic asset or transaction ID"
      }
    },
    "/issuers.json": {
      "get": {
        "operationId": "getIssuers",
        "responses": {
          "200": {
            "description": "Issuer index"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Resource not found"
          }
        },
        "summary": "List reviewed issuer identities and API resources"
      }
    },
    "/issuers/{slug}.json": {
      "get": {
        "operationId": "getIssuer",
        "parameters": [
          {
            "description": "Reviewed lowercase issuer slug from /issuers.json.",
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IssuerResponse"
                }
              }
            },
            "description": "Source-linked issuer holdings and comparisons",
            "links": {
              "featuredComparison": {
                "operationId": "getIssuerComparison",
                "parameters": {
                  "range": "2024-2025",
                  "slug": "$request.path.slug"
                }
              }
            }
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Resource not found"
          }
        },
        "summary": "Get source-linked annual holdings for one reviewed issuer"
      }
    },
    "/issuers/{slug}.txt": {
      "get": {
        "operationId": "getIssuerText",
        "parameters": [
          {
            "description": "Reviewed lowercase issuer slug from /issuers.json.",
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Plain-text answer, calculation, limitations, and evidence URLs"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Resource not found"
          }
        },
        "summary": "Get a compact text representation of one issuer resource"
      }
    },
    "/issuers/{slug}/comparisons/{range}.json": {
      "get": {
        "operationId": "getIssuerComparison",
        "parameters": [
          {
            "description": "Reviewed lowercase issuer slug from /issuers.json.",
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
              "type": "string"
            }
          },
          {
            "description": "Two filing years separated by a hyphen.",
            "example": "2024-2025",
            "in": "path",
            "name": "range",
            "required": true,
            "schema": {
              "pattern": "^20[0-9]{2}-20[0-9]{2}$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IssuerResponse"
                }
              }
            },
            "description": "Source-linked issuer holdings and comparisons",
            "links": {
              "issuer": {
                "operationId": "getIssuer",
                "parameters": {
                  "slug": "$request.path.slug"
                }
              },
              "text": {
                "operationId": "getIssuerComparisonText",
                "parameters": {
                  "range": "$request.path.range",
                  "slug": "$request.path.slug"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Invalid filing years"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Resource not found"
          }
        },
        "summary": "Compare one reviewed issuer across two filing years"
      }
    },
    "/issuers/{slug}/comparisons/{range}.txt": {
      "get": {
        "operationId": "getIssuerComparisonText",
        "parameters": [
          {
            "description": "Reviewed lowercase issuer slug from /issuers.json.",
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
              "type": "string"
            }
          },
          {
            "description": "Two filing years separated by a hyphen.",
            "example": "2024-2025",
            "in": "path",
            "name": "range",
            "required": true,
            "schema": {
              "pattern": "^20[0-9]{2}-20[0-9]{2}$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Plain-text answer, calculation, limitations, and evidence URLs"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Invalid filing years"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Resource not found"
          }
        },
        "summary": "Get an answer-ready text issuer comparison"
      }
    },
    "/search": {
      "get": {
        "operationId": "searchRecords",
        "parameters": [
          {
            "in": "query",
            "name": "year",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "kind",
            "required": true,
            "schema": {
              "enum": [
                "assets",
                "transactions"
              ],
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "owner",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "class",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "type",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 25,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "default": 0,
              "minimum": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResults"
                }
              }
            },
            "description": "Search results"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Invalid query"
          }
        },
        "summary": "Search assets or transactions within one year"
      }
    },
    "/years.json": {
      "get": {
        "operationId": "getYears",
        "responses": {
          "200": {
            "description": "Year index"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Resource not found"
          }
        },
        "summary": "List filing years"
      }
    },
    "/years/{year}/summary.json": {
      "get": {
        "operationId": "getYearSummary",
        "parameters": [
          {
            "in": "path",
            "name": "year",
            "required": true,
            "schema": {
              "maximum": 2026,
              "minimum": 2016,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/YearFacts"
                }
              }
            },
            "description": "Year facts"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Resource not found"
          }
        },
        "summary": "Get calculated facts and provenance for one year"
      }
    },
    "/years/{year}/{kind}.json": {
      "get": {
        "operationId": "getYearRecords",
        "parameters": [
          {
            "in": "path",
            "name": "year",
            "required": true,
            "schema": {
              "maximum": 2026,
              "minimum": 2016,
              "type": "integer"
            }
          },
          {
            "in": "path",
            "name": "kind",
            "required": true,
            "schema": {
              "enum": [
                "assets",
                "transactions",
                "pages"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/EvidenceRecord"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Record array"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Resource not found"
          }
        },
        "summary": "Download all records of one kind for a year"
      }
    }
  },
  "security": [],
  "servers": [
    {
      "url": "https://www.rokhanna.money/api/v1"
    }
  ]
}