{
  "openapi": "3.1.0",
  "info": {
    "title": "POPVOX partner congressional data API",
    "version": "0.2.0",
    "description": "Partner pilot. Read-only public evidence with provisional relationships. API keys require named Hub ownership and explicit dataset approval. No current-staff guarantee or reselling authorization. See https://popvox.com/data/api/ for access, source limitations and pagination."
  },
  "servers": [
    {
      "url": "https://popvox.com/api/data",
      "description": "POPVOX partner API; approved dataset scopes and a bearer key required"
    }
  ],
  "security": [
    {
      "partnerKey": []
    }
  ],
  "paths": {
    "/v1/historical-members": {
      "get": {
        "operationId": "list_historical_members",
        "summary": "List Congress.gov Member observations",
        "description": "Requires the member-history:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nCongress.gov coverage is primarily 1973 onward, including earlier service of some Members serving then; this is not the complete Bioguide roster.\n\nService dates have year precision. Missing end years do not establish current service. Member-level party, state and district must not be assigned retrospectively to service observations.\n\nExact Bioguide crosswalks identify a Member; they do not verify staff employment or service dates. CongressLink registry and snapshot identifiers are preserved.\n\nSource pages were retrieved sequentially, not as an atomic upstream snapshot. Individual Member detail endpoints were not collected.",
        "x-dataset-scope": "member-history:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "name_as_reported",
                "bioguide_id",
                "member_observation_id"
              ],
              "default": "name_as_reported"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "historical_member_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "bioguide_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z][0-9]{6}$"
            }
          },
          {
            "name": "state_as_reported",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case/accent-insensitive literal substring search in name_as_reported, bioguide_id",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "member_observation_id",
                              "historical_member_id",
                              "bioguide_id",
                              "name_as_reported",
                              "state_as_reported",
                              "district_as_reported",
                              "party_as_reported",
                              "source_updated_at_as_reported",
                              "retrieved_at",
                              "import_id",
                              "source_content_sha256",
                              "source_url",
                              "registry_links",
                              "registry_match_status"
                            ],
                            "properties": {
                              "member_observation_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "historical_member_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "bioguide_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "name_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Immutable source spelling and capitalization."
                              },
                              "state_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "district_as_reported": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "party_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_updated_at_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "retrieved_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_content_sha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "registry_links": {
                                "type": [
                                  "object",
                                  "array",
                                  "null"
                                ],
                                "description": "Exact Bioguide crosswalks to archived CongressLink registry/member snapshots. Numeric GPI IDs are decimal strings; array order is not meaningful. Identity matches do not establish service dates."
                              },
                              "registry_match_status": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/historical-service": {
      "get": {
        "operationId": "list_historical_service",
        "summary": "List year-precision Member service observations",
        "description": "Requires the member-history:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nCongress.gov coverage is primarily 1973 onward, including earlier service of some Members serving then; this is not the complete Bioguide roster.\n\nService dates have year precision. Missing end years do not establish current service. Member-level party, state and district must not be assigned retrospectively to service observations.\n\nExact Bioguide crosswalks identify a Member; they do not verify staff employment or service dates. CongressLink registry and snapshot identifiers are preserved.\n\nSource pages were retrieved sequentially, not as an atomic upstream snapshot. Individual Member detail endpoints were not collected.",
        "x-dataset-scope": "member-history:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "start_year",
                "end_year",
                "service_observation_id"
              ],
              "default": "service_observation_id"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "historical_member_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "bioguide_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z][0-9]{6}$"
            }
          },
          {
            "name": "chamber",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "House",
                "Senate"
              ]
            }
          },
          {
            "name": "start_year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1700,
              "maximum": 2200
            }
          },
          {
            "name": "end_year",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1700,
              "maximum": 2200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "service_observation_id",
                              "member_observation_id",
                              "historical_member_id",
                              "bioguide_id",
                              "source_ordinal",
                              "chamber_as_reported",
                              "chamber",
                              "start_year",
                              "end_year",
                              "date_precision",
                              "import_id",
                              "source_url",
                              "retrieved_at",
                              "starts_on",
                              "ends_on",
                              "is_current",
                              "date_basis"
                            ],
                            "properties": {
                              "service_observation_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_observation_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "historical_member_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "bioguide_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_ordinal": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "chamber_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "chamber": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "start_year": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "Source year, not an exact start date."
                              },
                              "end_year": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "Source year; null does not establish current service."
                              },
                              "date_precision": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "retrieved_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "starts_on": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "ends_on": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "is_current": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "date_basis": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/historical-sources": {
      "get": {
        "operationId": "list_historical_sources",
        "summary": "List Congress.gov retrieval receipts",
        "description": "Requires the member-history:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nCongress.gov coverage is primarily 1973 onward, including earlier service of some Members serving then; this is not the complete Bioguide roster.\n\nService dates have year precision. Missing end years do not establish current service. Member-level party, state and district must not be assigned retrospectively to service observations.\n\nExact Bioguide crosswalks identify a Member; they do not verify staff employment or service dates. CongressLink registry and snapshot identifiers are preserved.\n\nSource pages were retrieved sequentially, not as an atomic upstream snapshot. Individual Member detail endpoints were not collected.",
        "x-dataset-scope": "member-history:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "source_id",
                "retrieved_at"
              ],
              "default": "source_id"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "source_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "source_id",
                              "dataset_id",
                              "import_id",
                              "publisher",
                              "source_url",
                              "retrieved_at",
                              "response_sha256",
                              "timestamp_basis"
                            ],
                            "properties": {
                              "source_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "dataset_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "publisher": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "retrieved_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "response_sha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "timestamp_basis": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Meaning of source_timestamp: extraction_generated_at, proxy_retrieved_at, or derived_build_time."
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/meetings": {
      "get": {
        "operationId": "list_meetings",
        "summary": "List publisher event listings",
        "description": "Requires the hearings:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nCoverage is partial and publishing schedules vary by committee. A listing does not establish that an event occurred or that a listed witness attended.\n\nmeeting_id identifies a publisher event, not a reconciled event across publishers. Preserve source_namespace and source_event_id.\n\nWitness identifiers are provisional appearance identities. Name equality does not establish that two appearances belong to the same person.\n\nDocument and video URLs are source links, not a guarantee of downloaded, parsed or searchable content. GovInfo dateIssued is a source assertion, not a verified online release date or substitute for held dates.\n\nCommittee code matches are provisional and do not establish Member or staff attendance. Document links without appearance_id must not be attributed to every witness.\n\nExternal document enrichment includes only current source_linked claims; candidate, unmatched and retracted claims are excluded.",
        "x-dataset-scope": "hearings:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "start_date",
                "title",
                "meeting_version_id"
              ],
              "default": "start_date"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "meeting_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "chamber",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "House",
                "Senate",
                "Joint"
              ]
            }
          },
          {
            "name": "congress",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 999
            }
          },
          {
            "name": "event_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "Hearing",
                "Markup",
                "Business Meeting",
                "Other"
              ]
            }
          },
          {
            "name": "source_namespace",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case/accent-insensitive literal substring search in title, hearing_topic, description",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 120
            }
          },
          {
            "name": "event_from",
            "in": "query",
            "required": false,
            "description": "Inclusive source event-date bound. Does not establish attendance or that an event occurred; excludes undated records.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "event_to",
            "in": "query",
            "required": false,
            "description": "Inclusive source event-date bound. Does not establish attendance or that an event occurred; excludes undated records.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "meeting_version_id",
                              "meeting_id",
                              "import_id",
                              "source_namespace",
                              "source_event_id",
                              "chamber",
                              "congress",
                              "event_type",
                              "type_as_reported",
                              "title",
                              "hearing_topic",
                              "description",
                              "start_date",
                              "start_time",
                              "timezone",
                              "status_as_reported",
                              "source_url",
                              "source_fetched_at",
                              "source_sha256",
                              "identity_basis"
                            ],
                            "properties": {
                              "meeting_version_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "meeting_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Stable publisher event ID, not yet a reconciled event across publishers."
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_namespace": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_event_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "chamber": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "congress": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "event_type": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "type_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "title": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "hearing_topic": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "description": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "start_date": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "start_time": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "timezone": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "status_as_reported": {
                                "type": [
                                  "object",
                                  "array",
                                  "string",
                                  "null"
                                ],
                                "description": "Publisher status preserved as a JSON string, array, object or null; not confirmation that the event occurred."
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_fetched_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_sha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "identity_basis": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/meeting-committees": {
      "get": {
        "operationId": "list_meeting_committees",
        "summary": "List sourced meeting committee links",
        "description": "Requires the hearings:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nCoverage is partial and publishing schedules vary by committee. A listing does not establish that an event occurred or that a listed witness attended.\n\nmeeting_id identifies a publisher event, not a reconciled event across publishers. Preserve source_namespace and source_event_id.\n\nWitness identifiers are provisional appearance identities. Name equality does not establish that two appearances belong to the same person.\n\nDocument and video URLs are source links, not a guarantee of downloaded, parsed or searchable content. GovInfo dateIssued is a source assertion, not a verified online release date or substitute for held dates.\n\nCommittee code matches are provisional and do not establish Member or staff attendance. Document links without appearance_id must not be attributed to every witness.\n\nExternal document enrichment includes only current source_linked claims; candidate, unmatched and retracted claims are excluded.",
        "x-dataset-scope": "hearings:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "committee_link_id",
                "name_as_reported"
              ],
              "default": "committee_link_id"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "meeting_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "committee_snapshot_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "source_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "match_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "provisional_code_match",
                "unmatched"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "committee_link_id",
                              "meeting_id",
                              "meeting_version_id",
                              "source_code",
                              "identifier_namespace",
                              "name_as_reported",
                              "relationship_as_reported",
                              "committee_snapshot_id",
                              "match_status",
                              "match_basis",
                              "source_url",
                              "source_fetched_at",
                              "import_id"
                            ],
                            "properties": {
                              "committee_link_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "meeting_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Stable publisher event ID, not yet a reconciled event across publishers."
                              },
                              "meeting_version_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_code": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "identifier_namespace": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "name_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Immutable source spelling and capitalization."
                              },
                              "relationship_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_snapshot_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "match_status": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "match_basis": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_fetched_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/witness-appearances": {
      "get": {
        "operationId": "list_witness_appearances",
        "summary": "List listed witness appearances",
        "description": "Requires the hearings:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nCoverage is partial and publishing schedules vary by committee. A listing does not establish that an event occurred or that a listed witness attended.\n\nmeeting_id identifies a publisher event, not a reconciled event across publishers. Preserve source_namespace and source_event_id.\n\nWitness identifiers are provisional appearance identities. Name equality does not establish that two appearances belong to the same person.\n\nDocument and video URLs are source links, not a guarantee of downloaded, parsed or searchable content. GovInfo dateIssued is a source assertion, not a verified online release date or substitute for held dates.\n\nCommittee code matches are provisional and do not establish Member or staff attendance. Document links without appearance_id must not be attributed to every witness.\n\nExternal document enrichment includes only current source_linked claims; candidate, unmatched and retracted claims are excluded.",
        "x-dataset-scope": "hearings:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "name_as_reported",
                "start_date",
                "appearance_id"
              ],
              "default": "name_as_reported"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "meeting_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "appearance_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "witness_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "chamber",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "House",
                "Senate",
                "Joint"
              ]
            }
          },
          {
            "name": "congress",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 999
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case/accent-insensitive literal substring search in name_as_reported, organization_as_reported, position_as_reported, organization_or_title_as_reported",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 120
            }
          },
          {
            "name": "event_from",
            "in": "query",
            "required": false,
            "description": "Inclusive source event-date bound. Does not establish attendance or that an event occurred; excludes undated records.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "event_to",
            "in": "query",
            "required": false,
            "description": "Inclusive source event-date bound. Does not establish attendance or that an event occurred; excludes undated records.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "appearance_id",
                              "meeting_id",
                              "meeting_version_id",
                              "witness_id",
                              "source_appearance_id",
                              "name_as_reported",
                              "position_as_reported",
                              "organization_as_reported",
                              "organization_or_title_as_reported",
                              "attendance_status",
                              "identity_basis",
                              "chamber",
                              "congress",
                              "meeting_title",
                              "start_date",
                              "start_time",
                              "timezone",
                              "source_url",
                              "source_fetched_at",
                              "import_id"
                            ],
                            "properties": {
                              "appearance_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Witness appearance in a particular meeting version; null on event-wide documents."
                              },
                              "meeting_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Stable publisher event ID, not yet a reconciled event across publishers."
                              },
                              "meeting_version_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "witness_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Provisional appearance identity; do not merge equal names across meetings."
                              },
                              "source_appearance_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "name_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Immutable source spelling and capitalization."
                              },
                              "position_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "organization_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "organization_or_title_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "attendance_status": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "identity_basis": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "chamber": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "congress": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "meeting_title": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "start_date": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "start_time": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "timezone": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_fetched_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/meeting-documents": {
      "get": {
        "operationId": "list_meeting_documents",
        "summary": "List document and video link records",
        "description": "Requires the hearings:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nCoverage is partial and publishing schedules vary by committee. A listing does not establish that an event occurred or that a listed witness attended.\n\nmeeting_id identifies a publisher event, not a reconciled event across publishers. Preserve source_namespace and source_event_id.\n\nWitness identifiers are provisional appearance identities. Name equality does not establish that two appearances belong to the same person.\n\nDocument and video URLs are source links, not a guarantee of downloaded, parsed or searchable content. GovInfo dateIssued is a source assertion, not a verified online release date or substitute for held dates.\n\nCommittee code matches are provisional and do not establish Member or staff attendance. Document links without appearance_id must not be attributed to every witness.\n\nExternal document enrichment includes only current source_linked claims; candidate, unmatched and retracted claims are excluded.",
        "x-dataset-scope": "hearings:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "document_record_id",
                "document_type"
              ],
              "default": "document_record_id"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "meeting_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "appearance_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "document_type",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "record_kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "calendar",
                "enrichment"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case/accent-insensitive literal substring search in label",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "document_record_id",
                              "record_kind",
                              "meeting_id",
                              "meeting_version_id",
                              "appearance_id",
                              "document_type",
                              "type_as_reported",
                              "label",
                              "document_url",
                              "source_url",
                              "source_fetched_at",
                              "import_id",
                              "match_status",
                              "match_basis",
                              "provider",
                              "content_status"
                            ],
                            "properties": {
                              "document_record_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "record_kind": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "meeting_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Stable publisher event ID, not yet a reconciled event across publishers."
                              },
                              "meeting_version_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "appearance_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Witness appearance in a particular meeting version; null on event-wide documents."
                              },
                              "document_type": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "type_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "label": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "document_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_fetched_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "match_status": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "match_basis": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "provider": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "content_status": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/hearing-publications": {
      "get": {
        "operationId": "list_hearing_publications",
        "summary": "List hearing publication records",
        "description": "Requires the hearings:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nCoverage is partial and publishing schedules vary by committee. A listing does not establish that an event occurred or that a listed witness attended.\n\nmeeting_id identifies a publisher event, not a reconciled event across publishers. Preserve source_namespace and source_event_id.\n\nWitness identifiers are provisional appearance identities. Name equality does not establish that two appearances belong to the same person.\n\nDocument and video URLs are source links, not a guarantee of downloaded, parsed or searchable content. GovInfo dateIssued is a source assertion, not a verified online release date or substitute for held dates.\n\nCommittee code matches are provisional and do not establish Member or staff attendance. Document links without appearance_id must not be attributed to every witness.\n\nExternal document enrichment includes only current source_linked claims; candidate, unmatched and retracted claims are excluded.",
        "x-dataset-scope": "hearings:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "date_issued_as_reported",
                "publication_id"
              ],
              "default": "date_issued_as_reported"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "source_namespace",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "source_publication_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case/accent-insensitive literal substring search in title",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "publication_id",
                              "import_id",
                              "source_namespace",
                              "source_publication_id",
                              "title",
                              "date_issued_as_reported",
                              "held_dates",
                              "source_url",
                              "source_fetched_at",
                              "relationship_basis",
                              "publication_witnesses",
                              "witness_source_receipt"
                            ],
                            "properties": {
                              "publication_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_namespace": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_publication_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "title": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "date_issued_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "GovInfo MODS dateIssued as reported; not a verified online release timestamp or substitute for held_dates."
                              },
                              "held_dates": {
                                "type": [
                                  "object",
                                  "array",
                                  "null"
                                ],
                                "description": "Source assertions kept separate from date_issued_as_reported; not reconciled event links."
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_fetched_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "relationship_basis": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "publication_witnesses": {
                                "type": [
                                  "object",
                                  "array",
                                  "null"
                                ],
                                "description": "Publication-scoped contents entries, not confirmed oral testimony or resolved people. Empty for older imports without witness extraction; inspect witness_source_receipt. No inferred meeting links."
                              },
                              "witness_source_receipt": {
                                "type": [
                                  "object",
                                  "array",
                                  "null"
                                ],
                                "description": "Original transcript URL, SHA-256 and actual retrieval time used for witness extraction; null when no receipt was imported."
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/hearing-sources": {
      "get": {
        "operationId": "list_hearing_sources",
        "summary": "List hearing source references",
        "description": "Requires the hearings:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nCoverage is partial and publishing schedules vary by committee. A listing does not establish that an event occurred or that a listed witness attended.\n\nmeeting_id identifies a publisher event, not a reconciled event across publishers. Preserve source_namespace and source_event_id.\n\nWitness identifiers are provisional appearance identities. Name equality does not establish that two appearances belong to the same person.\n\nDocument and video URLs are source links, not a guarantee of downloaded, parsed or searchable content. GovInfo dateIssued is a source assertion, not a verified online release date or substitute for held dates.\n\nCommittee code matches are provisional and do not establish Member or staff attendance. Document links without appearance_id must not be attributed to every witness.\n\nExternal document enrichment includes only current source_linked claims; candidate, unmatched and retracted claims are excluded.",
        "x-dataset-scope": "hearings:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "source_id",
                "retrieved_at"
              ],
              "default": "source_id"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "meeting_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "record_kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "meeting",
                "publication",
                "enrichment"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "source_id",
                              "record_kind",
                              "dataset_id",
                              "meeting_id",
                              "import_id",
                              "source_namespace",
                              "source_url",
                              "retrieved_at",
                              "source_sha256",
                              "timestamp_basis"
                            ],
                            "properties": {
                              "source_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "record_kind": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "dataset_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "meeting_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Stable publisher event ID, not yet a reconciled event across publishers."
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_namespace": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "retrieved_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_sha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "timestamp_basis": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Meaning of source_timestamp: extraction_generated_at, proxy_retrieved_at, or derived_build_time."
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/staff-profiles": {
      "get": {
        "operationId": "list_staff_profiles",
        "summary": "List provisional office/name staff profiles",
        "description": "Requires the staff:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nObvious Senate travel/expense extraction fragments are excluded under the versioned public eligibility policy. Remaining candidates are not uniformly verified staff; original evidence remains available for internal review.\n\nPayroll report periods are not employment dates. Appearing in the latest available report does not confirm current employment.\n\nA staff_profile_id groups a reported name and office; it is not a unique person. reviewed_person_id is nullable.\n\nMember and committee office matches are automated provisional suggestions. Personal-office staff do not inherit a Member’s committee assignments.\n\nSource text may contain extraction errors. Original reported values retain publisher capitalization; display fields are presentation only.\n\nReviewed office-identifier overrides are not yet resolved into these automated context views; do not treat automated matches as final.\n\nProfile summaries describe observations matching this query. Representative title, source and reviewed identity belong only to the latest matching observation, selected by report end/start then immutable ID.\n\nA profile can contain observations linked to different people. No reviewed identity is promoted to the whole profile.",
        "x-dataset-scope": "staff:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "name_display",
                "office_display_name",
                "last_report_end",
                "observation_count",
                "staff_profile_id"
              ],
              "default": "name_display"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "chamber",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "House",
                "Senate"
              ]
            }
          },
          {
            "name": "office_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "staff_profile_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "reviewed_person_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "office_category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "office_type_extracted",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "report_period_label",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "appears_in_latest_report",
            "in": "query",
            "required": false,
            "description": "Filter MAX latest-report appearance after other evidence filters; false excludes profiles with any latest appearance within that selected evidence. Not employment status.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case/accent-insensitive literal substring search in name_display, name_as_reported, office_display_name, office_as_reported, title_display, title_extracted",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 120
            }
          },
          {
            "name": "report_from",
            "in": "query",
            "required": false,
            "description": "Inclusive reporting-period overlap bound; not employment dates.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "report_to",
            "in": "query",
            "required": false,
            "description": "Inclusive reporting-period overlap bound; not employment dates.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "staff_profile_id",
                              "name_display",
                              "name_as_reported",
                              "chamber",
                              "office_id",
                              "office_display_name",
                              "office_as_reported",
                              "office_code",
                              "representative_observation_version_id",
                              "representative_reviewed_person_id",
                              "title_display",
                              "title_extracted",
                              "office_type_extracted",
                              "report_period_label",
                              "report_start",
                              "report_end",
                              "source_id",
                              "source_url",
                              "publisher_source_id",
                              "source_row_first",
                              "source_row_last",
                              "source_pdf_page",
                              "source_report_page",
                              "dataset_id",
                              "import_id",
                              "extraction_generated_at",
                              "representative_evidence",
                              "limitations",
                              "first_report_start",
                              "last_report_end",
                              "observation_count",
                              "report_count",
                              "appears_in_latest_report",
                              "identity_status"
                            ],
                            "properties": {
                              "staff_profile_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Exact reported office/name grouping. Not a unique person."
                              },
                              "name_display": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "name_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Immutable source spelling and capitalization."
                              },
                              "chamber": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "office_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "office_display_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "office_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "office_code": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "representative_observation_version_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Latest matching report end/start, then immutable observation ID ascending. Not a current title claim."
                              },
                              "representative_reviewed_person_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Nullable accepted identity for the representative observation only. Never apply to the whole profile."
                              },
                              "title_display": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "title_extracted": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "office_type_extracted": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "report_period_label": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "report_start": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Start of reporting period, not employment."
                              },
                              "report_end": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "End of reporting period, not employment."
                              },
                              "source_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "publisher_source_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_row_first": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "source_row_last": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "source_pdf_page": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "source_report_page": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "dataset_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "extraction_generated_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "representative_evidence": {
                                "type": [
                                  "object",
                                  "array",
                                  "null"
                                ]
                              },
                              "limitations": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "first_report_start": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Earliest matching report start, not hire date."
                              },
                              "last_report_end": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Latest matching report end, not departure or employment confirmation."
                              },
                              "observation_count": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "pattern": "^[0-9]+$",
                                "description": "Decimal string count of matching observations in this profile; not distinct jobs or people."
                              },
                              "report_count": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "pattern": "^[0-9]+$",
                                "description": "Decimal string count of distinct official source references among matching observations."
                              },
                              "appears_in_latest_report": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "0/1 appearance flag within selected source snapshot, not current employment."
                              },
                              "identity_status": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/staff-observations": {
      "get": {
        "operationId": "list_staff_observations",
        "summary": "List immutable payroll observation versions",
        "description": "Requires the staff:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nObvious Senate travel/expense extraction fragments are excluded under the versioned public eligibility policy. Remaining candidates are not uniformly verified staff; original evidence remains available for internal review.\n\nPayroll report periods are not employment dates. Appearing in the latest available report does not confirm current employment.\n\nA staff_profile_id groups a reported name and office; it is not a unique person. reviewed_person_id is nullable.\n\nMember and committee office matches are automated provisional suggestions. Personal-office staff do not inherit a Member’s committee assignments.\n\nSource text may contain extraction errors. Original reported values retain publisher capitalization; display fields are presentation only.\n\nReviewed office-identifier overrides are not yet resolved into these automated context views; do not treat automated matches as final.",
        "x-dataset-scope": "staff:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "report_end",
                "name_display",
                "observation_version_id"
              ],
              "default": "report_end"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "chamber",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "House",
                "Senate"
              ]
            }
          },
          {
            "name": "office_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "staff_profile_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "reviewed_person_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "bioguide_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z][0-9]{6}$"
            }
          },
          {
            "name": "gpi_member_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{1,18}$"
            }
          },
          {
            "name": "committee_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "committee_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "report_period_label",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "office_category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "office_type_extracted",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "appears_in_latest_report",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "member_match_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "matched",
                "needs_review",
                "unmatched",
                "out_of_scope",
                "not_evaluated"
              ]
            }
          },
          {
            "name": "committee_match_status",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "matched",
                "needs_review",
                "unmatched",
                "out_of_scope",
                "not_evaluated"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case/accent-insensitive literal substring search in name_display, name_as_reported, office_display_name, office_as_reported, title_display, title_extracted",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 120
            }
          },
          {
            "name": "report_from",
            "in": "query",
            "required": false,
            "description": "Inclusive reporting-period overlap bound; not employment dates.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "report_to",
            "in": "query",
            "required": false,
            "description": "Inclusive reporting-period overlap bound; not employment dates.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "observation_version_id",
                              "observation_key",
                              "staff_profile_id",
                              "reviewed_person_id",
                              "chamber",
                              "dataset_id",
                              "import_id",
                              "extraction_generated_at",
                              "name_display",
                              "name_as_reported",
                              "office_id",
                              "office_display_name",
                              "office_as_reported",
                              "office_code",
                              "office_type_extracted",
                              "title_display",
                              "title_extracted",
                              "report_period_label",
                              "report_start",
                              "report_end",
                              "appears_in_latest_report",
                              "source_url",
                              "publisher_source_id",
                              "source_row_first",
                              "source_row_last",
                              "source_pdf_page",
                              "source_report_page",
                              "evidence",
                              "limitations",
                              "member_id",
                              "gpi_member_id",
                              "bioguide_id",
                              "member_name",
                              "member_match_status",
                              "member_match_method",
                              "member_match_rationale",
                              "member_import_id",
                              "member_detail_coverage",
                              "member_list_source_url",
                              "member_detail_source_url",
                              "committee_id",
                              "committee_code",
                              "committee_name",
                              "committee_match_status",
                              "committee_match_method",
                              "committee_match_rationale",
                              "committee_period_relationship",
                              "committee_snapshot_congress",
                              "staff_unit_as_reported",
                              "committee_source_evidence",
                              "identity_status",
                              "relationship_basis"
                            ],
                            "properties": {
                              "observation_version_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "observation_key": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "staff_profile_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Exact reported office/name grouping. Not a unique person."
                              },
                              "reviewed_person_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Nullable reviewed identity associated with this observation only."
                              },
                              "chamber": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "dataset_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "extraction_generated_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "name_display": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "name_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Immutable source spelling and capitalization."
                              },
                              "office_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "office_display_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "office_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "office_code": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "office_type_extracted": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "title_display": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "title_extracted": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "report_period_label": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "report_start": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Start of reporting period, not employment."
                              },
                              "report_end": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "End of reporting period, not employment."
                              },
                              "appears_in_latest_report": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "description": "0/1 appearance flag within selected source snapshot, not current employment."
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "publisher_source_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_row_first": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "source_row_last": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "source_pdf_page": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "source_report_page": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "evidence": {
                                "type": [
                                  "object",
                                  "array",
                                  "null"
                                ]
                              },
                              "limitations": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "gpi_member_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "pattern": "^[0-9]+$",
                                "description": "Decimal string; preserve numeric identifier precision."
                              },
                              "bioguide_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_match_status": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Automated provisional office match; matched is not a reviewed identity."
                              },
                              "member_match_method": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_match_rationale": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_detail_coverage": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_list_source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_detail_source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_code": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_match_status": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Automated provisional office match; no inherited Member committee employment."
                              },
                              "committee_match_method": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_match_rationale": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_period_relationship": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_snapshot_congress": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "staff_unit_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_source_evidence": {
                                "type": [
                                  "object",
                                  "array",
                                  "null"
                                ]
                              },
                              "identity_status": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "relationship_basis": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/members": {
      "get": {
        "operationId": "list_members",
        "summary": "List member snapshots",
        "description": "Requires the members:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nThe CongressLink roster is not a historical census. Some current Senators have only House detail history plus a Senate roster-role fallback.\n\nListed chamber and active flags are source assertions.",
        "x-dataset-scope": "members:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "display_name",
                "gpi_member_id",
                "member_snapshot_id"
              ],
              "default": "display_name"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "chamber",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "House",
                "Senate"
              ]
            }
          },
          {
            "name": "bioguide_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z][0-9]{6}$"
            }
          },
          {
            "name": "gpi_member_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{1,18}$"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case/accent-insensitive literal substring search in display_name, bioguide_id",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "member_id",
                              "registry_id",
                              "gpi_member_id",
                              "member_snapshot_id",
                              "bioguide_id",
                              "display_name",
                              "first_name",
                              "last_name",
                              "chamber",
                              "detail_chamber",
                              "detail_coverage",
                              "list_source_url",
                              "detail_source_url",
                              "import_id",
                              "retrieved_at",
                              "listing_scope",
                              "limitations",
                              "sourced_assignments",
                              "committee_coverage_status"
                            ],
                            "properties": {
                              "member_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "registry_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "gpi_member_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "pattern": "^[0-9]+$",
                                "description": "Decimal string; preserve numeric identifier precision."
                              },
                              "member_snapshot_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "bioguide_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "display_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "first_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "last_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "chamber": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "detail_chamber": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "detail_coverage": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "list_source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "detail_source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "retrieved_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "listing_scope": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "limitations": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "sourced_assignments": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "pattern": "^[0-9]+$",
                                "description": "Decimal string; preserve numeric identifier precision."
                              },
                              "committee_coverage_status": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/committees": {
      "get": {
        "operationId": "list_committees",
        "summary": "List committee snapshots per Congress",
        "description": "Requires the committees:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nBodies are observed in Member assignments, not a complete committee census. Joint committees and bodies without returned members may be absent.\n\nParent links are code-based proposals. Committee codes remain in the CongressLink namespace.",
        "x-dataset-scope": "committees:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "display_name",
                "code_as_reported",
                "committee_snapshot_id"
              ],
              "default": "display_name"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "chamber",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "House",
                "Senate",
                "Joint"
              ]
            }
          },
          {
            "name": "congress",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 999
            }
          },
          {
            "name": "committee_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "code_as_reported",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case/accent-insensitive literal substring search in display_name, name_as_reported, code_as_reported",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 120
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "committee_id",
                              "registry_id",
                              "upstream_committee_id",
                              "committee_snapshot_id",
                              "display_name",
                              "code_as_reported",
                              "name_as_reported",
                              "chamber",
                              "congress",
                              "proposed_parent_id",
                              "hierarchy_basis",
                              "source_evidence",
                              "committee_import_id",
                              "member_import_id",
                              "built_at"
                            ],
                            "properties": {
                              "committee_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "registry_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "upstream_committee_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "pattern": "^[0-9]+$",
                                "description": "Decimal string; preserve numeric identifier precision."
                              },
                              "committee_snapshot_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "display_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "code_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "name_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Immutable source spelling and capitalization."
                              },
                              "chamber": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "congress": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "proposed_parent_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Code-based parent proposal, not an authoritative hierarchy."
                              },
                              "hierarchy_basis": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_evidence": {
                                "type": [
                                  "object",
                                  "array",
                                  "null"
                                ]
                              },
                              "committee_import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "built_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/sources": {
      "get": {
        "operationId": "list_sources",
        "summary": "List source references in selected complete snapshots",
        "description": "A scoped key must supply kind=payroll (staff:read), member_api (members:read), or committee_api (committees:read). Unfiltered sources require all three scopes; dataset_id also requires its matching scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nPayroll original-file checksums may be null; extraction-artifact checksums do not authenticate original government bytes.\n\nMember and committee sources describe the same archived proxy response where applicable; distinct source IDs may share URLs.",
        "x-dataset-scope": "depends-on-kind",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "source_id",
                "report_end"
              ],
              "default": "source_id"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "chamber",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "House",
                "Senate",
                "Joint"
              ]
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "payroll",
                "member_api",
                "committee_api"
              ]
            }
          },
          {
            "name": "dataset_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "source_id",
                              "kind",
                              "dataset_id",
                              "chamber",
                              "publisher",
                              "source_url",
                              "publisher_source_id",
                              "source_kind",
                              "report_start",
                              "report_end",
                              "original_file_sha256",
                              "extraction_artifact_sha256",
                              "response_sha256",
                              "import_id",
                              "source_timestamp",
                              "timestamp_basis",
                              "publishing_frequency",
                              "limitations"
                            ],
                            "properties": {
                              "source_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "kind": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "dataset_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "chamber": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "publisher": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "publisher_source_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_kind": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "report_start": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Start of reporting period, not employment."
                              },
                              "report_end": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "End of reporting period, not employment."
                              },
                              "original_file_sha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "extraction_artifact_sha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "response_sha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_timestamp": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Timestamp interpreted only with timestamp_basis; not necessarily upstream refresh time."
                              },
                              "timestamp_basis": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Meaning of source_timestamp: extraction_generated_at, proxy_retrieved_at, or derived_build_time."
                              },
                              "publishing_frequency": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "limitations": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/member-roles": {
      "get": {
        "operationId": "list_member_roles",
        "summary": "List sourced legislative role versions",
        "description": "Requires the members:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nThese are sourced legislative roles, not staff employment or committee appointment dates. Upstream role ID is null for roster fallbacks.",
        "x-dataset-scope": "members:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "role_version_id",
                "starts_on"
              ],
              "default": "role_version_id"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "chamber",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "House",
                "Senate"
              ]
            }
          },
          {
            "name": "member_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "gpi_member_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{1,18}$"
            }
          },
          {
            "name": "bioguide_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z][0-9]{6}$"
            }
          },
          {
            "name": "state_code",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "role_version_id",
                              "member_id",
                              "member_snapshot_id",
                              "registry_id",
                              "gpi_member_id",
                              "bioguide_id",
                              "upstream_role_id",
                              "chamber",
                              "title",
                              "state_code",
                              "district",
                              "starts_on",
                              "ends_on",
                              "is_active_as_reported",
                              "party_name",
                              "party_abbreviation",
                              "evidence_kind",
                              "source_url",
                              "source_response_sha256",
                              "retrieved_at"
                            ],
                            "properties": {
                              "role_version_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_snapshot_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "registry_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "gpi_member_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "pattern": "^[0-9]+$",
                                "description": "Decimal string; preserve numeric identifier precision."
                              },
                              "bioguide_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "upstream_role_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "pattern": "^[0-9]+$",
                                "description": "Source role identifier, nullable for roster fallback."
                              },
                              "chamber": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "title": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "state_code": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "district": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "starts_on": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "ends_on": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "is_active_as_reported": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "party_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "party_abbreviation": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "evidence_kind": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_response_sha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "retrieved_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/committee-assignments": {
      "get": {
        "operationId": "list_committee_assignments",
        "summary": "List sourced Member committee assignments",
        "description": "Requires the committees:read dataset scope.\n\nSource values are not independently verified. Retrieval and import times do not establish an upstream refresh time.\n\nMissing records or relationships are coverage gaps, not evidence of absence.\n\nsource_start_date and source_end_date can be synchronization dates, not verified appointment dates.\n\nAssignments are as reported; current flags and completeness are unverified.",
        "x-dataset-scope": "committees:read",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Bounded page size",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Zero-based offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 200000,
              "default": 0
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "assignment_id",
                "member_name"
              ],
              "default": "assignment_id"
            }
          },
          {
            "name": "order",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ],
              "default": "asc"
            }
          },
          {
            "name": "snapshot",
            "in": "query",
            "required": false,
            "description": "Use meta.snapshot from the first page. 409 means restart pagination.",
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            }
          },
          {
            "name": "chamber",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "House",
                "Senate",
                "Joint"
              ]
            }
          },
          {
            "name": "committee_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "member_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "gpi_member_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[0-9]{1,18}$"
            }
          },
          {
            "name": "bioguide_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z][0-9]{6}$"
            }
          },
          {
            "name": "congress",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 999
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot-consistent paginated records. Numeric upstream BIGINT IDs are decimal strings; source flags are 0/1.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Page"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true,
                            "required": [
                              "assignment_id",
                              "committee_id",
                              "committee_snapshot_id",
                              "upstream_committee_id",
                              "registry_id",
                              "code_as_reported",
                              "committee_name",
                              "chamber",
                              "congress",
                              "member_id",
                              "member_snapshot_id",
                              "gpi_member_id",
                              "bioguide_id",
                              "member_name",
                              "role_as_reported",
                              "rank_as_reported",
                              "is_current_as_reported",
                              "source_start_date",
                              "source_end_date",
                              "date_basis",
                              "source_url",
                              "source_response_sha256",
                              "committee_import_id",
                              "member_import_id",
                              "built_at"
                            ],
                            "properties": {
                              "assignment_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_snapshot_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "upstream_committee_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "pattern": "^[0-9]+$",
                                "description": "Decimal string; preserve numeric identifier precision."
                              },
                              "registry_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "code_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "chamber": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "congress": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "member_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_snapshot_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "gpi_member_id": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "pattern": "^[0-9]+$",
                                "description": "Decimal string; preserve numeric identifier precision."
                              },
                              "bioguide_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "role_as_reported": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "rank_as_reported": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "is_current_as_reported": {
                                "type": [
                                  "integer",
                                  "null"
                                ]
                              },
                              "source_start_date": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "As reported; may be synchronization time, not appointment."
                              },
                              "source_end_date": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "As reported; may be synchronization time, not departure."
                              },
                              "date_basis": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_url": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "source_response_sha256": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "committee_import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "member_import_id": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "built_at": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Dataset scope or browser origin not authorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Snapshot changed; restart pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "414": {
            "description": "Request rejected",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited; obey Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Source snapshot, database or fresh authorization registry unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "partnerKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "pv1.<key-id>.<random-secret>"
      }
    },
    "schemas": {
      "Page": {
        "type": "object",
        "required": [
          "data",
          "meta",
          "request_id"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "meta": {
            "type": "object",
            "required": [
              "snapshot",
              "total",
              "count_unit",
              "limit",
              "offset",
              "returned",
              "next_offset",
              "freshness",
              "coverage_gaps"
            ],
            "properties": {
              "snapshot": {
                "type": "string"
              },
              "total": {
                "type": "integer"
              },
              "count_unit": {
                "type": "string"
              },
              "summary_scope": {
                "type": "string",
                "description": "Staff profiles use matching_observations; counts and representative source change with evidence filters."
              },
              "matching_observation_count": {
                "type": "integer",
                "description": "Total matching observations across all filtered profiles, not merely this page."
              },
              "latest_filter_basis": {
                "type": "string"
              },
              "representative_basis": {
                "type": "string"
              },
              "limit": {
                "type": "integer"
              },
              "offset": {
                "type": "integer"
              },
              "returned": {
                "type": "integer"
              },
              "next_offset": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "generated_at": {
                "type": "string",
                "format": "date-time"
              },
              "freshness": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "dataset_id": {
                      "type": "string"
                    },
                    "import_id": {
                      "type": "string"
                    },
                    "generation": {
                      "type": "string",
                      "description": "Completed import manifest hash; not a publisher release timestamp."
                    },
                    "timestamp_basis": {
                      "type": "string"
                    },
                    "coverage": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "built_at": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Normalizer or enrichment build time, not publication time."
                    },
                    "first_retrieved_at": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "last_retrieved_at": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "upstream_updated_at": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "staff_index_ready": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "description": "Payroll projection readiness, 0/1; staff search fails closed when not ready."
                    },
                    "staff_index_generation": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Derived serving generation, not a new source import."
                    },
                    "staff_index_built_at": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Derived index build time, not upstream publication time."
                    },
                    "report_start": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "report_end": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              },
              "event_date_range": {
                "type": "object",
                "properties": {
                  "from": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date"
                  },
                  "to": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date"
                  }
                }
              },
              "coverage_gaps": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "request_id"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}