openapi: 3.2.0
info:
  title: 2s — the (most) everything Gov API
  version: '1'
  summary: The (most) everything API.
  description: 'The (most) everything API for AI agents: 575+ pay-per-call endpoints on one origin.'
  contact:
    name: 2s
    url: https://2s.io
    email: alley@2s.io
  x-logo:
    url: https://2s.io/icon-512.png
    altText: 2s
  x-guidance: 'Pay-per-call REST API for AI agents — hundreds of endpoints returning ground-truth data (US public records, company & legal identifiers, finance/SEC, crypto/web3, security & CVEs, medical codes, weather & geocoding, agriculture, energy, maritime, music, and more). Every endpoint is paid per call in USDC via x402 (Base or Solana) — no API key, no signup. Call any endpoint with no auth to get a 402 PaymentRequirements envelope, sign it (EIP-3009 on Base, partial SPL transfer on Solana), and retry with the PAYMENT-SIGNATURE header. Add ?trial=1 for one free real call per endpoint per hour to test before paying. To discover the right endpoint: GET https://2s.io/api/directory for the full catalog, or GET https://2s.io/api/search/endpoints?q=<natural-language task> for a ranked match. Per-call price is on each operation as x-payment-info (from $0.001). Batch up to 50 calls behind one payment via POST https://2s.io/api/batch/run.'
servers:
- url: https://2s.io
tags:
- name: gov
paths:
  /api/gov/bea-gdp:
    get:
      tags:
      - gov
      summary: Quarterly real GDP by US state from the Bureau of Economic
      description: Quarterly real GDP by US state from the Bureau of Economic Analysis (BEA) Regional accounts — all-industry total, in millions of chained (inflation-adjusted) dollars. Requires state (2-letter); optionally a specific year (defaults to the last 5 years). Returns the state name plus GDP observations (period like 2025Q2, real GDP in millions USD, unit), newest quarter first. Free, public-domain (BEA). Authoritative state economic-output data an LLM cannot recall — for economic research, regional analysis, and market sizing.
      operationId: gov_bea-gdp
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [one state GDP result]; total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            query:
                              type: object
                              properties:
                                state:
                                  type: string
                                geoFips:
                                  type: string
                                year:
                                  type: string
                                limit:
                                  type: number
                              required:
                              - state
                              - geoFips
                              - year
                              - limit
                              additionalProperties: false
                            geoName:
                              type: string
                              nullable: true
                            returned:
                              type: number
                            observations:
                              type: array
                              items:
                                type: object
                                properties:
                                  period:
                                    type: string
                                    nullable: true
                                  realGdpMillionsUSD:
                                    type: number
                                    nullable: true
                                  unit:
                                    type: string
                                    nullable: true
                                required:
                                - period
                                - realGdpMillionsUSD
                                - unit
                                additionalProperties: false
                            source:
                              $ref: '#/components/schemas/Source'
                            note:
                              type: string
                          required:
                          - query
                          - geoName
                          - returned
                          - observations
                          - source
                          - note
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.bea-gdp
      x-2s-version: null
      x-2s-price:
        usd: 0.0027
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002700'
        protocols:
        - x402: {}
      parameters:
      - name: state
        in: query
        required: true
        description: 2-letter US state/territory code.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: year
        in: query
        required: false
        description: Four-digit calendar year.
        schema:
          type: integer
          minimum: 1960
          maximum: 2100
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 40
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/bill-summaries:
    get:
      tags:
      - gov
      summary: Stream the latest US Congressional bill summaries via
      description: Stream the latest US Congressional bill summaries via Congress.gov. Each row is a CRS-authored summary attached to a specific version of a bill (Introduced, Reported to House, Engrossed in Senate, Public Law, etc.). Filter by congress + bill type. Returns the underlying bill metadata + summary text + version code + action date. Use this for change-detection on bills you care about, or to power agent-side "what did Congress just pass" feeds.
      operationId: gov_bill-summaries
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = CRS bill summaries (bill metadata + summary text + version code + action date); total = upstream match count.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            actionDate:
                              type: string
                              nullable: true
                            actionDesc:
                              type: string
                              nullable: true
                            bill:
                              type: object
                              additionalProperties: {}
                              nullable: true
                            currentChamber:
                              type: string
                              nullable: true
                            currentChamberCode:
                              type: string
                              nullable: true
                            lastSummaryUpdateDate:
                              type: string
                              nullable: true
                            text:
                              type: string
                              nullable: true
                            updateDate:
                              type: string
                              nullable: true
                            versionCode:
                              type: string
                              nullable: true
                          required:
                          - actionDate
                          - actionDesc
                          - bill
                          - currentChamber
                          - currentChamberCode
                          - lastSummaryUpdateDate
                          - text
                          - updateDate
                          - versionCode
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.bill-summaries
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: congress
        in: query
        required: false
        description: US Congress number (e.g. 118 for the 2023–2025 Congress).
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - name: type
        in: query
        required: false
        description: Filter results by type.
        schema:
          type: string
          enum:
          - hr
          - s
          - hjres
          - sjres
          - hconres
          - sconres
          - hres
          - sres
      - name: fromDate
        in: query
        required: false
        description: From date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: toDate
        in: query
        required: false
        description: To date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: sort
        in: query
        required: false
        description: Field to sort results by.
        schema:
          type: string
          enum:
          - updateDate+desc
          - updateDate+asc
          default: updateDate+desc
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 250
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/carrier-safety:
    get:
      tags:
      - gov
      summary: FMCSA motor-carrier (trucking/bus company) safety profile
      description: 'FMCSA motor-carrier (trucking/bus company) safety profile. Pass dot (USDOT number) for the full record: legal/DBA name, state, interstate/intrastate operation, operating-authority status (allowedToOperate), FMCSA safety rating, fleet size (drivers + power units), crash history (total/fatal/injury/tow-away), roadside-inspection history with driver + vehicle out-of-service rates, and the CSA BASIC measures (Unsafe Driving, Hours-of-Service, Driver Fitness, Controlled Substances, Vehicle Maintenance, Hazmat, Crash Indicator) with violation counts. Or pass name to search → matching carriers with their DOT numbers. Free, public-domain US DOT data (keyed). For commercial-auto/freight underwriting, broker/shipper vetting, and vendor due diligence — the authorization + safety record an agent can''t get from training.'
      operationId: gov_carrier-safety
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      mode:
                        type: string
                        enum:
                        - carrier
                        - search
                      query:
                        type: object
                        properties:
                          dot:
                            type: number
                            nullable: true
                          name:
                            type: string
                            nullable: true
                        required:
                        - dot
                        - name
                        additionalProperties: false
                      found:
                        type: boolean
                      carrier:
                        type: object
                        properties:
                          dotNumber:
                            type: number
                            nullable: true
                          legalName:
                            type: string
                            nullable: true
                          dbaName:
                            type: string
                            nullable: true
                          physicalState:
                            type: string
                            nullable: true
                          operation:
                            type: string
                            nullable: true
                          allowedToOperate:
                            type: boolean
                            nullable: true
                          statusCode:
                            type: string
                            nullable: true
                          safetyRating:
                            type: string
                            nullable: true
                          safetyRatingDate:
                            type: string
                            nullable: true
                          totalDrivers:
                            type: number
                            nullable: true
                          totalPowerUnits:
                            type: number
                            nullable: true
                        required:
                        - dotNumber
                        - legalName
                        - dbaName
                        - physicalState
                        - operation
                        - allowedToOperate
                        - statusCode
                        - safetyRating
                        - safetyRatingDate
                        - totalDrivers
                        - totalPowerUnits
                        additionalProperties: false
                        nullable: true
                      crashes:
                        type: object
                        properties:
                          total:
                            type: number
                            nullable: true
                          fatal:
                            type: number
                            nullable: true
                          injury:
                            type: number
                            nullable: true
                          towaway:
                            type: number
                            nullable: true
                        required:
                        - total
                        - fatal
                        - injury
                        - towaway
                        additionalProperties: false
                        nullable: true
                      inspections:
                        type: object
                        properties:
                          driverTotal:
                            type: number
                            nullable: true
                          driverOutOfService:
                            type: number
                            nullable: true
                          driverOosRate:
                            type: number
                            nullable: true
                          vehicleTotal:
                            type: number
                            nullable: true
                          vehicleOutOfService:
                            type: number
                            nullable: true
                          vehicleOosRate:
                            type: number
                            nullable: true
                        required:
                        - driverTotal
                        - driverOutOfService
                        - driverOosRate
                        - vehicleTotal
                        - vehicleOutOfService
                        - vehicleOosRate
                        additionalProperties: false
                        nullable: true
                      basics:
                        type: array
                        items:
                          type: object
                          properties:
                            category:
                              type: string
                              nullable: true
                            measureValue:
                              type: number
                              nullable: true
                            percentile:
                              type: string
                              nullable: true
                            violationThreshold:
                              type: number
                              nullable: true
                            exceededInterventionThreshold:
                              type: boolean
                              nullable: true
                            totalViolations:
                              type: number
                              nullable: true
                            totalInspectionsWithViolation:
                              type: number
                              nullable: true
                            runDate:
                              type: string
                              nullable: true
                          required:
                          - category
                          - measureValue
                          - percentile
                          - violationThreshold
                          - exceededInterventionThreshold
                          - totalViolations
                          - totalInspectionsWithViolation
                          - runDate
                          additionalProperties: false
                      matches:
                        type: array
                        items:
                          type: object
                          properties:
                            dotNumber:
                              type: number
                              nullable: true
                            legalName:
                              type: string
                              nullable: true
                            dbaName:
                              type: string
                              nullable: true
                            physicalState:
                              type: string
                              nullable: true
                          required:
                          - dotNumber
                          - legalName
                          - dbaName
                          - physicalState
                          additionalProperties: false
                      source:
                        $ref: '#/components/schemas/Source'
                      note:
                        type: string
                    required:
                    - mode
                    - query
                    - found
                    - carrier
                    - crashes
                    - inspections
                    - basics
                    - matches
                    - source
                    - note
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.carrier-safety
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: legacy
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: dot
        in: query
        required: false
        description: Dot.
        schema:
          type: integer
          exclusiveMinimum: true
          minimum: 0
      - name: name
        in: query
        required: false
        description: Name to search for.
        schema:
          type: string
          minLength: 2
          maxLength: 120
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/congress-amendment:
    get:
      tags:
      - gov
      summary: Look up or list US Congressional amendments via Congress.gov
      description: 'Look up or list US Congressional amendments via Congress.gov. Pass congress + type + number to fetch a single amendment with full sponsor + action history. Or filter list by congress + type + date range. Amendment types: hamdt=House Amendment, samdt=Senate Amendment, suamdt=Senate Unprinted Amendment.'
      operationId: gov_congress-amendment
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [amendment] (lookup mode, total 1) or the amendment list (list mode, total = upstream match count); meta.mode flags which.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            congress:
                              type: number
                              nullable: true
                            type:
                              type: string
                              nullable: true
                              description: HAMDT | SAMDT | SUAMDT.
                            number:
                              type: string
                              nullable: true
                            description:
                              type: string
                              nullable: true
                            purpose:
                              type: string
                              nullable: true
                            latestAction:
                              type: object
                              additionalProperties: {}
                              nullable: true
                              description: Upstream pass-through, e.g. { actionDate, text }.
                            updateDate:
                              type: string
                              nullable: true
                            apiUrl:
                              type: string
                              nullable: true
                              description: Congress.gov API URL for the amendment.
                          additionalProperties: {}
                          description: List mode emits this trimmed shape; lookup mode passes the full raw Congress.gov amendment detail through (extra fields, full sponsor + action history).
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          mode:
                            type: string
                            enum:
                            - lookup
                            - list
                        required:
                        - mode
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.congress-amendment
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: congress
        in: query
        required: false
        description: US Congress number (e.g. 118 for the 2023–2025 Congress).
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - name: type
        in: query
        required: false
        description: Filter results by type.
        schema:
          type: string
          enum:
          - hamdt
          - samdt
          - suamdt
      - name: number
        in: query
        required: false
        description: Item number or identifier.
        schema:
          type: integer
          minimum: 1
      - name: fromDate
        in: query
        required: false
        description: From date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: toDate
        in: query
        required: false
        description: To date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 250
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/congress-bill:
    get:
      tags:
      - gov
      summary: Look up or search US Congressional bills via the Library of
      description: 'Look up or search US Congressional bills via the Library of Congress Congress.gov API. Pass congress + type + number to fetch a specific bill (title, sponsors, latest action, action/amendment/committee counts, policy area, congress.gov URL). Or omit number to list bills filtered by congress, bill type (hr | s | hjres | sjres | hconres | sconres | hres | sres), date range, with pagination + sort. Bill type semantics: hr=House Bill, s=Senate Bill, hjres/sjres=joint resolution, hconres/sconres=concurrent resolution, hres/sres=simple resolution.'
      operationId: gov_congress-bill
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [bill] (lookup mode, total 1) or the bill list (list mode, total = upstream match count); meta.mode flags which.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            congress:
                              type: number
                              nullable: true
                            type:
                              type: string
                              nullable: true
                              description: Uppercased bill type (HR, S, HJRES, ...).
                            number:
                              type: string
                              nullable: true
                            title:
                              type: string
                              nullable: true
                            originChamber:
                              type: string
                              nullable: true
                            latestAction:
                              type: object
                              additionalProperties: {}
                              nullable: true
                              description: Upstream pass-through, e.g. { actionDate, text }.
                            updateDate:
                              type: string
                              nullable: true
                            apiUrl:
                              type: string
                              nullable: true
                              description: Congress.gov API URL for the bill.
                            introducedDate:
                              type: string
                              nullable: true
                              description: Lookup mode only.
                            constitutionalAuthorityStatementText:
                              type: string
                              nullable: true
                              description: Lookup mode only.
                            policyArea:
                              type: string
                              nullable: true
                              description: Policy area name; lookup mode only.
                            sponsors:
                              type: array
                              items:
                                type: object
                                additionalProperties: {}
                              description: Upstream sponsor objects; lookup mode only.
                            cosponsors:
                              type: number
                              description: Cosponsor count; lookup mode only.
                            committees:
                              type: number
                              description: Committee count; lookup mode only.
                            actionsCount:
                              type: number
                              description: Lookup mode only.
                            amendmentsCount:
                              type: number
                              description: Lookup mode only.
                            textVersionsUrl:
                              type: string
                              nullable: true
                              description: Lookup mode only.
                            source:
                              $ref: '#/components/schemas/Source'
                          required:
                          - congress
                          - type
                          - number
                          - title
                          - originChamber
                          - latestAction
                          - updateDate
                          - apiUrl
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          mode:
                            type: string
                            enum:
                            - lookup
                            - list
                        required:
                        - mode
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.congress-bill
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: congress
        in: query
        required: false
        description: US Congress number (e.g. 118 for the 2023–2025 Congress).
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - name: type
        in: query
        required: false
        description: Filter results by type.
        schema:
          type: string
          enum:
          - hr
          - s
          - hjres
          - sjres
          - hconres
          - sconres
          - hres
          - sres
      - name: number
        in: query
        required: false
        description: Item number or identifier.
        schema:
          type: integer
          minimum: 1
      - name: fromDate
        in: query
        required: false
        description: From date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: toDate
        in: query
        required: false
        description: To date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: sort
        in: query
        required: false
        description: Field to sort results by.
        schema:
          type: string
          enum:
          - updateDate+desc
          - updateDate+asc
          default: updateDate+desc
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 250
          default: 20
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/congress-committee:
    get:
      tags:
      - gov
      summary: List or look up US Congressional committees (Library of
      description: List or look up US Congressional committees (Library of Congress Congress.gov). Pass systemCode (e.g. "hspw00") to fetch a single committee with full detail (members, subcommittees, history, hearings, jurisdiction). Or filter list by congress + chamber (house | senate | joint). Standard system codes follow chamber prefix + abbreviation + suffix convention.
      operationId: gov_congress-committee
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [committee] (lookup mode, total 1) or the committee list (list mode, total = upstream match count); meta.mode flags which.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            systemCode:
                              type: string
                              nullable: true
                            name:
                              type: string
                              nullable: true
                            chamber:
                              type: string
                              nullable: true
                              description: House | Senate | Joint.
                            committeeTypeCode:
                              type: string
                              nullable: true
                              description: e.g. Standing, Select, Joint.
                            url:
                              type: string
                              nullable: true
                              description: Congress.gov API URL for the committee.
                            updateDate:
                              type: string
                              nullable: true
                            parent:
                              type: object
                              additionalProperties: {}
                              nullable: true
                              description: Parent committee reference; null for top-level committees.
                            subcommittees:
                              anyOf:
                              - type: number
                              - type: array
                                items:
                                  type: object
                                  additionalProperties: {}
                              description: Subcommittee count in list mode; raw subcommittee array in lookup mode.
                          additionalProperties: {}
                          description: List mode emits this trimmed shape; systemCode lookup passes the full raw Congress.gov committee detail through (members, history, jurisdiction — extra fields).
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          mode:
                            type: string
                            enum:
                            - lookup
                            - list
                        required:
                        - mode
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.congress-committee
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: congress
        in: query
        required: false
        description: US Congress number (e.g. 118 for the 2023–2025 Congress).
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - name: chamber
        in: query
        required: false
        description: 'Legislative chamber: house or senate.'
        schema:
          type: string
          enum:
          - house
          - senate
          - joint
      - name: systemCode
        in: query
        required: false
        description: System code.
        schema:
          type: string
          pattern: ^[a-z]{2,8}\d{2,4}$
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 250
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/congress-filings:
    get:
      tags:
      - gov
      summary: Track US House members' financial-disclosure filings
      description: 'Track US House members'' financial-disclosure filings — including Periodic Transaction Reports (PTRs), the STOCK Act filings where members must disclose their stock trades within 45 days. Defaults to PTRs; pass type=annual|candidate|amendment|all to see other disclosure kinds. Filter by member name (q), 2-letter state, filing year, or filing-date range (dateFrom/dateTo). Each result gives the member, state + district, filing type (with a readable label), the filing/disclosure date, and a direct link to the source document (docUrl). The envelope total is the full count matching your filter — so q=Pelosi or year=2026 answers ''how many PTRs did they file''. Covers 2008→present (~8,200 PTRs), refreshed daily so new filings appear within ~a day. Note: by law trades are disclosed up to 45 days after they happen — this is current-to-the-filing, not real-time. Data: US House Clerk (public domain).'
      operationId: gov_congress-filings
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = matching filings (newest first); total = full count matching the filter.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            docId:
                              type: string
                            chamber:
                              type: string
                            memberName:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            district:
                              type: string
                              nullable: true
                            filingType:
                              type: string
                              nullable: true
                            filingTypeLabel:
                              type: string
                              nullable: true
                            filingYear:
                              type: number
                              nullable: true
                            filingDate:
                              type: string
                              nullable: true
                            docUrl:
                              type: string
                              nullable: true
                            tradesParsed:
                              type: boolean
                          required:
                          - docId
                          - chamber
                          - memberName
                          - state
                          - district
                          - filingType
                          - filingTypeLabel
                          - filingYear
                          - filingDate
                          - docUrl
                          - tradesParsed
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.congress-filings
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: q
        in: query
        required: false
        description: Free-text search query.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: type
        in: query
        required: false
        description: Filter results by type.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: chamber
        in: query
        required: false
        description: 'Legislative chamber: house or senate.'
        schema:
          type: string
          enum:
          - house
          - senate
      - name: year
        in: query
        required: false
        description: Four-digit calendar year.
        schema:
          type: integer
          minimum: 2008
          maximum: 2100
      - name: dateFrom
        in: query
        required: false
        description: Date from.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: dateTo
        in: query
        required: false
        description: Date to.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          maximum: 100000
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/congress-hearing:
    get:
      tags:
      - gov
      summary: Look up or list US Congressional hearings via Congress.gov
      description: Look up or list US Congressional hearings via Congress.gov. Pass congress + chamber + jacketNumber to fetch a single hearing with full detail (title, dates, committee, transcripts/recordings if available). Or filter list by congress + chamber, with optional date range. Hearings cover committee testimony from the executive branch, subject experts, and stakeholders — primary-source material for oversight + policy research.
      operationId: gov_congress-hearing
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [hearing] (lookup mode, total 1) or the hearing list (list mode, total = upstream match count); meta.mode flags which.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            congress:
                              type: number
                              nullable: true
                            chamber:
                              type: string
                              nullable: true
                              description: House | Senate.
                            jacketNumber:
                              type: number
                              nullable: true
                            updateDate:
                              type: string
                              nullable: true
                            apiUrl:
                              type: string
                              nullable: true
                              description: Congress.gov API URL for the hearing.
                          additionalProperties: {}
                          description: List mode emits this trimmed shape; lookup mode passes the full raw Congress.gov hearing detail through (title, dates, committee, transcript/recording links — extra fields).
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          mode:
                            type: string
                            enum:
                            - lookup
                            - list
                        required:
                        - mode
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.congress-hearing
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: congress
        in: query
        required: false
        description: US Congress number (e.g. 118 for the 2023–2025 Congress).
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - name: chamber
        in: query
        required: false
        description: 'Legislative chamber: house or senate.'
        schema:
          type: string
          enum:
          - house
          - senate
      - name: jacketNumber
        in: query
        required: false
        description: Jacket number.
        schema:
          type: integer
          minimum: 1
      - name: fromDate
        in: query
        required: false
        description: From date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: toDate
        in: query
        required: false
        description: To date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 250
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/congress-member:
    get:
      tags:
      - gov
      summary: Look up or search members of the US Congress via Library of
      description: Look up or search members of the US Congress via Library of Congress Congress.gov API. Pass bioguideId (e.g. M001190) to fetch one member (full bio, terms, party history, leadership roles, sponsored + cosponsored legislation counts, official website, address). Or filter by congress + state + district, with currentMember=true to limit to seated members. Bioguide IDs are stable across history and are the canonical Congress-member identifier.
      operationId: gov_congress-member
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [member] (lookup mode, total 1) or the member list (list mode, total = upstream match count); meta.mode flags which.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            bioguideId:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            district:
                              type: number
                              nullable: true
                            terms:
                              description: 'Service terms; array of term objects in lookup mode, upstream pass-through ({ item: [...] }) in list mode.'
                            depiction:
                              type: object
                              additionalProperties: {}
                              nullable: true
                              description: Official portrait, e.g. { imageUrl, attribution }.
                            name:
                              type: string
                              nullable: true
                              description: List mode only ("Last, First").
                            partyName:
                              type: string
                              nullable: true
                              description: List mode only.
                            directOrderName:
                              type: string
                              nullable: true
                              description: Lookup mode only.
                            firstName:
                              type: string
                              nullable: true
                              description: Lookup mode only.
                            lastName:
                              type: string
                              nullable: true
                              description: Lookup mode only.
                            suffixName:
                              type: string
                              nullable: true
                              description: Lookup mode only.
                            nickName:
                              type: string
                              nullable: true
                              description: Lookup mode only.
                            honorificName:
                              type: string
                              nullable: true
                              description: Lookup mode only.
                            partyHistory:
                              type: array
                              items:
                                type: object
                                additionalProperties: {}
                              description: Lookup mode only.
                            birthYear:
                              type: string
                              nullable: true
                              description: Lookup mode only.
                            deathYear:
                              type: string
                              nullable: true
                              description: Lookup mode only.
                            officialWebsiteUrl:
                              type: string
                              nullable: true
                              description: Lookup mode only.
                            addressInformation:
                              type: object
                              additionalProperties: {}
                              nullable: true
                              description: Office address pass-through; lookup mode only.
                            leadership:
                              type: array
                              items:
                                type: object
                                additionalProperties: {}
                              description: Leadership roles; lookup mode only.
                            sponsoredLegislation:
                              type: object
                              additionalProperties: {}
                              nullable: true
                              description: '{ count, url }; lookup mode only.'
                            cosponsoredLegislation:
                              type: object
                              additionalProperties: {}
                              nullable: true
                              description: '{ count, url }; lookup mode only.'
                            source:
                              $ref: '#/components/schemas/Source'
                          required:
                          - bioguideId
                          - state
                          - district
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          mode:
                            type: string
                            enum:
                            - lookup
                            - list
                        required:
                        - mode
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.congress-member
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: bioguideId
        in: query
        required: false
        description: Bioguide ID.
        schema:
          type: string
          pattern: ^[A-Z]\d{6}$
      - name: congress
        in: query
        required: false
        description: US Congress number (e.g. 118 for the 2023–2025 Congress).
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
      - name: district
        in: query
        required: false
        description: District.
        schema:
          type: integer
          minimum: 0
          maximum: 60
      - name: currentMember
        in: query
        required: false
        description: Current member.
        schema:
          type: boolean
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 250
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/congress-nomination:
    get:
      tags:
      - gov
      summary: Look up or list US presidential nominations (cabinet
      description: 'Look up or list US presidential nominations (cabinet, judicial, executive) sent to the Senate for confirmation via Congress.gov. Pass congress + number for a single nomination with full action history. Or filter list by congress + date range. Each row carries: citation (PN###-#), description (nominee + position), receivedDate, nominationType (civilian / military / etc.), organization, latest action (committee referral, hearing, confirmation, withdrawal). Essential for confirmation-tracking + judicial-vetting agents.'
      operationId: gov_congress-nomination
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [nomination] (lookup mode, total 1) or the nomination list (list mode, total = upstream match count); meta.mode flags which.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            congress:
                              type: number
                              nullable: true
                            number:
                              type: number
                              nullable: true
                            partNumber:
                              type: string
                              nullable: true
                            citation:
                              type: string
                              nullable: true
                              description: PN citation, e.g. PN11-16.
                            description:
                              type: string
                              nullable: true
                              description: Nominee + position.
                            receivedDate:
                              type: string
                              nullable: true
                            latestAction:
                              type: object
                              additionalProperties: {}
                              nullable: true
                              description: Upstream pass-through, e.g. { actionDate, text }.
                            nominationType:
                              type: object
                              additionalProperties: {}
                              nullable: true
                              description: Upstream pass-through, e.g. { isCivilian, isMilitary }.
                            organization:
                              type: string
                              nullable: true
                            updateDate:
                              type: string
                              nullable: true
                            apiUrl:
                              type: string
                              nullable: true
                              description: Congress.gov API URL for the nomination.
                          additionalProperties: {}
                          description: List mode emits this trimmed shape; lookup mode passes the full raw Congress.gov nomination detail through (full action history — extra fields).
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          mode:
                            type: string
                            enum:
                            - lookup
                            - list
                        required:
                        - mode
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.congress-nomination
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: congress
        in: query
        required: false
        description: US Congress number (e.g. 118 for the 2023–2025 Congress).
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - name: number
        in: query
        required: false
        description: Item number or identifier.
        schema:
          type: integer
          minimum: 1
      - name: fromDate
        in: query
        required: false
        description: From date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: toDate
        in: query
        required: false
        description: To date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 250
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/congress-record:
    get:
      tags:
      - gov
      summary: List daily Congressional Record issues via Congress.gov
      description: List daily Congressional Record issues via Congress.gov — the official transcripts and proceedings of the US House and Senate, daily. Filter by year + month + day to narrow to a specific date or month. Each issue carries volume, issue number, publish date, and links to per-section content (Daily Digest, Senate, House, Extensions of Remarks) with PDF + sub-section URLs. Primary source for what was said on the floor.
      operationId: gov_congress-record
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = Congressional Record issues (id, congress, session, issue, volume, publishDate, links); total = null (upstream paginates without a true count).'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              nullable: true
                            congress:
                              type: string
                              nullable: true
                            session:
                              type: string
                              nullable: true
                            issue:
                              type: string
                              nullable: true
                            volume:
                              type: string
                              nullable: true
                            publishDate:
                              type: string
                              nullable: true
                            links:
                              type: object
                              additionalProperties: {}
                              nullable: true
                              description: 'Upstream pass-through: per-section links (Daily Digest, Senate, House, Extensions of Remarks) with PDF + sub-section URLs.'
                          required:
                          - id
                          - congress
                          - session
                          - issue
                          - volume
                          - publishDate
                          - links
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.congress-record
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: year
        in: query
        required: false
        description: Four-digit calendar year.
        schema:
          type: integer
          minimum: 1873
          maximum: 2100
      - name: month
        in: query
        required: false
        description: Calendar month (1–12).
        schema:
          type: integer
          minimum: 1
          maximum: 12
      - name: day
        in: query
        required: false
        description: Day of the month (1–31).
        schema:
          type: integer
          minimum: 1
          maximum: 31
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/congress-trades:
    get:
      tags:
      - gov
      summary: Search individual US Congress member stock trades, parsed
      description: 'Search individual US Congress member stock trades, parsed from STOCK Act Periodic Transaction Reports into clean rows. Filter by member name (q, e.g. "Pelosi"), ticker (e.g. NVDA), transaction type (purchase | sale | exchange | partial_sale), party (D | R | I), 2-letter state, chamber, or transaction-date range (dateFrom/dateTo). Each trade returns the member + party + state/district, owner (self/spouse/joint/dependent), ticker + asset description, buy/sell, the disclosed dollar RANGE (amountMin/amountMax — disclosures are ranges, not exact), the transaction date, the disclosure date, days-to-disclose (compliance lag), and a link to the source filing PDF. The envelope total is the full count matching your filter — so ticker=NVDA&type=purchase counts who bought NVIDIA. Amounts are ranges by law; trades are disclosed up to 45 days after they happen (current-to-the-filing). Coverage: US House + Senate e-filed PTRs; scanned/handwritten reports are parsed separately. Data: US House Clerk / US Senate eFD (public domain). Cross-ref /api/gov/congress-filings for the raw filing index.'
      operationId: gov_congress-trades
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = matching trades (newest transaction first); total = full count matching the filter.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            member:
                              type: string
                              nullable: true
                            chamber:
                              type: string
                            party:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            district:
                              type: string
                              nullable: true
                            owner:
                              type: string
                              nullable: true
                            ticker:
                              type: string
                              nullable: true
                            assetDescription:
                              type: string
                              nullable: true
                            assetType:
                              type: string
                              nullable: true
                            transactionType:
                              type: string
                              nullable: true
                            amountMin:
                              type: number
                              nullable: true
                            amountMax:
                              type: number
                              nullable: true
                            transactionDate:
                              type: string
                              nullable: true
                            disclosureDate:
                              type: string
                              nullable: true
                            daysToDisclose:
                              type: number
                              nullable: true
                            docUrl:
                              type: string
                              nullable: true
                            source:
                              type: string
                              nullable: true
                          required:
                          - member
                          - chamber
                          - party
                          - state
                          - district
                          - owner
                          - ticker
                          - assetDescription
                          - assetType
                          - transactionType
                          - amountMin
                          - amountMax
                          - transactionDate
                          - disclosureDate
                          - daysToDisclose
                          - docUrl
                          - source
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.congress-trades
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: q
        in: query
        required: false
        description: Free-text search query.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: ticker
        in: query
        required: false
        description: Ticker.
        schema:
          type: string
          minLength: 1
          maxLength: 10
      - name: type
        in: query
        required: false
        description: Filter results by type.
        schema:
          type: string
          minLength: 1
          maxLength: 20
      - name: chamber
        in: query
        required: false
        description: 'Legislative chamber: house or senate.'
        schema:
          type: string
          enum:
          - house
          - senate
      - name: party
        in: query
        required: false
        description: Party.
        schema:
          type: string
          minLength: 1
          maxLength: 11
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: dateFrom
        in: query
        required: false
        description: Date from.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: dateTo
        in: query
        required: false
        description: Date to.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          maximum: 100000
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/congress-treaty:
    get:
      tags:
      - gov
      summary: Look up or list international treaties transmitted to the
      description: Look up or list international treaties transmitted to the US Senate for advice and consent via Congress.gov. Pass congress + number (optionally + suffix for partitioned treaties) to fetch a single treaty with parties, topic, transmittal date, and consideration status. Or list by congress. Returns the congress the treaty was received in, the congress that considered it (if any), partial-treaty suffix, topic, transmitted date, and count of parties.
      operationId: gov_congress-treaty
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [treaty] (lookup mode, total 1) or the treaty list (list mode, total = upstream match count); meta.mode flags which.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            congressReceived:
                              type: number
                              nullable: true
                              description: Congress the treaty was received in.
                            congressConsidered:
                              type: number
                              nullable: true
                              description: Congress that considered it; null if none.
                            number:
                              type: number
                              nullable: true
                            suffix:
                              type: string
                              nullable: true
                              description: Partition letter for partitioned treaties, e.g. "A".
                            topic:
                              type: string
                              nullable: true
                            transmittedDate:
                              type: string
                              nullable: true
                            updateDate:
                              type: string
                              nullable: true
                            countriesPartiesCount:
                              type: number
                              nullable: true
                          additionalProperties: {}
                          description: List mode emits this trimmed shape; lookup mode passes the full raw Congress.gov treaty detail through (parties, actions — extra fields).
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          mode:
                            type: string
                            enum:
                            - lookup
                            - list
                        required:
                        - mode
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.congress-treaty
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: congress
        in: query
        required: false
        description: US Congress number (e.g. 118 for the 2023–2025 Congress).
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - name: number
        in: query
        required: false
        description: Item number or identifier.
        schema:
          type: integer
          minimum: 1
      - name: suffix
        in: query
        required: false
        description: Suffix.
        schema:
          type: string
          pattern: ^[A-Za-z]$
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 250
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/contract-opportunities:
    get:
      tags:
      - gov
      summary: Search ACTIVE US federal contract opportunities
      description: 'Search ACTIVE US federal contract opportunities (solicitations, combined synopses, sources-sought, RFPs/RFQs) from SAM.gov. Requires a posted-date window: postedFrom and postedTo as MM/DD/YYYY, max 1 year span. Optional filters: title (keyword), naics (NAICS code), state (place/office 2-letter), setAside (set-aside code, e.g. SBA, 8A, WOSB, SDVOSBC), ptype (notice type: o=solicitation, p=presolicitation, r=sources-sought, k=combined, etc.); page with limit (1-100) and offset. Returns each opportunity with notice id, title, solicitation number, type, department path, posted date, response deadline, NAICS, classification, set-aside, active flag, contracting office location, and a sam.gov UI link — plus a total match count. Data: SAM.gov, free and public-domain. Distinct from /api/gov/usaspending-awards (past awards) — this is what is OPEN to bid now. Fresh, time-sensitive data for govcon / capture / bid-intelligence agents.'
      operationId: gov_contract-opportunities
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = matching active opportunities (newest postings as ranked by SAM), total = SAM total match count.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            noticeId:
                              type: string
                              nullable: true
                            title:
                              type: string
                              nullable: true
                            solicitationNumber:
                              type: string
                              nullable: true
                            type:
                              type: string
                              nullable: true
                            department:
                              type: string
                              nullable: true
                            postedDate:
                              type: string
                              nullable: true
                            responseDeadline:
                              type: string
                              nullable: true
                            naicsCode:
                              type: string
                              nullable: true
                            classificationCode:
                              type: string
                              nullable: true
                            setAside:
                              type: string
                              nullable: true
                            active:
                              type: boolean
                              nullable: true
                            organizationType:
                              type: string
                              nullable: true
                            office:
                              type: object
                              properties:
                                city:
                                  type: string
                                  nullable: true
                                state:
                                  type: string
                                  nullable: true
                                zip:
                                  type: string
                                  nullable: true
                                country:
                                  type: string
                                  nullable: true
                              required:
                              - city
                              - state
                              - zip
                              - country
                              additionalProperties: false
                              nullable: true
                            uiLink:
                              type: string
                              nullable: true
                          required:
                          - noticeId
                          - title
                          - solicitationNumber
                          - type
                          - department
                          - postedDate
                          - responseDeadline
                          - naicsCode
                          - classificationCode
                          - setAside
                          - active
                          - organizationType
                          - office
                          - uiLink
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              postedFrom:
                                type: string
                              postedTo:
                                type: string
                              title:
                                type: string
                                nullable: true
                              naics:
                                type: string
                                nullable: true
                              state:
                                type: string
                                nullable: true
                              setAside:
                                type: string
                                nullable: true
                              ptype:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                              offset:
                                type: integer
                            required:
                            - postedFrom
                            - postedTo
                            - title
                            - naics
                            - state
                            - setAside
                            - ptype
                            - limit
                            - offset
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.contract-opportunities
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: postedFrom
        in: query
        required: true
        description: Posted from.
        schema:
          type: string
          pattern: ^(0[1-9]|1[0-2])\/(0[1-9]|[12]\d|3[01])\/\d{4}$
      - name: postedTo
        in: query
        required: true
        description: Posted to.
        schema:
          type: string
          pattern: ^(0[1-9]|1[0-2])\/(0[1-9]|[12]\d|3[01])\/\d{4}$
      - name: title
        in: query
        required: false
        description: Title to search for.
        schema:
          type: string
          minLength: 2
          maxLength: 200
      - name: naics
        in: query
        required: false
        description: NAICS.
        schema:
          type: string
          pattern: ^\d{2,6}$
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: setAside
        in: query
        required: false
        description: Set aside.
        schema:
          type: string
          minLength: 2
          maxLength: 12
      - name: ptype
        in: query
        required: false
        description: Ptype.
        schema:
          type: string
          minLength: 1
          maxLength: 2
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          maximum: 10000
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/counterparty:
    get:
      tags:
      - gov
      summary: Federal counterparty due-diligence dossier on one name, in
      description: 'Federal counterparty due-diligence dossier on one name, in a single call. Give name (a company or person) and optional state; get back six independent federal/authoritative screens composed into one verdict: SAM.gov registration (UEI/CAGE, active status), SAM federal exclusions (debarment/suspension), OFAC SDN sanctions, GLEIF Legal Entity Identifier, USAspending federal contract-award history, and FARA foreign-agent registration. Returns headline riskFlags (e.g. federally_debarred, sanctions_high_confidence_match, registered_foreign_agent), a cleared boolean (true only when both debarment AND sanctions sources answered and were clean — FARA status is disclosure context and does NOT affect cleared), a summary of booleans, and a per-source found/error/data block so one slow or empty source never fails the whole call. Composition of /api/gov/entity + /api/gov/exclusions + /api/law/sanctions-check + /api/business/lei + /api/gov/usaspending-awards + /api/gov/foreign-agents — all free, public-domain US data. Name matching is probabilistic: review flagged matches manually and confirm with a hard identifier (UEI, LEI) before acting. For vendor onboarding, KYC/AML triage, grant eligibility, and procurement integrity. The federal counterpart to /api/business/entity-screen (which covers state registries).'
      operationId: gov_counterparty
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      query:
                        type: object
                        properties:
                          name:
                            type: string
                          state:
                            type: string
                            nullable: true
                        required:
                        - name
                        - state
                        additionalProperties: false
                      riskFlags:
                        type: array
                        items:
                          type: string
                      cleared:
                        type: boolean
                      summary:
                        type: object
                        properties:
                          samRegistered:
                            type: boolean
                            nullable: true
                          activeRegistration:
                            type: boolean
                            nullable: true
                          isDebarred:
                            type: boolean
                            nullable: true
                          isSanctioned:
                            type: boolean
                            nullable: true
                          hasLei:
                            type: boolean
                            nullable: true
                          federalAwardCount:
                            type: number
                            nullable: true
                          isForeignAgent:
                            type: boolean
                            nullable: true
                        required:
                        - samRegistered
                        - activeRegistration
                        - isDebarred
                        - isSanctioned
                        - hasLei
                        - federalAwardCount
                        - isForeignAgent
                        additionalProperties: false
                      registration:
                        type: object
                        properties:
                          found:
                            type: boolean
                          error:
                            type: string
                            nullable: true
                          data:
                            type: object
                            additionalProperties: {}
                            nullable: true
                        required:
                        - found
                        - error
                        - data
                        additionalProperties: false
                      exclusions:
                        type: object
                        properties:
                          found:
                            type: boolean
                          error:
                            type: string
                            nullable: true
                          data:
                            type: object
                            additionalProperties: {}
                            nullable: true
                        required:
                        - found
                        - error
                        - data
                        additionalProperties: false
                      sanctions:
                        type: object
                        properties:
                          found:
                            type: boolean
                          error:
                            type: string
                            nullable: true
                          data:
                            type: object
                            additionalProperties: {}
                            nullable: true
                        required:
                        - found
                        - error
                        - data
                        additionalProperties: false
                      lei:
                        type: object
                        properties:
                          found:
                            type: boolean
                          error:
                            type: string
                            nullable: true
                          data:
                            type: object
                            additionalProperties: {}
                            nullable: true
                        required:
                        - found
                        - error
                        - data
                        additionalProperties: false
                      federalAwards:
                        type: object
                        properties:
                          found:
                            type: boolean
                          error:
                            type: string
                            nullable: true
                          data:
                            type: object
                            additionalProperties: {}
                            nullable: true
                        required:
                        - found
                        - error
                        - data
                        additionalProperties: false
                      foreignAgent:
                        type: object
                        properties:
                          found:
                            type: boolean
                          error:
                            type: string
                            nullable: true
                          data:
                            type: object
                            additionalProperties: {}
                            nullable: true
                        required:
                        - found
                        - error
                        - data
                        additionalProperties: false
                      sources:
                        type: array
                        items:
                          $ref: '#/components/schemas/Source'
                      note:
                        type: string
                    required:
                    - query
                    - riskFlags
                    - cleared
                    - summary
                    - registration
                    - exclusions
                    - sanctions
                    - lei
                    - federalAwards
                    - foreignAgent
                    - sources
                    - note
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.counterparty
      x-2s-version: null
      x-2s-price:
        usd: 0.018
      x-2s-accepts:
      - x402
      x-2s-response-shape: legacy
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.018000'
        protocols:
        - x402: {}
      parameters:
      - name: name
        in: query
        required: true
        description: Name to search for.
        schema:
          type: string
          minLength: 2
          maxLength: 200
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: threshold
        in: query
        required: false
        description: Minimum score/threshold required to include a result.
        schema:
          type: number
          minimum: 0.1
          maximum: 1
          default: 0.4
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 20
          default: 5
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/disaster-assistance:
    get:
      tags:
      - gov
      summary: FEMA disaster assistance dollars - how much federal aid was
      description: 'FEMA disaster assistance dollars — how much federal aid was approved or obligated for a declared disaster, by place. program=individuals (default) returns Individuals & Households Program (IHP) approved housing assistance, one record per ZIP per disaster, with FEMA-approved repair/replace, rental, and other-needs dollars and valid-registration counts (tenancy=owner default, or renter). program=public returns Public Assistance funded-project summaries, one record per applicant (state/local government, tribe, or eligible nonprofit) per disaster, with the federally obligated grant amount and project count. Filter by disasterNumber (the join key to gov.disaster-declarations), state (2-letter), and zipCode (5-digit, IHP only); results are ordered by approved/obligated dollars, highest first, with the total matching count and a normalized approvedAmountUSD per record. Free, public-domain (OpenFEMA). Distinct from gov.disaster-declarations (which disasters were declared + what was authorized), gov.risk-index (modeled future risk), and gov.nfip-claims (flood-insurance losses): this is the realized federal-spend record — for disaster-recovery, grants, insurance, and emergency-management workflows.'
      operationId: gov_disaster-assistance
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      query:
                        type: object
                        properties:
                          program:
                            type: string
                          tenancy:
                            type: string
                            nullable: true
                          disasterNumber:
                            type: number
                            nullable: true
                          state:
                            type: string
                            nullable: true
                          zipCode:
                            type: string
                            nullable: true
                          limit:
                            type: number
                        required:
                        - program
                        - tenancy
                        - disasterNumber
                        - state
                        - zipCode
                        - limit
                        additionalProperties: false
                      program:
                        type: string
                      totalRecords:
                        type: number
                        nullable: true
                      returned:
                        type: number
                      returnedSumApprovedUSD:
                        type: number
                      records:
                        type: array
                        items:
                          type: object
                          properties:
                            program:
                              type: string
                            disasterNumber:
                              type: number
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            county:
                              type: string
                              nullable: true
                            approvedAmountUSD:
                              type: number
                              nullable: true
                            tenancy:
                              type: string
                              nullable: true
                            city:
                              type: string
                              nullable: true
                            zipCode:
                              type: string
                              nullable: true
                            validRegistrations:
                              type: number
                              nullable: true
                            approvedForFemaAssistance:
                              type: number
                              nullable: true
                            repairReplaceAmount:
                              type: number
                              nullable: true
                            rentalAmount:
                              type: number
                              nullable: true
                            otherNeedsAmount:
                              type: number
                              nullable: true
                            applicantName:
                              type: string
                              nullable: true
                            educationApplicant:
                              type: boolean
                              nullable: true
                            numberOfProjects:
                              type: number
                              nullable: true
                            incidentType:
                              type: string
                              nullable: true
                            declarationDate:
                              type: string
                              nullable: true
                          required:
                          - program
                          - disasterNumber
                          - state
                          - county
                          - approvedAmountUSD
                          - tenancy
                          - city
                          - zipCode
                          - validRegistrations
                          - approvedForFemaAssistance
                          - repairReplaceAmount
                          - rentalAmount
                          - otherNeedsAmount
                          - applicantName
                          - educationApplicant
                          - numberOfProjects
                          - incidentType
                          - declarationDate
                          additionalProperties: false
                      source:
                        $ref: '#/components/schemas/Source'
                      note:
                        type: string
                    required:
                    - query
                    - program
                    - totalRecords
                    - returned
                    - returnedSumApprovedUSD
                    - records
                    - source
                    - note
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.disaster-assistance
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: legacy
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: program
        in: query
        required: false
        description: '''individuals'' (IHP, default) or ''public''.'
        schema:
          type: string
          enum:
          - individuals
          - public
      - name: tenancy
        in: query
        required: false
        description: 'For program=individuals: ''owner'' (default) or ''renter''.'
        schema:
          type: string
          enum:
          - owner
          - renter
      - name: disasterNumber
        in: query
        required: false
        description: FEMA disaster number.
        schema:
          type: integer
          minimum: 1
          maximum: 99999
      - name: state
        in: query
        required: false
        description: 2-letter US state/territory code.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: zipCode
        in: query
        required: false
        description: 5-digit ZIP (IHP only).
        schema:
          type: string
          pattern: ^\d{5}$
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/disaster-declarations:
    get:
      tags:
      - gov
      summary: FEMA federal disaster & emergency declarations - every
      description: 'FEMA federal disaster & emergency declarations — every federally declared disaster since 1953, including the ones declared this week. Filter by state (2-letter), disasterNumber, declarationType (DR=major disaster, EM=emergency, FM/FS/FW=fire management), incidentType (e.g. Hurricane, Fire, Flood, Severe Storm), county (5-digit FIPS), fiscal year (fyDeclared), and declaration date range (fromDate/toDate, YYYY-MM-DD). With no filter, returns the most recent declarations nationwide. Returns the total matching count plus records (one per designated county/area) with the declaration string, disaster number, title, incident type, declaration + incident begin/end + closeout dates, designated area, county FIPS, FEMA region, and the assistance programs authorized (Individuals & Households, Individual Assistance, Public Assistance, Hazard Mitigation). Free, public-domain (OpenFEMA). Distinct from gov.risk-index (modeled future risk) and gov.nfip-claims (realized flood losses): this is the official federal-response record — for disaster-response logistics, eligibility checks, insurance, and emergency-management workflows.'
      operationId: gov_disaster-declarations
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      query:
                        type: object
                        properties:
                          state:
                            type: string
                            nullable: true
                          disasterNumber:
                            type: number
                            nullable: true
                          declarationType:
                            type: string
                            nullable: true
                          incidentType:
                            type: string
                            nullable: true
                          county:
                            type: string
                            nullable: true
                          fyDeclared:
                            type: number
                            nullable: true
                          fromDate:
                            type: string
                            nullable: true
                          toDate:
                            type: string
                            nullable: true
                          limit:
                            type: number
                        required:
                        - state
                        - disasterNumber
                        - declarationType
                        - incidentType
                        - county
                        - fyDeclared
                        - fromDate
                        - toDate
                        - limit
                        additionalProperties: false
                      totalDeclarations:
                        type: number
                        nullable: true
                      returned:
                        type: number
                      declarations:
                        type: array
                        items:
                          type: object
                          properties:
                            femaDeclarationString:
                              type: string
                              nullable: true
                            disasterNumber:
                              type: number
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            declarationType:
                              type: string
                              nullable: true
                            declarationTypeLabel:
                              type: string
                              nullable: true
                            declarationTitle:
                              type: string
                              nullable: true
                            incidentType:
                              type: string
                              nullable: true
                            declarationDate:
                              type: string
                              nullable: true
                            fyDeclared:
                              type: number
                              nullable: true
                            incidentBeginDate:
                              type: string
                              nullable: true
                            incidentEndDate:
                              type: string
                              nullable: true
                            disasterCloseoutDate:
                              type: string
                              nullable: true
                            designatedArea:
                              type: string
                              nullable: true
                            countyFips:
                              type: string
                              nullable: true
                            region:
                              type: number
                              nullable: true
                            tribalRequest:
                              type: boolean
                              nullable: true
                            programs:
                              type: object
                              properties:
                                individualsAndHouseholds:
                                  type: boolean
                                  nullable: true
                                individualAssistance:
                                  type: boolean
                                  nullable: true
                                publicAssistance:
                                  type: boolean
                                  nullable: true
                                hazardMitigation:
                                  type: boolean
                                  nullable: true
                              required:
                              - individualsAndHouseholds
                              - individualAssistance
                              - publicAssistance
                              - hazardMitigation
                              additionalProperties: false
                          required:
                          - femaDeclarationString
                          - disasterNumber
                          - state
                          - declarationType
                          - declarationTypeLabel
                          - declarationTitle
                          - incidentType
                          - declarationDate
                          - fyDeclared
                          - incidentBeginDate
                          - incidentEndDate
                          - disasterCloseoutDate
                          - designatedArea
                          - countyFips
                          - region
                          - tribalRequest
                          - programs
                          additionalProperties: false
                      source:
                        $ref: '#/components/schemas/Source'
                      note:
                        type: string
                    required:
                    - query
                    - totalDeclarations
                    - returned
                    - declarations
                    - source
                    - note
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.disaster-declarations
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: legacy
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: state
        in: query
        required: false
        description: 2-letter US state/territory code.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: disasterNumber
        in: query
        required: false
        description: FEMA disaster number.
        schema:
          type: integer
          minimum: 1
          maximum: 99999
      - name: declarationType
        in: query
        required: false
        description: DR, EM, FM, FS, or FW.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: incidentType
        in: query
        required: false
        description: Incident type, e.g. Hurricane, Fire, Flood.
        schema:
          type: string
          minLength: 2
          maxLength: 60
      - name: county
        in: query
        required: false
        description: County name to filter by.
        schema:
          type: string
          pattern: ^\d{5}$
      - name: fyDeclared
        in: query
        required: false
        description: Fy declared.
        schema:
          type: integer
          minimum: 1953
          maximum: 2100
      - name: fromDate
        in: query
        required: false
        description: From date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: toDate
        in: query
        required: false
        description: To date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/district:
    get:
      tags:
      - gov
      summary: Resolve a US street address to its congressional district
      description: Resolve a US street address to its congressional district (119th Congress), state, and county, via the US Census Bureau geocoder. Returns the matched/normalized address, latitude/longitude, state (name + 2-letter abbreviation), county, and the district number within the state (null for at-large or non-voting delegate districts). The point-in-polygon district lookup is something an agent can't do from a sandbox. Pair it with the gov/congress.* endpoints to find the representatives once you have the state + district. Public domain, keyless.
      operationId: gov_district
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items[0] = the geocoded district + state + county.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            matchedAddress:
                              type: string
                              nullable: true
                            coordinates:
                              type: object
                              properties:
                                lat:
                                  type: number
                                  nullable: true
                                lon:
                                  type: number
                                  nullable: true
                              required:
                              - lat
                              - lon
                              additionalProperties: false
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            stateAbbr:
                              type: string
                              nullable: true
                            stateFips:
                              type: string
                              nullable: true
                            county:
                              type: string
                              nullable: true
                            congress:
                              type: string
                            district:
                              type: string
                              nullable: true
                              description: District number within the state (null = at-large/delegate).
                            districtName:
                              type: string
                              nullable: true
                          required:
                          - matchedAddress
                          - coordinates
                          - state
                          - stateAbbr
                          - stateFips
                          - county
                          - congress
                          - district
                          - districtName
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          source:
                            type: string
                        required:
                        - source
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.district
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: address
        in: query
        required: true
        description: A US street address (one line, e.g. "1600 Pennsylvania Ave NW, Washington, DC 20500").
        schema:
          type: string
          minLength: 5
          maxLength: 300
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/entity:
    get:
      tags:
      - gov
      summary: Look up entities registered to do business with the US
      description: 'Look up entities registered to do business with the US federal government in SAM.gov. Search by ueiSAM (12-char Unique Entity ID), cageCode, or legalBusinessName (provide at least one); page with limit (1-100). Returns each entity with its UEI, CAGE code, legal and DBA name, SAM registration status and dates (registration, expiration, last update), purpose of registration, an active-exclusion flag, physical address, and business types — plus a total match count. Data: SAM.gov entity management, free and public-domain (registration core data; sensitive FOUO sections are not returned). The canonical federal counterparty identity key — pair with /api/gov/exclusions (debarment) and /api/law/sanctions-check (OFAC) for full counterparty due diligence.'
      operationId: gov_entity
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = matching SAM entities, total = SAM total match count.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            ueiSAM:
                              type: string
                              nullable: true
                            cageCode:
                              type: string
                              nullable: true
                            legalBusinessName:
                              type: string
                              nullable: true
                            dbaName:
                              type: string
                              nullable: true
                            samRegistered:
                              type: boolean
                              nullable: true
                            registrationStatus:
                              type: string
                              nullable: true
                            registrationDate:
                              type: string
                              nullable: true
                            registrationExpirationDate:
                              type: string
                              nullable: true
                            lastUpdateDate:
                              type: string
                              nullable: true
                            purposeOfRegistration:
                              type: string
                              nullable: true
                            hasActiveExclusion:
                              type: boolean
                              nullable: true
                            physicalAddress:
                              type: object
                              properties:
                                city:
                                  type: string
                                  nullable: true
                                state:
                                  type: string
                                  nullable: true
                                zip:
                                  type: string
                                  nullable: true
                                country:
                                  type: string
                                  nullable: true
                              required:
                              - city
                              - state
                              - zip
                              - country
                              additionalProperties: false
                              nullable: true
                            businessTypes:
                              type: array
                              items:
                                type: string
                          required:
                          - ueiSAM
                          - cageCode
                          - legalBusinessName
                          - dbaName
                          - samRegistered
                          - registrationStatus
                          - registrationDate
                          - registrationExpirationDate
                          - lastUpdateDate
                          - purposeOfRegistration
                          - hasActiveExclusion
                          - physicalAddress
                          - businessTypes
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              legalBusinessName:
                                type: string
                                nullable: true
                              ueiSAM:
                                type: string
                                nullable: true
                              cageCode:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                            required:
                            - legalBusinessName
                            - ueiSAM
                            - cageCode
                            - limit
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.entity
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: legalBusinessName
        in: query
        required: false
        description: Legal business name.
        schema:
          type: string
          minLength: 2
          maxLength: 200
      - name: ueiSAM
        in: query
        required: false
        description: Uei sam.
        schema:
          type: string
          minLength: 12
          maxLength: 12
      - name: cageCode
        in: query
        required: false
        description: Cage code.
        schema:
          type: string
          minLength: 3
          maxLength: 10
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/epa-facilities:
    get:
      tags:
      - gov
      summary: EPA Facility Registry Service (FRS) - every regulated
      description: EPA Facility Registry Service (FRS) — every regulated facility known to the EPA across all programs (RCRA hazardous waste, NPDES water discharge, SDWA drinking water, TRI toxic release, CAA Clean Air, Superfund, etc.). Filter by state (required), facility name prefix, and EPA program acronym. Each record includes registry ID, primary name, address, city/state/county/zip, EPA region, program system + ID, source-of-data system. Public-domain US government records.
      operationId: gov_epa-facilities
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = EPA-regulated facilities (state/name/program filtered); total = null (Envirofacts does not report a match count); meta.query echoes the search.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            registryId:
                              type: string
                            primaryName:
                              type: string
                              nullable: true
                            locationAddress:
                              type: string
                              nullable: true
                            city:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            postalCode:
                              type: string
                              nullable: true
                            county:
                              type: string
                              nullable: true
                            epaRegion:
                              type: string
                              nullable: true
                            programSystem:
                              type: string
                              nullable: true
                            pgmSysId:
                              type: string
                              nullable: true
                            sourceOfData:
                              type: string
                              nullable: true
                            publicIndicator:
                              type: string
                              nullable: true
                          required:
                          - registryId
                          - primaryName
                          - locationAddress
                          - city
                          - state
                          - postalCode
                          - county
                          - epaRegion
                          - programSystem
                          - pgmSysId
                          - sourceOfData
                          - publicIndicator
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              state:
                                type: string
                              name:
                                type: string
                                nullable: true
                              program:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                              offset:
                                type: integer
                            required:
                            - state
                            - name
                            - program
                            - limit
                            - offset
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.epa-facilities
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: state
        in: query
        required: true
        description: '2-letter US state code. Required. Example: "CA", "TX", "NY".'
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
      - name: name
        in: query
        required: false
        description: 'Facility-name prefix match (case-insensitive). Example: "TESLA", "BOEING", "AMAZON".'
        schema:
          type: string
          minLength: 2
          maxLength: 80
      - name: program
        in: query
        required: false
        description: 'Program system acronym. Examples: RCRA (hazardous waste), NPDES (water discharge), TRI (toxic release), AIR (Clean Air), SDWA (drinking water).'
        schema:
          type: string
          minLength: 2
          maxLength: 10
          pattern: ^[A-Za-z0-9]+$
      - name: limit
        in: query
        required: false
        description: Max facilities to return (1-100). Default 25.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        required: false
        description: Offset for pagination. Default 0.
        schema:
          type: integer
          minimum: 0
          maximum: 10000
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/eu-tenders:
    get:
      tags:
      - gov
      summary: Search EU public-procurement notices from TED (Tenders
      description: 'Search EU public-procurement notices from TED (Tenders Electronic Daily) — the official journal of European public tenders. Filter by country (ISO 3-letter buyer country, e.g. DEU, FRA, ESP), cpv (Common Procurement Vocabulary code/prefix, e.g. 72000000 = IT services), and/or keyword (full-text). Each result: publication number, English title, buyer name + country, publication date, tender deadline, CPV codes, notice + procedure type, total value, and links to the notice page + PDF. Power users can pass a raw `query` in TED''s expert query language (e.g. ''(buyer-country=FRA) AND (FT~"hospital")''). Free, reusable EU open data (attribution). Live procurement intelligence agents can''t get from training — for bid discovery, market research, and supplier monitoring across all EU member states.'
      operationId: gov_eu-tenders
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = matching notices (page slice); total = total matching across all pages.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            publicationNumber:
                              type: string
                              nullable: true
                            title:
                              type: string
                              nullable: true
                            buyer:
                              type: string
                              nullable: true
                            buyerCountry:
                              type: string
                              nullable: true
                            publicationDate:
                              type: string
                              nullable: true
                            deadline:
                              type: string
                              nullable: true
                            cpvCodes:
                              type: array
                              items:
                                type: string
                            noticeType:
                              type: string
                              nullable: true
                            procedureType:
                              type: string
                              nullable: true
                            totalValue: {}
                            url:
                              type: string
                              nullable: true
                            pdfUrl:
                              type: string
                              nullable: true
                          required:
                          - publicationNumber
                          - title
                          - buyer
                          - buyerCountry
                          - publicationDate
                          - deadline
                          - cpvCodes
                          - noticeType
                          - procedureType
                          - url
                          - pdfUrl
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.eu-tenders
      x-2s-version: null
      x-2s-price:
        usd: 0.0048
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004800'
        protocols:
        - x402: {}
      parameters:
      - name: country
        in: query
        required: false
        description: Country name or ISO country code.
        schema:
          type: string
          minLength: 2
          maxLength: 3
      - name: cpv
        in: query
        required: false
        description: Cpv.
        schema:
          type: string
          minLength: 2
          maxLength: 8
          pattern: ^\d+$
      - name: keyword
        in: query
        required: false
        description: Keyword.
        schema:
          type: string
          minLength: 1
          maxLength: 100
      - name: query
        in: query
        required: false
        description: Free-text search query.
        schema:
          type: string
          minLength: 1
          maxLength: 500
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - name: page
        in: query
        required: false
        description: Page number (1-based) for paginated results.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/exclusions:
    get:
      tags:
      - gov
      summary: Check whether a person or company is excluded (debarred or
      description: 'Check whether a person or company is excluded (debarred or suspended) from receiving US federal contracts, grants, or assistance — the SAM.gov Exclusions list. Search by name (person or entity), ueiSAM, cageCode, and/or classificationType (Individual, Firm, Vessel, Special Entity Designation); page with limit (1-100). Returns each exclusion with the excluded name, classification, exclusion type and program, the excluding agency, UEI, activation and termination dates, and address — plus a total match count. Data: SAM.gov exclusions, free and public-domain. Distinct from /api/law/sanctions-check (OFAC sanctions) — this is federal procurement debarment. Use for vendor onboarding, grant eligibility, and counterparty due diligence; pair with /api/gov/entity and /api/law/sanctions-check.'
      operationId: gov_exclusions
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = matching exclusion records, total = SAM total match count. meta.hasExclusion is the headline boolean.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              nullable: true
                            classificationType:
                              type: string
                              nullable: true
                            exclusionType:
                              type: string
                              nullable: true
                            exclusionProgram:
                              type: string
                              nullable: true
                            excludingAgency:
                              type: string
                              nullable: true
                            ueiSAM:
                              type: string
                              nullable: true
                            activationDate:
                              type: string
                              nullable: true
                            terminationDate:
                              type: string
                              nullable: true
                            address:
                              type: object
                              properties:
                                city:
                                  type: string
                                  nullable: true
                                state:
                                  type: string
                                  nullable: true
                                country:
                                  type: string
                                  nullable: true
                              required:
                              - city
                              - state
                              - country
                              additionalProperties: false
                              nullable: true
                          required:
                          - name
                          - classificationType
                          - exclusionType
                          - exclusionProgram
                          - excludingAgency
                          - ueiSAM
                          - activationDate
                          - terminationDate
                          - address
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              name:
                                type: string
                                nullable: true
                              ueiSAM:
                                type: string
                                nullable: true
                              cageCode:
                                type: string
                                nullable: true
                              classificationType:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                            required:
                            - name
                            - ueiSAM
                            - cageCode
                            - classificationType
                            - limit
                            additionalProperties: false
                          hasExclusion:
                            type: boolean
                            description: True when at least one exclusion matched the query.
                        required:
                        - query
                        - hasExclusion
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.exclusions
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: name
        in: query
        required: false
        description: Name to search for.
        schema:
          type: string
          minLength: 2
          maxLength: 200
      - name: ueiSAM
        in: query
        required: false
        description: Uei sam.
        schema:
          type: string
          minLength: 12
          maxLength: 12
      - name: cageCode
        in: query
        required: false
        description: Cage code.
        schema:
          type: string
          minLength: 3
          maxLength: 10
      - name: classificationType
        in: query
        required: false
        description: Classification type.
        schema:
          type: string
          enum:
          - Individual
          - Firm
          - Vessel
          - Special Entity Designation
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fair-market-rent:
    get:
      tags:
      - gov
      summary: HUD Fair Market Rents (FMR) for a US county or state
      description: 'HUD Fair Market Rents (FMR) for a US county or state — HUD’s annual gross-rent estimate (rent + utilities) by bedroom size (efficiency through 4-bedroom), the basis for Housing Choice Voucher payment standards and other HUD programs. Look up by 5-digit county FIPS (returns the county/metro rents, broken out per ZIP where HUD publishes Small Area FMRs) or by 2-letter state (returns every metro area + county). Optional year (defaults to latest). Source: HUD USER FMR API (US public domain).'
      operationId: gov_fair-market-rent
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [one FMR lookup with its areas[] (county / metro / ZIP small-areas), each carrying bedroom rents]; total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            scope:
                              type: string
                              enum:
                              - county
                              - state
                            fips:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            year:
                              type: string
                              nullable: true
                            countyName:
                              type: string
                              nullable: true
                            metroName:
                              type: string
                              nullable: true
                            areaName:
                              type: string
                              nullable: true
                            areas:
                              type: array
                              items:
                                type: object
                                properties:
                                  level:
                                    type: string
                                    enum:
                                    - county
                                    - metro
                                    - smallarea
                                    - state-county
                                  name:
                                    type: string
                                    nullable: true
                                  zipCode:
                                    type: string
                                    nullable: true
                                  fipsCode:
                                    type: string
                                    nullable: true
                                  rents:
                                    type: object
                                    properties:
                                      efficiency:
                                        type: number
                                        nullable: true
                                      oneBedroom:
                                        type: number
                                        nullable: true
                                      twoBedroom:
                                        type: number
                                        nullable: true
                                      threeBedroom:
                                        type: number
                                        nullable: true
                                      fourBedroom:
                                        type: number
                                        nullable: true
                                    required:
                                    - efficiency
                                    - oneBedroom
                                    - twoBedroom
                                    - threeBedroom
                                    - fourBedroom
                                    additionalProperties: false
                                  fmrPercentile:
                                    type: number
                                    nullable: true
                                required:
                                - level
                                - name
                                - zipCode
                                - fipsCode
                                - rents
                                - fmrPercentile
                                additionalProperties: false
                          required:
                          - scope
                          - fips
                          - state
                          - year
                          - countyName
                          - metroName
                          - areaName
                          - areas
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fair-market-rent
      x-2s-version: null
      x-2s-price:
        usd: 0.012
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.012000'
        protocols:
        - x402: {}
      parameters:
      - name: fips
        in: query
        required: false
        description: 5-digit US county FIPS, e.g. 06037 (Los Angeles County).
        schema:
          type: string
          pattern: ^\d{5}$
      - name: state
        in: query
        required: false
        description: 2-letter US state abbreviation, e.g. CA.
        schema:
          type: string
          pattern: ^[A-Za-z]{2}$
      - name: year
        in: query
        required: false
        description: FMR year, e.g. 2026. Omit for the latest.
        schema:
          type: string
          pattern: ^\d{4}$
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fcc-id:
    get:
      tags:
      - gov
      summary: Resolve an FCC ID (printed on US wireless/electronic
      description: 'Resolve an FCC ID (printed on US wireless/electronic devices) to the grantee — the manufacturer that holds the FCC equipment authorization. Pass fccId in any form (BCG-E3217A, BCGE3217A). Returns the grantee code, the product code, and the grantee company: name, city, state, country, and the date its grantee code was registered. Uses the FCC EAS Equipment Authorization Grantee Registrations open dataset, free and keyless — the "who made this device" lookup an agent reading a label off hardware cannot do natively. (Per-product RF detail — frequencies, equipment class — is not in the open dataset and is out of scope.)'
      operationId: gov_fcc-id
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      query:
                        type: object
                        properties:
                          fccId:
                            type: string
                        required:
                        - fccId
                        additionalProperties: false
                      found:
                        type: boolean
                      granteeCode:
                        type: string
                        nullable: true
                      productCode:
                        type: string
                        nullable: true
                      grantee:
                        type: object
                        properties:
                          name:
                            type: string
                            nullable: true
                          city:
                            type: string
                            nullable: true
                          state:
                            type: string
                            nullable: true
                          country:
                            type: string
                            nullable: true
                          zipCode:
                            type: string
                            nullable: true
                          dateReceived:
                            type: string
                            nullable: true
                        required:
                        - name
                        - city
                        - state
                        - country
                        - zipCode
                        - dateReceived
                        additionalProperties: false
                        nullable: true
                      source:
                        $ref: '#/components/schemas/Source'
                      note:
                        type: string
                    required:
                    - query
                    - found
                    - granteeCode
                    - productCode
                    - grantee
                    - source
                    - note
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fcc-id
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: legacy
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: fccId
        in: query
        required: true
        description: An FCC ID, e.g. BCG-E3217A or BCGE3217A.
        schema:
          type: string
          minLength: 3
          maxLength: 40
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fda-animalvet-events:
    get:
      tags:
      - gov
      summary: FDA animal and veterinary adverse event reports, newest first
      description: 'FDA animal and veterinary adverse event reports, newest first. All filters optional. Each record includes AER ID, dates, animal species/gender/breed/age/weight, reactions (VeDDRA-coded), drugs (brand + active ingredients + administration), primary reporter (Veterinarian/Owner/Other). Use cases: veterinary practice safety research, pet food adverse events, livestock drug surveillance. Backed by OpenFDA''s /animalandveterinary/event endpoint; public-domain US government records.'
      operationId: gov_fda-animalvet-events
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = FDA animal/veterinary adverse event reports, newest first; total = upstream match count; meta.query echoes the search.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            aerId:
                              type: string
                            originalReceiveDate:
                              type: string
                              nullable: true
                            onsetDate:
                              type: string
                              nullable: true
                            numberAffected:
                              type: integer
                              nullable: true
                            numberTreated:
                              type: integer
                              nullable: true
                            animal:
                              type: object
                              properties:
                                species:
                                  type: string
                                  nullable: true
                                gender:
                                  type: string
                                  nullable: true
                                breed:
                                  type: string
                                  nullable: true
                                ageValue:
                                  type: string
                                  nullable: true
                                ageUnit:
                                  type: string
                                  nullable: true
                                weightValue:
                                  type: string
                                  nullable: true
                                weightUnit:
                                  type: string
                                  nullable: true
                              required:
                              - species
                              - gender
                              - breed
                              - ageValue
                              - ageUnit
                              - weightValue
                              - weightUnit
                              additionalProperties: false
                            reactions:
                              type: array
                              items:
                                type: object
                                properties:
                                  term:
                                    type: string
                                  veddraCode:
                                    type: string
                                    nullable: true
                                required:
                                - term
                                - veddraCode
                                additionalProperties: false
                            drugs:
                              type: array
                              items:
                                type: object
                                properties:
                                  brandName:
                                    type: string
                                    nullable: true
                                  activeIngredients:
                                    type: array
                                    items:
                                      type: string
                                  administeredBy:
                                    type: string
                                    nullable: true
                                  route:
                                    type: string
                                    nullable: true
                                required:
                                - brandName
                                - activeIngredients
                                - administeredBy
                                - route
                                additionalProperties: false
                            primaryReporter:
                              type: string
                              nullable: true
                          required:
                          - aerId
                          - originalReceiveDate
                          - onsetDate
                          - numberAffected
                          - numberTreated
                          - animal
                          - reactions
                          - drugs
                          - primaryReporter
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              drug:
                                type: string
                                nullable: true
                              species:
                                type: string
                                nullable: true
                              reaction:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                            required:
                            - drug
                            - species
                            - reaction
                            - limit
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fda-animalvet-events
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: drug
        in: query
        required: false
        description: 'Drug name substring across brand + active ingredients. Examples: "Heartgard", "Bravecto", "Apoquel".'
        schema:
          type: string
          minLength: 2
          maxLength: 100
      - name: species
        in: query
        required: false
        description: 'Animal species. Examples: "Dog", "Cat", "Horse", "Cattle", "Chicken".'
        schema:
          type: string
          minLength: 2
          maxLength: 60
      - name: reaction
        in: query
        required: false
        description: 'Reaction (VeDDRA preferred term) substring. Examples: "Vomiting", "Lethargy", "Death".'
        schema:
          type: string
          minLength: 2
          maxLength: 100
      - name: limit
        in: query
        required: false
        description: Max events (1-100). Default 20.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fda-device-events:
    get:
      tags:
      - gov
      summary: FDA medical device adverse event reports (MAUDE), newest
      description: FDA medical device adverse event reports (MAUDE), newest first by date received. All filters optional. Each record includes report number, event type, dates received + of event, manufacturer, brand/generic device name, model + catalog numbers, listed device problems, patient outcomes, and primary narrative text. Backed by OpenFDA's /device/event endpoint; public-domain US government records.
      operationId: gov_fda-device-events
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = FDA MAUDE device adverse event reports; total = upstream match count; meta.query echoes the search.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            reportNumber:
                              type: string
                            eventType:
                              type: string
                              nullable: true
                            dateReceived:
                              type: string
                              nullable: true
                            dateOfEvent:
                              type: string
                              nullable: true
                            manufacturerName:
                              type: string
                              nullable: true
                            brandName:
                              type: string
                              nullable: true
                            genericName:
                              type: string
                              nullable: true
                            modelNumber:
                              type: string
                              nullable: true
                            catalogNumber:
                              type: string
                              nullable: true
                            deviceProblems:
                              type: array
                              items:
                                type: string
                            patientOutcome:
                              type: array
                              items:
                                type: string
                            eventDescription:
                              type: string
                              nullable: true
                          required:
                          - reportNumber
                          - eventType
                          - dateReceived
                          - dateOfEvent
                          - manufacturerName
                          - brandName
                          - genericName
                          - modelNumber
                          - catalogNumber
                          - deviceProblems
                          - patientOutcome
                          - eventDescription
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              device:
                                type: string
                                nullable: true
                              manufacturer:
                                type: string
                                nullable: true
                              problem:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                            required:
                            - device
                            - manufacturer
                            - problem
                            - limit
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fda-device-events
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: device
        in: query
        required: false
        description: 'Device-name substring across brand_name + generic_name. Examples: "pacemaker", "insulin pump", "DePuy hip".'
        schema:
          type: string
          minLength: 2
          maxLength: 100
      - name: manufacturer
        in: query
        required: false
        description: 'Manufacturer-name substring. Examples: "medtronic", "boston scientific", "abbott".'
        schema:
          type: string
          minLength: 2
          maxLength: 100
      - name: problem
        in: query
        required: false
        description: FDA device product code substring (advanced filter; most users want device or manufacturer).
        schema:
          type: string
          minLength: 2
          maxLength: 100
      - name: limit
        in: query
        required: false
        description: Max events (1-100). Default 20.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fda-drug-events:
    get:
      tags:
      - gov
      summary: Adverse drug event reports from FDA's Adverse Event
      description: Adverse drug event reports from FDA's Adverse Event Reporting System (FAERS) — 9M+ records since 1968 covering serious adverse events, hospitalizations, deaths, and disabilities. Search by drug name (brand/generic/substance, all OR-matched) and optionally filter by MedDRA reaction term. Returns report ID, received date, seriousness flags, patient demographics, MedDRA-coded reactions, implicated drugs (up to 5 per report), and reporting country. Backed by OpenFDA; data is public-domain US government records.
      operationId: gov_fda-drug-events
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = FDA FAERS adverse drug event reports; total = upstream match count; meta.query echoes the search.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            safetyReportId:
                              type: string
                            receivedDate:
                              type: string
                              nullable: true
                            serious:
                              type: boolean
                            hospitalization:
                              type: boolean
                            death:
                              type: boolean
                            disabling:
                              type: boolean
                            lifeThreatening:
                              type: boolean
                            patientSex:
                              type: string
                              nullable: true
                            patientAge:
                              type: string
                              nullable: true
                            reactions:
                              type: array
                              items:
                                type: string
                            drugs:
                              type: array
                              items:
                                type: object
                                properties:
                                  medicinalProduct:
                                    type: string
                                    nullable: true
                                  brandName:
                                    type: string
                                    nullable: true
                                  indication:
                                    type: string
                                    nullable: true
                                  dosageText:
                                    type: string
                                    nullable: true
                                required:
                                - medicinalProduct
                                - brandName
                                - indication
                                - dosageText
                                additionalProperties: false
                            occurCountry:
                              type: string
                              nullable: true
                          required:
                          - safetyReportId
                          - receivedDate
                          - serious
                          - hospitalization
                          - death
                          - disabling
                          - lifeThreatening
                          - patientSex
                          - patientAge
                          - reactions
                          - drugs
                          - occurCountry
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              drug:
                                type: string
                              reaction:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                            required:
                            - drug
                            - reaction
                            - limit
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fda-drug-events
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: drug
        in: query
        required: true
        description: 'Drug name (brand, generic, or substance). Examples: "tylenol", "metformin", "lisinopril". Case-insensitive.'
        schema:
          type: string
          minLength: 2
          maxLength: 100
      - name: reaction
        in: query
        required: false
        description: 'Optional MedDRA preferred-term reaction filter. Examples: "headache", "nausea", "anaphylaxis".'
        schema:
          type: string
          minLength: 2
          maxLength: 100
      - name: limit
        in: query
        required: false
        description: Max reports to return (1-100). Default 10.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fda-food-recalls:
    get:
      tags:
      - gov
      summary: FDA food recall enforcement reports, newest first by report
      description: FDA food recall enforcement reports, newest first by report date. All filters optional. Each record includes recall number, status (Ongoing/Completed/Terminated/Pending), classification (Class I/II/III), product description, reason for recall, initial-notification mechanism, voluntary-vs-mandated, recalling firm + city/state/country, distribution pattern, and recall + report dates. Backed by OpenFDA's /food/enforcement endpoint; public-domain US government records.
      operationId: gov_fda-food-recalls
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = FDA food recall enforcement reports, newest first; total = upstream match count; meta.query echoes the search.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            recallNumber:
                              type: string
                            status:
                              type: string
                              nullable: true
                            classification:
                              type: string
                              nullable: true
                            productType:
                              type: string
                              nullable: true
                            productDescription:
                              type: string
                              nullable: true
                            reasonForRecall:
                              type: string
                              nullable: true
                            initialNotification:
                              type: string
                              nullable: true
                            voluntaryMandated:
                              type: string
                              nullable: true
                            recallingFirm:
                              type: string
                              nullable: true
                            city:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            country:
                              type: string
                              nullable: true
                            distributionPattern:
                              type: string
                              nullable: true
                            recallInitiationDate:
                              type: string
                              nullable: true
                            reportDate:
                              type: string
                              nullable: true
                          required:
                          - recallNumber
                          - status
                          - classification
                          - productType
                          - productDescription
                          - reasonForRecall
                          - initialNotification
                          - voluntaryMandated
                          - recallingFirm
                          - city
                          - state
                          - country
                          - distributionPattern
                          - recallInitiationDate
                          - reportDate
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              product:
                                type: string
                                nullable: true
                              classification:
                                type: string
                                nullable: true
                              status:
                                type: string
                                nullable: true
                              state:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                            required:
                            - product
                            - classification
                            - status
                            - state
                            - limit
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fda-food-recalls
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: product
        in: query
        required: false
        description: 'Product-name substring match on the recall description. Examples: "spinach", "peanut butter", "infant formula".'
        schema:
          type: string
          minLength: 2
          maxLength: 100
      - name: classification
        in: query
        required: false
        description: Optional class filter. I = life-threatening (e.g., Listeria, undeclared major allergen), II = temporary/reversible health risk, III = unlikely to cause harm (e.g., minor labeling).
        schema:
          type: string
          enum:
          - I
          - II
          - III
      - name: status
        in: query
        required: false
        description: Optional status filter.
        schema:
          type: string
          enum:
          - Ongoing
          - Completed
          - Terminated
          - Pending
      - name: state
        in: query
        required: false
        description: Optional 2-letter US state of the recalling firm (e.g., "CA", "TX").
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
      - name: limit
        in: query
        required: false
        description: Max recalls (1-100). Default 20.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fda-recalls:
    get:
      tags:
      - gov
      summary: FDA drug recall enforcement reports, newest first
      description: FDA drug recall enforcement reports, newest first. All filters optional. Each record includes recall number, status (Ongoing/Completed/Terminated/Pending), classification (Class I/II/III), product description, reason for recall, initial-notification mechanism, voluntary-vs-mandated flag, recalling firm name + city/state/country, distribution pattern, and recall + report dates. Backed by OpenFDA's /drug/enforcement endpoint; data is public-domain US government records.
      operationId: gov_fda-recalls
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = FDA drug recall enforcement reports, newest first; total = upstream match count; meta.query echoes the search.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            recallNumber:
                              type: string
                            status:
                              type: string
                              nullable: true
                            classification:
                              type: string
                              nullable: true
                            productType:
                              type: string
                              nullable: true
                            productDescription:
                              type: string
                              nullable: true
                            reasonForRecall:
                              type: string
                              nullable: true
                            initialNotification:
                              type: string
                              nullable: true
                            voluntaryMandated:
                              type: string
                              nullable: true
                            recallingFirm:
                              type: string
                              nullable: true
                            city:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            country:
                              type: string
                              nullable: true
                            distributionPattern:
                              type: string
                              nullable: true
                            recallInitiationDate:
                              type: string
                              nullable: true
                            reportDate:
                              type: string
                              nullable: true
                          required:
                          - recallNumber
                          - status
                          - classification
                          - productType
                          - productDescription
                          - reasonForRecall
                          - initialNotification
                          - voluntaryMandated
                          - recallingFirm
                          - city
                          - state
                          - country
                          - distributionPattern
                          - recallInitiationDate
                          - reportDate
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              drug:
                                type: string
                                nullable: true
                              classification:
                                type: string
                                nullable: true
                              status:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                            required:
                            - drug
                            - classification
                            - status
                            - limit
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fda-recalls
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: drug
        in: query
        required: false
        description: 'Optional drug-name substring match on the recall product description. Examples: "sanitizer", "metformin", "valsartan".'
        schema:
          type: string
          minLength: 2
          maxLength: 100
      - name: classification
        in: query
        required: false
        description: Optional class filter. I = life-threatening, II = temporary/reversible health risk, III = unlikely to cause harm.
        schema:
          type: string
          enum:
          - I
          - II
          - III
      - name: status
        in: query
        required: false
        description: Optional status filter.
        schema:
          type: string
          enum:
          - Ongoing
          - Completed
          - Terminated
          - Pending
      - name: limit
        in: query
        required: false
        description: Max recalls to return (1-100). Default 20.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fec:
    get:
      tags:
      - gov
      summary: US federal campaign finance from the FEC (openFEC)
      description: 'US federal campaign finance from the FEC (openFEC). Two modes: pass name to search candidates (returns FEC candidate id, party, office, state, district, incumbent/challenger, status, and election cycles); or pass candidateId (e.g. P80000722) to get that candidate''s aggregate financial totals — total receipts, disbursements, cash on hand, and individual / PAC / party / self contributions in USD for the newest cycle, alongside identity. Free, public-domain (FEC). Search by name first, then pass a returned candidateId back in for the money. For donor/spend diligence, political research, and disclosure lookups.'
      operationId: gov_fec
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = candidates (finance populated only in candidateId mode); total = match count.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            candidateId:
                              type: string
                              nullable: true
                            name:
                              type: string
                              nullable: true
                            party:
                              type: string
                              nullable: true
                            office:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            district:
                              type: string
                              nullable: true
                            incumbentChallenge:
                              type: string
                              nullable: true
                            status:
                              type: string
                              nullable: true
                            cycles:
                              type: array
                              items:
                                type: number
                            electionYears:
                              type: array
                              items:
                                type: number
                            finance:
                              type: object
                              properties:
                                cycle:
                                  type: number
                                  nullable: true
                                coverageEndDate:
                                  type: string
                                  nullable: true
                                receiptsUSD:
                                  type: number
                                  nullable: true
                                disbursementsUSD:
                                  type: number
                                  nullable: true
                                cashOnHandUSD:
                                  type: number
                                  nullable: true
                                individualContributionsUSD:
                                  type: number
                                  nullable: true
                                pacContributionsUSD:
                                  type: number
                                  nullable: true
                                partyContributionsUSD:
                                  type: number
                                  nullable: true
                                candidateContributionsUSD:
                                  type: number
                                  nullable: true
                              required:
                              - cycle
                              - coverageEndDate
                              - receiptsUSD
                              - disbursementsUSD
                              - cashOnHandUSD
                              - individualContributionsUSD
                              - pacContributionsUSD
                              - partyContributionsUSD
                              - candidateContributionsUSD
                              additionalProperties: false
                              nullable: true
                          required:
                          - candidateId
                          - name
                          - party
                          - office
                          - state
                          - district
                          - incumbentChallenge
                          - status
                          - cycles
                          - electionYears
                          - finance
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fec
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: name
        in: query
        required: false
        description: Name to search for.
        schema:
          type: string
          minLength: 1
          maxLength: 100
      - name: candidateId
        in: query
        required: false
        description: Candidate ID.
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{1,20}$
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fec-candidate:
    get:
      tags:
      - gov
      summary: Search US federal political candidates via the OpenFEC API
      description: Search US federal political candidates via the OpenFEC API. Filter by free-text q (name match), candidate ID (e.g. H0VA01076), state, district, party (DEM, REP, IND, LIB, GRE, etc.), office (P=President | S=Senate | H=House), election cycle (even years), election year, and hasRaised (only candidates with reported receipts). Returns FEC candidate ID, name, party, office, state/district, incumbency status, active-through cycle, first/last file dates, cycles, principal committee linkage. Use the candidate ID returned here to fetch their committees with /api/gov/fec-committee.
      operationId: gov_fec-candidate
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = FEC candidate records; total = upstream match count (OpenFEC pagination.count); page = pagination block.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            candidateId:
                              type: string
                              nullable: true
                              description: FEC candidate ID, e.g. H0VA01076.
                            name:
                              type: string
                              nullable: true
                            party:
                              type: string
                              nullable: true
                              description: 3-4 letter party code (DEM, REP, ...).
                            partyFull:
                              type: string
                              nullable: true
                            office:
                              type: string
                              nullable: true
                              description: P=President, S=Senate, H=House.
                            officeFull:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            district:
                              type: string
                              nullable: true
                              description: 2-digit district string; null for President/Senate.
                            districtNumber:
                              type: number
                              nullable: true
                            incumbentChallenge:
                              type: string
                              nullable: true
                              description: I=Incumbent, C=Challenger, O=Open seat.
                            incumbentChallengeFull:
                              type: string
                              nullable: true
                            activeThrough:
                              type: number
                              nullable: true
                              description: Last election cycle the candidate is active through.
                            lastF2Date:
                              type: string
                              nullable: true
                            firstFileDate:
                              type: string
                              nullable: true
                            lastFileDate:
                              type: string
                              nullable: true
                            hasRaisedFunds:
                              type: boolean
                            cycles:
                              type: array
                              items:
                                type: number
                            electionYears:
                              type: array
                              items:
                                type: number
                            principalCommittees:
                              type: array
                              items:
                                type: object
                                additionalProperties: {}
                              description: Upstream pass-through principal-committee objects.
                          required:
                          - candidateId
                          - name
                          - party
                          - partyFull
                          - office
                          - officeFull
                          - state
                          - district
                          - districtNumber
                          - incumbentChallenge
                          - incumbentChallengeFull
                          - activeThrough
                          - lastF2Date
                          - firstFileDate
                          - lastFileDate
                          - hasRaisedFunds
                          - cycles
                          - electionYears
                          - principalCommittees
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      page:
                        type: object
                        properties:
                          number:
                            type: integer
                          size:
                            type: integer
                          pages:
                            type: integer
                            nullable: true
                        required:
                        - number
                        - size
                        - pages
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fec-candidate
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: q
        in: query
        required: false
        description: Free-text search query.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: candidateId
        in: query
        required: false
        description: Candidate ID.
        schema:
          type: string
          pattern: ^[A-Z]\d[A-Z0-9]{7}$
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
      - name: district
        in: query
        required: false
        description: District.
        schema:
          type: string
          pattern: ^\d{2}$
      - name: party
        in: query
        required: false
        description: Party.
        schema:
          type: string
          pattern: ^[A-Za-z]{3,4}$
      - name: office
        in: query
        required: false
        description: Office.
        schema:
          type: string
          enum:
          - P
          - S
          - H
      - name: cycle
        in: query
        required: false
        description: Two-year US election cycle, given as the even-numbered end year (e.g. 2024).
        schema:
          type: integer
          minimum: 1980
          maximum: 2100
      - name: electionYear
        in: query
        required: false
        description: Election year.
        schema:
          type: integer
          minimum: 1980
          maximum: 2100
      - name: hasRaised
        in: query
        required: false
        description: Has raised.
        schema:
          type: boolean
      - name: perPage
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: page
        in: query
        required: false
        description: Page number (1-based) for paginated results.
        schema:
          type: integer
          minimum: 1
          default: 1
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fec-committee:
    get:
      tags:
      - gov
      summary: Search US federal political committees (PACs, super PACs
      description: Search US federal political committees (PACs, super PACs, party committees, candidate principal committees, leadership PACs, etc.) via the OpenFEC API. Filter by q (name match), committee ID, candidate ID (returns committees linked to that candidate), committee type (P=Presidential | S=Senate | H=House | X=Independent expenditure-only | Y=Party | Z=National Party non-federal), designation (A=Authorized | J=Joint fundraising | P=Principal | U=Unauthorized | B=Lobbyist/Registrant PAC), state, party, cycle, organization type (C=Corporation | L=Labor | M=Membership | T=Trade | V=Cooperative | W=Corp without stock). Returns FEC committee ID, name, type/designation/organization labels, state, party, treasurer, linked candidate IDs, cycles, affiliated-committee names, first/last file dates.
      operationId: gov_fec-committee
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = FEC committee records; total = upstream match count (OpenFEC pagination.count); page = pagination block.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            committeeId:
                              type: string
                              nullable: true
                              description: FEC committee ID, e.g. C00401224.
                            name:
                              type: string
                              nullable: true
                            committeeType:
                              type: string
                              nullable: true
                              description: Committee type code (P/S/H/X/Y/Z/…).
                            committeeTypeFull:
                              type: string
                              nullable: true
                            designation:
                              type: string
                              nullable: true
                              description: Designation code (A/J/P/U/B).
                            designationFull:
                              type: string
                              nullable: true
                            organizationType:
                              type: string
                              nullable: true
                              description: Organization type code (C/L/M/T/V/W).
                            organizationTypeFull:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            party:
                              type: string
                              nullable: true
                            partyFull:
                              type: string
                              nullable: true
                            treasurerName:
                              type: string
                              nullable: true
                            candidateIds:
                              type: array
                              items:
                                type: string
                              description: Candidate IDs linked to this committee.
                            cycles:
                              type: array
                              items:
                                type: number
                              description: Election cycles the committee has been active in.
                            affiliatedCommitteeName:
                              type: string
                              nullable: true
                            firstFileDate:
                              type: string
                              nullable: true
                              description: YYYY-MM-DD.
                            lastFileDate:
                              type: string
                              nullable: true
                          required:
                          - committeeId
                          - name
                          - committeeType
                          - committeeTypeFull
                          - designation
                          - designationFull
                          - organizationType
                          - organizationTypeFull
                          - state
                          - party
                          - partyFull
                          - treasurerName
                          - candidateIds
                          - cycles
                          - affiliatedCommitteeName
                          - firstFileDate
                          - lastFileDate
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      page:
                        type: object
                        properties:
                          number:
                            type: integer
                          size:
                            type: integer
                          pages:
                            type: integer
                            nullable: true
                        required:
                        - number
                        - size
                        - pages
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fec-committee
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: q
        in: query
        required: false
        description: Free-text search query.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: committeeId
        in: query
        required: false
        description: Committee ID.
        schema:
          type: string
          pattern: ^C\d{8}$
      - name: candidateId
        in: query
        required: false
        description: Candidate ID.
        schema:
          type: string
          pattern: ^[A-Z]\d[A-Z0-9]{7}$
      - name: committeeType
        in: query
        required: false
        description: Committee type.
        schema:
          type: string
          enum:
          - P
          - S
          - H
          - X
          - Y
          - Z
          - N
          - I
          - O
          - Q
          - U
          - V
          - W
          - D
          - E
      - name: designation
        in: query
        required: false
        description: Designation.
        schema:
          type: string
          enum:
          - A
          - J
          - P
          - U
          - B
          - D
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
      - name: party
        in: query
        required: false
        description: Party.
        schema:
          type: string
          pattern: ^[A-Za-z]{3,4}$
      - name: cycle
        in: query
        required: false
        description: Two-year US election cycle, given as the even-numbered end year (e.g. 2024).
        schema:
          type: integer
          minimum: 1980
          maximum: 2100
      - name: organizationType
        in: query
        required: false
        description: Organization type.
        schema:
          type: string
          enum:
          - C
          - L
          - M
          - T
          - V
          - W
      - name: perPage
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: page
        in: query
        required: false
        description: Page number (1-based) for paginated results.
        schema:
          type: integer
          minimum: 1
          default: 1
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fec-contributions:
    get:
      tags:
      - gov
      summary: Search FEC Schedule A - every itemized contribution to a
      description: 'Search FEC Schedule A — every itemized contribution to a federal political committee (>264M rows across all cycles). Filter by recipient committeeId or candidateId, contributor name / city / state / zip / employer / occupation, amount range, cycle (twoYearTransactionPeriod e.g. 2024), date range, isIndividual (true = individuals only; false = committee-to-committee). Sort by contribution date or amount, asc/desc. Requires at least one scope (committeeId, candidateId, twoYearTransactionPeriod cycle, or a date range) — an unscoped query scans every cycle and times out. The investigative-journalism + political-research goldmine: who gives, how much, when, working where, doing what. Each row carries the contribution receipt date, amount, contributor aggregate YTD, receipt type, memo, entity type, and link to the underlying PDF filing.'
      operationId: gov_fec-contributions
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = FEC Schedule A itemized contributions; total = upstream match count (OpenFEC pagination.count, null on deep keyset pages); page = pagination block.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            transactionId:
                              type: string
                              nullable: true
                            committeeId:
                              type: string
                              nullable: true
                              description: Recipient committee.
                            committeeName:
                              type: string
                              nullable: true
                            candidateId:
                              type: string
                              nullable: true
                            contributorName:
                              type: string
                              nullable: true
                            contributorFirstName:
                              type: string
                              nullable: true
                            contributorLastName:
                              type: string
                              nullable: true
                            contributorEmployer:
                              type: string
                              nullable: true
                            contributorOccupation:
                              type: string
                              nullable: true
                            contributorCity:
                              type: string
                              nullable: true
                            contributorState:
                              type: string
                              nullable: true
                            contributorZip:
                              type: string
                              nullable: true
                            receiptType:
                              type: string
                              nullable: true
                              description: FEC receipt type code, e.g. 15.
                            receiptTypeFull:
                              type: string
                              nullable: true
                            contributionReceiptDate:
                              type: string
                              nullable: true
                              description: YYYY-MM-DD.
                            contributionReceiptAmount:
                              type: number
                              nullable: true
                              description: USD.
                            contributorAggregateYtd:
                              type: number
                              nullable: true
                              description: Contributor year-to-date aggregate to this committee (USD).
                            memoText:
                              type: string
                              nullable: true
                            isIndividual:
                              type: boolean
                              nullable: true
                            entityType:
                              type: string
                              nullable: true
                              description: E.g. IND, PAC, ORG.
                            entityTypeDesc:
                              type: string
                              nullable: true
                            twoYearTransactionPeriod:
                              type: number
                              nullable: true
                              description: Even-year cycle.
                            reportYear:
                              type: number
                              nullable: true
                            reportType:
                              type: string
                              nullable: true
                            pdfUrl:
                              type: string
                              nullable: true
                              description: Link to the underlying PDF filing.
                          required:
                          - transactionId
                          - committeeId
                          - committeeName
                          - candidateId
                          - contributorName
                          - contributorFirstName
                          - contributorLastName
                          - contributorEmployer
                          - contributorOccupation
                          - contributorCity
                          - contributorState
                          - contributorZip
                          - receiptType
                          - receiptTypeFull
                          - contributionReceiptDate
                          - contributionReceiptAmount
                          - contributorAggregateYtd
                          - memoText
                          - isIndividual
                          - entityType
                          - entityTypeDesc
                          - twoYearTransactionPeriod
                          - reportYear
                          - reportType
                          - pdfUrl
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      page:
                        type: object
                        properties:
                          number:
                            type: integer
                          size:
                            type: integer
                          pages:
                            type: integer
                            nullable: true
                        required:
                        - number
                        - size
                        - pages
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fec-contributions
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: committeeId
        in: query
        required: false
        description: Committee ID.
        schema:
          type: string
          pattern: ^C\d{8}$
      - name: candidateId
        in: query
        required: false
        description: Candidate ID.
        schema:
          type: string
          pattern: ^[A-Z]\d[A-Z0-9]{7}$
      - name: contributorName
        in: query
        required: false
        description: Contributor name.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: contributorCity
        in: query
        required: false
        description: Contributor city.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: contributorState
        in: query
        required: false
        description: Contributor state.
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
      - name: contributorZip
        in: query
        required: false
        description: Contributor ZIP.
        schema:
          type: string
          pattern: ^\d{5}(\d{4})?$
      - name: contributorEmployer
        in: query
        required: false
        description: Contributor employer.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: contributorOccupation
        in: query
        required: false
        description: Contributor occupation.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: minAmount
        in: query
        required: false
        description: Minimum amount to include (USD).
        schema:
          type: number
          minimum: 0
      - name: maxAmount
        in: query
        required: false
        description: Maximum amount to include (USD).
        schema:
          type: number
          minimum: 0
      - name: twoYearTransactionPeriod
        in: query
        required: false
        description: Two year transaction period.
        schema:
          type: integer
          minimum: 1980
          maximum: 2100
      - name: minDate
        in: query
        required: false
        description: Min date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: maxDate
        in: query
        required: false
        description: Max date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: isIndividual
        in: query
        required: false
        description: Is individual.
        schema:
          type: boolean
      - name: perPage
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: page
        in: query
        required: false
        description: Page number (1-based) for paginated results.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: sortField
        in: query
        required: false
        description: Sort field.
        schema:
          type: string
          enum:
          - contribution_receipt_date
          - contribution_receipt_amount
      - name: sortDirection
        in: query
        required: false
        description: Sort direction.
        schema:
          type: string
          enum:
          - asc
          - desc
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fec-expenditures:
    get:
      tags:
      - gov
      summary: Search FEC Schedule B - every itemized disbursement (spend
      description: 'Search FEC Schedule B — every itemized disbursement (spend, vendor payment, operating expenditure, contribution out, transfer) made by a federal political committee (>157M rows). Filter by committeeId, recipient name / city / state, disbursement purpose category (Administrative / Fundraising / Media / Polling / Salary / Travel / Operating / Contribution / Loan / etc.), description text, amount range, cycle, date range. Sort by date or amount. Every row carries: who got paid, when, how much, for what, with link to underlying PDF. The natural pair with /api/gov/fec-contributions for following the money on both sides of any federal committee.'
      operationId: gov_fec-expenditures
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = FEC Schedule B itemized disbursements; total = upstream match count (OpenFEC pagination.count, null when upstream omits it); page = pagination block.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            transactionId:
                              type: string
                              nullable: true
                            committeeId:
                              type: string
                              nullable: true
                              description: Spending committee.
                            committeeName:
                              type: string
                              nullable: true
                            recipientName:
                              type: string
                              nullable: true
                            recipientCity:
                              type: string
                              nullable: true
                            recipientState:
                              type: string
                              nullable: true
                            recipientZip:
                              type: string
                              nullable: true
                            disbursementDate:
                              type: string
                              nullable: true
                              description: YYYY-MM-DD.
                            disbursementAmount:
                              type: number
                              nullable: true
                              description: USD.
                            disbursementDescription:
                              type: string
                              nullable: true
                            disbursementPurposeCategory:
                              type: string
                              nullable: true
                              description: E.g. ADMINISTRATIVE, FUNDRAISING, MEDIA.
                            disbursementTypeDescription:
                              type: string
                              nullable: true
                            memoText:
                              type: string
                              nullable: true
                            twoYearTransactionPeriod:
                              type: number
                              nullable: true
                              description: Even-year cycle.
                            reportYear:
                              type: number
                              nullable: true
                            reportType:
                              type: string
                              nullable: true
                            pdfUrl:
                              type: string
                              nullable: true
                              description: Link to the underlying PDF filing.
                          required:
                          - transactionId
                          - committeeId
                          - committeeName
                          - recipientName
                          - recipientCity
                          - recipientState
                          - recipientZip
                          - disbursementDate
                          - disbursementAmount
                          - disbursementDescription
                          - disbursementPurposeCategory
                          - disbursementTypeDescription
                          - memoText
                          - twoYearTransactionPeriod
                          - reportYear
                          - reportType
                          - pdfUrl
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      page:
                        type: object
                        properties:
                          number:
                            type: integer
                          size:
                            type: integer
                          pages:
                            type: integer
                            nullable: true
                        required:
                        - number
                        - size
                        - pages
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fec-expenditures
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: committeeId
        in: query
        required: false
        description: Committee ID.
        schema:
          type: string
          pattern: ^C\d{8}$
      - name: recipientName
        in: query
        required: false
        description: Recipient name.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: recipientCity
        in: query
        required: false
        description: Recipient city.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: recipientState
        in: query
        required: false
        description: Recipient state.
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
      - name: disbursementPurposeCategory
        in: query
        required: false
        description: Disbursement purpose category.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: disbursementDescription
        in: query
        required: false
        description: Disbursement description.
        schema:
          type: string
          minLength: 1
          maxLength: 160
      - name: minAmount
        in: query
        required: false
        description: Minimum amount to include (USD).
        schema:
          type: number
          minimum: 0
      - name: maxAmount
        in: query
        required: false
        description: Maximum amount to include (USD).
        schema:
          type: number
          minimum: 0
      - name: twoYearTransactionPeriod
        in: query
        required: false
        description: Two year transaction period.
        schema:
          type: integer
          minimum: 1980
          maximum: 2100
      - name: minDate
        in: query
        required: false
        description: Min date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: maxDate
        in: query
        required: false
        description: Max date.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: perPage
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: page
        in: query
        required: false
        description: Page number (1-based) for paginated results.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: sortField
        in: query
        required: false
        description: Sort field.
        schema:
          type: string
          enum:
          - disbursement_date
          - disbursement_amount
      - name: sortDirection
        in: query
        required: false
        description: Sort direction.
        schema:
          type: string
          enum:
          - asc
          - desc
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/fec-totals:
    get:
      tags:
      - gov
      summary: Aggregate financial summaries (receipts, disbursements
      description: Aggregate financial summaries (receipts, disbursements, cash-on-hand, debt, transfers, refunds, contributions by source, etc.) per cycle for federal candidates (scope=candidates) or committees (scope=committees). Filter by candidateId / committeeId, cycle, office (P/S/H), party, state, district. For candidates, electionFull=true rolls all cycles of a single election into one row (e.g. a presidential cycle spans 4 years). Use this for top-line "how much did they raise/spend" answers without paging through millions of itemized transactions.
      operationId: gov_fec-totals
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = per-cycle FEC financial summary rows; total = upstream match count (OpenFEC pagination.count); page = pagination block; meta.scope echoes candidates/committees.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties: {}
                          additionalProperties: true
                          description: Raw OpenFEC totals row, passed through with OpenFEC snake_case column names (receipts, disbursements, cash_on_hand_end_period, …). Column set varies by scope (candidates vs committees) and committee type.
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      page:
                        type: object
                        properties:
                          number:
                            type: integer
                          size:
                            type: integer
                          pages:
                            type: integer
                            nullable: true
                        required:
                        - number
                        - size
                        - pages
                        additionalProperties: false
                      meta:
                        type: object
                        properties:
                          scope:
                            type: string
                            enum:
                            - candidates
                            - committees
                        required:
                        - scope
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.fec-totals
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: scope
        in: query
        required: true
        description: Scope.
        schema:
          type: string
          enum:
          - candidates
          - committees
      - name: candidateId
        in: query
        required: false
        description: Candidate ID.
        schema:
          type: string
          pattern: ^[A-Z]\d[A-Z0-9]{7}$
      - name: committeeId
        in: query
        required: false
        description: Committee ID.
        schema:
          type: string
          pattern: ^C\d{8}$
      - name: cycle
        in: query
        required: false
        description: Two-year US election cycle, given as the even-numbered end year (e.g. 2024).
        schema:
          type: integer
          minimum: 1980
          maximum: 2100
      - name: office
        in: query
        required: false
        description: Office.
        schema:
          type: string
          enum:
          - P
          - S
          - H
      - name: party
        in: query
        required: false
        description: Party.
        schema:
          type: string
          pattern: ^[A-Za-z]{3,4}$
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
      - name: district
        in: query
        required: false
        description: District.
        schema:
          type: string
          pattern: ^\d{2}$
      - name: electionFull
        in: query
        required: false
        description: Election full.
        schema:
          type: boolean
      - name: perPage
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: page
        in: query
        required: false
        description: Page number (1-based) for paginated results.
        schema:
          type: integer
          minimum: 1
          default: 1
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/federal-register-recent:
    get:
      tags:
      - gov
      summary: Newest Federal Register documents by publication date
      description: Newest Federal Register documents by publication date — chronological feed for compliance change-detection. Filter by document type (RULE / PRORULE / NOTICE / PRESDOCU), agency name, and publication date range. Each record includes document number, type, title, abstract, publication date, effective date, agencies, citations (CFR/USC), HTML + PDF URLs. Defaults to last 7 days of final rules. Free public-domain data from federalregister.gov.
      operationId: gov_federal-register-recent
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = recent Federal Register documents in chronological order; total = upstream match count; meta.hasNext signals more pages, meta.query echoes the search.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            documentNumber:
                              type: string
                            type:
                              type: string
                              nullable: true
                            title:
                              type: string
                              nullable: true
                            abstract:
                              type: string
                              nullable: true
                            publicationDate:
                              type: string
                              nullable: true
                            effectiveOn:
                              type: string
                              nullable: true
                            agencies:
                              type: array
                              items:
                                type: string
                            citations:
                              type: array
                              items:
                                type: string
                            htmlUrl:
                              type: string
                              format: uri
                              nullable: true
                            pdfUrl:
                              type: string
                              format: uri
                              nullable: true
                          required:
                          - documentNumber
                          - type
                          - title
                          - abstract
                          - publicationDate
                          - effectiveOn
                          - agencies
                          - citations
                          - htmlUrl
                          - pdfUrl
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              type:
                                type: string
                              agency:
                                type: string
                                nullable: true
                              since:
                                type: string
                              until:
                                type: string
                              limit:
                                type: integer
                              page:
                                type: integer
                            required:
                            - type
                            - agency
                            - since
                            - until
                            - limit
                            - page
                            additionalProperties: false
                          hasNext:
                            type: boolean
                        required:
                        - query
                        - hasNext
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.federal-register-recent
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: type
        in: query
        required: false
        description: 'Document type: RULE = final rules, PRORULE = proposed rules, NOTICE = notices, PRESDOCU = presidential docs.'
        schema:
          type: string
          enum:
          - RULE
          - PRORULE
          - NOTICE
          - PRESDOCU
          default: RULE
      - name: agency
        in: query
        required: false
        description: Agency slug or name (e.g., "environmental-protection-agency", "federal-trade-commission").
        schema:
          type: string
          minLength: 2
          maxLength: 80
      - name: since
        in: query
        required: false
        description: Earliest publication date (YYYY-MM-DD). Default = 7 days ago.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: until
        in: query
        required: false
        description: Latest publication date (YYYY-MM-DD). Default = today.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: limit
        in: query
        required: false
        description: Max results (1-100). Default 25.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: page
        in: query
        required: false
        description: Page number (1-based). Default 1.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 1
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/foreign-agents:
    get:
      tags:
      - gov
      summary: Search currently-active FARA (Foreign Agents Registration
      description: Search currently-active FARA (Foreign Agents Registration Act) registrants by name. Pass a company or person name; returns whether the entity is a registered foreign agent (isRegisteredForeignAgent), a single KYB-safe bestMatch (null below medium confidence — no false positives), and scored candidate matches with registration number, registration date, city/state, and a 0-1 match score + confidence (high/medium/low). FARA registration is a US disclosure status (an agent acting for a foreign principal), not wrongdoing. Authoritative DOJ FARA eFile data, free and keyless — the foreign-agent check a compliance or procurement agent cannot derive from training.
      operationId: gov_foreign-agents
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      query:
                        type: object
                        properties:
                          name:
                            type: string
                        required:
                        - name
                        additionalProperties: false
                      isRegisteredForeignAgent:
                        type: boolean
                      bestMatch:
                        type: object
                        properties:
                          registrationNumber:
                            type: number
                            nullable: true
                          name:
                            type: string
                          registrationDate:
                            type: string
                            nullable: true
                          city:
                            type: string
                            nullable: true
                          state:
                            type: string
                            nullable: true
                          score:
                            type: number
                          confidence:
                            type: string
                            enum:
                            - high
                            - medium
                            - low
                        required:
                        - registrationNumber
                        - name
                        - registrationDate
                        - city
                        - state
                        - score
                        - confidence
                        additionalProperties: false
                        nullable: true
                      matchCount:
                        type: number
                      matches:
                        type: array
                        items:
                          type: object
                          properties:
                            registrationNumber:
                              type: number
                              nullable: true
                            name:
                              type: string
                            registrationDate:
                              type: string
                              nullable: true
                            city:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            score:
                              type: number
                            confidence:
                              type: string
                              enum:
                              - high
                              - medium
                              - low
                          required:
                          - registrationNumber
                          - name
                          - registrationDate
                          - city
                          - state
                          - score
                          - confidence
                          additionalProperties: false
                      source:
                        $ref: '#/components/schemas/Source'
                      note:
                        type: string
                    required:
                    - query
                    - isRegisteredForeignAgent
                    - bestMatch
                    - matchCount
                    - matches
                    - source
                    - note
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.foreign-agents
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: legacy
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: name
        in: query
        required: true
        description: Company or person name to screen against FARA registrants.
        schema:
          type: string
          minLength: 2
          maxLength: 200
      - name: limit
        in: query
        required: false
        description: Max candidate matches (default 5).
        schema:
          type: integer
          minimum: 1
          maximum: 20
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/hazard-mitigation:
    get:
      tags:
      - gov
      summary: FEMA Hazard Mitigation Assistance (HMA) funded projects
      description: 'FEMA Hazard Mitigation Assistance (HMA) funded projects — the pre- and post-disaster mitigation grants FEMA has actually obligated (HMGP, BRIC/PDM, FMA). Filter by state (2-letter), disasterNumber, programFy (program fiscal year), and/or programArea; at least one filter is required. Returns the total matching project count plus projects (identifier, program area, project type, status, recipient/subrecipient, county, disaster number, project amount and federal share obligated in USD, cost-share %, benefit-cost ratio, number of properties, approval/close dates), largest federal share first. Free, public-domain (OpenFEMA). Distinct from gov.public-assistance (post-disaster recovery grants) and gov.nfip-claims (flood losses paid) — this is mitigation funding: who got money to reduce future risk, where, and at what benefit-cost ratio.'
      operationId: gov_hazard-mitigation
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [one HMA result object]; total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            query:
                              type: object
                              properties:
                                state:
                                  type: string
                                  nullable: true
                                disasterNumber:
                                  type: number
                                  nullable: true
                                programFy:
                                  type: number
                                  nullable: true
                                programArea:
                                  type: string
                                  nullable: true
                                limit:
                                  type: number
                              required:
                              - state
                              - disasterNumber
                              - programFy
                              - programArea
                              - limit
                              additionalProperties: false
                            totalProjects:
                              type: number
                              nullable: true
                            returned:
                              type: number
                            returnedSummary:
                              type: object
                              properties:
                                totalFederalShareUSD:
                                  type: number
                                averageBenefitCostRatio:
                                  type: number
                                  nullable: true
                              required:
                              - totalFederalShareUSD
                              - averageBenefitCostRatio
                              additionalProperties: false
                            projects:
                              type: array
                              items:
                                type: object
                                properties:
                                  projectIdentifier:
                                    type: string
                                    nullable: true
                                  programArea:
                                    type: string
                                    nullable: true
                                  programFy:
                                    type: number
                                    nullable: true
                                  projectType:
                                    type: string
                                    nullable: true
                                  status:
                                    type: string
                                    nullable: true
                                  state:
                                    type: string
                                    nullable: true
                                  county:
                                    type: string
                                    nullable: true
                                  countyCode:
                                    type: string
                                    nullable: true
                                  disasterNumber:
                                    type: number
                                    nullable: true
                                  recipient:
                                    type: string
                                    nullable: true
                                  subrecipient:
                                    type: string
                                    nullable: true
                                  projectAmountUSD:
                                    type: number
                                    nullable: true
                                  federalShareObligatedUSD:
                                    type: number
                                    nullable: true
                                  costSharePercentage:
                                    type: number
                                    nullable: true
                                  benefitCostRatio:
                                    type: number
                                    nullable: true
                                  numberOfProperties:
                                    type: number
                                    nullable: true
                                  dateApproved:
                                    type: string
                                    nullable: true
                                  dateClosed:
                                    type: string
                                    nullable: true
                                required:
                                - projectIdentifier
                                - programArea
                                - programFy
                                - projectType
                                - status
                                - state
                                - county
                                - countyCode
                                - disasterNumber
                                - recipient
                                - subrecipient
                                - projectAmountUSD
                                - federalShareObligatedUSD
                                - costSharePercentage
                                - benefitCostRatio
                                - numberOfProperties
                                - dateApproved
                                - dateClosed
                                additionalProperties: false
                            source:
                              $ref: '#/components/schemas/Source'
                            note:
                              type: string
                          required:
                          - query
                          - totalProjects
                          - returned
                          - returnedSummary
                          - projects
                          - source
                          - note
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.hazard-mitigation
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: state
        in: query
        required: false
        description: 2-letter US state/territory code.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: disasterNumber
        in: query
        required: false
        description: Disaster number.
        schema:
          type: integer
          minimum: 1
          maximum: 100000
      - name: programFy
        in: query
        required: false
        description: Program fy.
        schema:
          type: integer
          minimum: 1989
          maximum: 2100
      - name: programArea
        in: query
        required: false
        description: Program area.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/house-votes:
    get:
      tags:
      - gov
      summary: US House of Representatives roll-call votes, newest first
      description: 'US House of Representatives roll-call votes, newest first by action date. Each record includes year + roll number, congress/session, vote question + type + result, action date/time, bill reference (legis_num), description, grand totals (yea/nay/present/not-voting), AND per-party breakdown (Republican/Democratic/Independent yea/nay/present/not-voting counts). Filters (all optional, AND-combined): year, congress, result substring, bill substring (legis_num ILIKE), since/until (action_date), limit + offset. Locally aggregated from clerk.house.gov XML feeds (refreshed daily by cron). Public-domain US government records.'
      operationId: gov_house-votes
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = US House roll-call votes with per-party totals; total = matching rows; meta carries the query echo + nextOffset/previousOffset.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            year:
                              type: integer
                            roll:
                              type: integer
                            congress:
                              type: integer
                              nullable: true
                            session:
                              type: string
                              nullable: true
                            voteQuestion:
                              type: string
                              nullable: true
                            voteType:
                              type: string
                              nullable: true
                            voteResult:
                              type: string
                              nullable: true
                            actionDate:
                              type: string
                              nullable: true
                            actionTime:
                              type: string
                              nullable: true
                            legisNum:
                              type: string
                              nullable: true
                            voteDesc:
                              type: string
                              nullable: true
                            totals:
                              type: object
                              properties:
                                yea:
                                  type: integer
                                nay:
                                  type: integer
                                present:
                                  type: integer
                                notVoting:
                                  type: integer
                              required:
                              - yea
                              - nay
                              - present
                              - notVoting
                              additionalProperties: false
                            totalsByParty:
                              type: object
                              additionalProperties:
                                type: object
                                properties:
                                  yea:
                                    type: integer
                                  nay:
                                    type: integer
                                  present:
                                    type: integer
                                  not_voting:
                                    type: integer
                                required:
                                - yea
                                - nay
                                - present
                                - not_voting
                                additionalProperties: false
                            sourceXmlUrl:
                              type: string
                              format: uri
                          required:
                          - year
                          - roll
                          - congress
                          - session
                          - voteQuestion
                          - voteType
                          - voteResult
                          - actionDate
                          - actionTime
                          - legisNum
                          - voteDesc
                          - totals
                          - totalsByParty
                          - sourceXmlUrl
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              year:
                                type: number
                                nullable: true
                              congress:
                                type: number
                                nullable: true
                              result:
                                type: string
                                nullable: true
                              bill:
                                type: string
                                nullable: true
                              since:
                                type: string
                                nullable: true
                              until:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                              offset:
                                type: integer
                            required:
                            - year
                            - congress
                            - result
                            - bill
                            - since
                            - until
                            - limit
                            - offset
                            additionalProperties: false
                          nextOffset:
                            type: integer
                            nullable: true
                          previousOffset:
                            type: integer
                            nullable: true
                        required:
                        - query
                        - nextOffset
                        - previousOffset
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.house-votes
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: year
        in: query
        required: false
        description: 'Filter by year. Example: 2025.'
        schema:
          type: integer
          minimum: 1990
          maximum: 2099
      - name: congress
        in: query
        required: false
        description: Filter by Congress number. The 119th Congress = 2025-2026.
        schema:
          type: integer
          minimum: 100
          maximum: 200
      - name: result
        in: query
        required: false
        description: 'Filter by vote result (case-insensitive substring). Examples: "Passed", "Failed", "Agreed".'
        schema:
          type: string
          minLength: 2
          maxLength: 40
      - name: bill
        in: query
        required: false
        description: 'Filter by bill reference (case-insensitive substring on legis_num). Examples: "H R 498", "H R 49", "S 1".'
        schema:
          type: string
          minLength: 2
          maxLength: 40
      - name: since
        in: query
        required: false
        description: Earliest action date (YYYY-MM-DD).
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: until
        in: query
        required: false
        description: Latest action date (YYYY-MM-DD).
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: limit
        in: query
        required: false
        description: Max records (1-100). Default 25.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        required: false
        description: Offset for pagination. Default 0.
        schema:
          type: integer
          minimum: 0
          maximum: 100000
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/income-limits:
    get:
      tags:
      - gov
      summary: HUD Income Limits (IL) for a US county or state - the
      description: 'HUD Income Limits (IL) for a US county or state — the program-eligibility thresholds for HUD assistance, derived from Area Median Family Income: extremely-low (30% AMI), very-low (50% AMI), and low (80% AMI) income limits for household sizes 1–8, plus the area median income. Look up by 5-digit county FIPS or by 2-letter state. Optional year (defaults to latest). The raw HUD il30/il50/il80 codes are reshaped into clear nested limits by household size. Source: HUD USER Income Limits API (US public domain).'
      operationId: gov_income-limits
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [one income-limits lookup with medianIncome + 30/50/80% AMI limits by household size]; total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            scope:
                              type: string
                              enum:
                              - county
                              - state
                            fips:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            year:
                              type: string
                              nullable: true
                            areaName:
                              type: string
                              nullable: true
                            medianIncome:
                              type: number
                              nullable: true
                            extremelyLow30pct:
                              type: object
                              properties:
                                hh1:
                                  type: number
                                  nullable: true
                                hh2:
                                  type: number
                                  nullable: true
                                hh3:
                                  type: number
                                  nullable: true
                                hh4:
                                  type: number
                                  nullable: true
                                hh5:
                                  type: number
                                  nullable: true
                                hh6:
                                  type: number
                                  nullable: true
                                hh7:
                                  type: number
                                  nullable: true
                                hh8:
                                  type: number
                                  nullable: true
                              required:
                              - hh1
                              - hh2
                              - hh3
                              - hh4
                              - hh5
                              - hh6
                              - hh7
                              - hh8
                              additionalProperties: false
                            veryLow50pct:
                              type: object
                              properties:
                                hh1:
                                  type: number
                                  nullable: true
                                hh2:
                                  type: number
                                  nullable: true
                                hh3:
                                  type: number
                                  nullable: true
                                hh4:
                                  type: number
                                  nullable: true
                                hh5:
                                  type: number
                                  nullable: true
                                hh6:
                                  type: number
                                  nullable: true
                                hh7:
                                  type: number
                                  nullable: true
                                hh8:
                                  type: number
                                  nullable: true
                              required:
                              - hh1
                              - hh2
                              - hh3
                              - hh4
                              - hh5
                              - hh6
                              - hh7
                              - hh8
                              additionalProperties: false
                            lowIncome80pct:
                              type: object
                              properties:
                                hh1:
                                  type: number
                                  nullable: true
                                hh2:
                                  type: number
                                  nullable: true
                                hh3:
                                  type: number
                                  nullable: true
                                hh4:
                                  type: number
                                  nullable: true
                                hh5:
                                  type: number
                                  nullable: true
                                hh6:
                                  type: number
                                  nullable: true
                                hh7:
                                  type: number
                                  nullable: true
                                hh8:
                                  type: number
                                  nullable: true
                              required:
                              - hh1
                              - hh2
                              - hh3
                              - hh4
                              - hh5
                              - hh6
                              - hh7
                              - hh8
                              additionalProperties: false
                          required:
                          - scope
                          - fips
                          - state
                          - year
                          - areaName
                          - medianIncome
                          - extremelyLow30pct
                          - veryLow50pct
                          - lowIncome80pct
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.income-limits
      x-2s-version: null
      x-2s-price:
        usd: 0.012
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.012000'
        protocols:
        - x402: {}
      parameters:
      - name: fips
        in: query
        required: false
        description: 5-digit US county FIPS, e.g. 06037 (Los Angeles County).
        schema:
          type: string
          pattern: ^\d{5}$
      - name: state
        in: query
        required: false
        description: 2-letter US state abbreviation, e.g. CA.
        schema:
          type: string
          pattern: ^[A-Za-z]{2}$
      - name: year
        in: query
        required: false
        description: Income-limit year, e.g. 2026. Omit for the latest.
        schema:
          type: string
          pattern: ^\d{4}$
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/inmate-locator:
    get:
      tags:
      - gov
      summary: Search the Federal Bureau of Prisons inmate locator
      description: 'Search the Federal Bureau of Prisons inmate locator — federal inmates from 1982 to present, both currently incarcerated and released. Search by lastName (+ optional firstName/middleName, age, sex, race) or by exact BOP register number (inmateNumber, e.g. "12345-678"). Each match: full name, register number, sex, race, age, current facility (code/name/type), projected release date, actual release date (when released). KYC, due-diligence, journalism, and background-research staple. Federal public data.'
      operationId: gov_inmate-locator
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = matched federal inmates; total = match count (null when BOP capped the list); meta.capped flags truncation.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            name:
                              type: object
                              properties:
                                first:
                                  type: string
                                  nullable: true
                                middle:
                                  type: string
                                  nullable: true
                                last:
                                  type: string
                                  nullable: true
                                suffix:
                                  type: string
                                  nullable: true
                              required:
                              - first
                              - middle
                              - last
                              - suffix
                              additionalProperties: false
                            inmateNumber:
                              type: string
                              nullable: true
                            sex:
                              type: string
                              nullable: true
                            race:
                              type: string
                              nullable: true
                            age:
                              type: number
                              nullable: true
                            facility:
                              type: object
                              properties:
                                code:
                                  type: string
                                  nullable: true
                                name:
                                  type: string
                                  nullable: true
                                type:
                                  type: string
                                  nullable: true
                              required:
                              - code
                              - name
                              - type
                              additionalProperties: false
                              nullable: true
                            projectedReleaseDate:
                              type: string
                              nullable: true
                            actualReleaseDate:
                              type: string
                              nullable: true
                            releaseCode:
                              type: string
                              nullable: true
                          required:
                          - name
                          - inmateNumber
                          - sex
                          - race
                          - age
                          - facility
                          - projectedReleaseDate
                          - actualReleaseDate
                          - releaseCode
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          capped:
                            type: boolean
                            description: True when BOP truncated the match list; total is null in that case.
                        required:
                        - capped
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.inmate-locator
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: lastName
        in: query
        required: false
        description: Last name to filter by.
        schema:
          type: string
          minLength: 2
          maxLength: 80
      - name: firstName
        in: query
        required: false
        description: First name to filter by.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: middleName
        in: query
        required: false
        description: Middle name.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: inmateNumber
        in: query
        required: false
        description: Inmate number.
        schema:
          type: string
          pattern: ^\d{5}-\d{3}$
      - name: age
        in: query
        required: false
        description: Age.
        schema:
          type: integer
          minimum: 18
          maximum: 120
      - name: sex
        in: query
        required: false
        description: Sex.
        schema:
          type: string
          enum:
          - Male
          - Female
      - name: race
        in: query
        required: false
        description: Race.
        schema:
          type: string
          maxLength: 40
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/lobbying-filings:
    get:
      tags:
      - gov
      summary: Search US federal lobbying disclosures (Senate LDA filings)
      description: 'Search US federal lobbying disclosures (Senate LDA filings) — who lobbies for whom, on what issues, for how much. Filter by registrant (lobbying firm name), client (organization being represented), lobbyist (individual name), year, period (first_quarter|second_quarter|third_quarter|fourth_quarter|mid_year|year_end), and type (e.g. RR=registration, Q1-Q4=quarterly reports). Each filing: type, year/period, reported income or expenses (USD), registrant + client (id/name/description/state), lobbying issues (code + description), lobbyist count, official document URL, posted timestamp. Money-in-politics, journalism, and policy-intelligence staple. Public federal data.'
      operationId: gov_lobbying-filings
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = LDA lobbying filings (registrant, client, issues, income/expenses); total = upstream match count.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            filingUuid:
                              type: string
                            type:
                              type: string
                              nullable: true
                            typeDisplay:
                              type: string
                              nullable: true
                            year:
                              type: number
                              nullable: true
                            period:
                              type: string
                              nullable: true
                            periodDisplay:
                              type: string
                              nullable: true
                            income:
                              type: number
                              nullable: true
                            expenses:
                              type: number
                              nullable: true
                            registrant:
                              type: object
                              properties:
                                id:
                                  type: number
                                  nullable: true
                                name:
                                  type: string
                                  nullable: true
                                description:
                                  type: string
                                  nullable: true
                              required:
                              - id
                              - name
                              - description
                              additionalProperties: false
                              nullable: true
                            client:
                              type: object
                              properties:
                                id:
                                  type: number
                                  nullable: true
                                name:
                                  type: string
                                  nullable: true
                                description:
                                  type: string
                                  nullable: true
                                state:
                                  type: string
                                  nullable: true
                              required:
                              - id
                              - name
                              - description
                              - state
                              additionalProperties: false
                              nullable: true
                            issues:
                              type: array
                              items:
                                type: object
                                properties:
                                  code:
                                    type: string
                                    nullable: true
                                  description:
                                    type: string
                                    nullable: true
                                required:
                                - code
                                - description
                                additionalProperties: false
                            lobbyistCount:
                              type: number
                            documentUrl:
                              type: string
                              nullable: true
                            postedAt:
                              type: string
                              nullable: true
                          required:
                          - filingUuid
                          - type
                          - typeDisplay
                          - year
                          - period
                          - periodDisplay
                          - income
                          - expenses
                          - registrant
                          - client
                          - issues
                          - lobbyistCount
                          - documentUrl
                          - postedAt
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.lobbying-filings
      x-2s-version: null
      x-2s-price:
        usd: 0.0072
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.007200'
        protocols:
        - x402: {}
      parameters:
      - name: registrant
        in: query
        required: false
        description: Registrant.
        schema:
          type: string
          minLength: 2
          maxLength: 120
      - name: client
        in: query
        required: false
        description: Client.
        schema:
          type: string
          minLength: 2
          maxLength: 120
      - name: lobbyist
        in: query
        required: false
        description: Lobbyist.
        schema:
          type: string
          minLength: 2
          maxLength: 120
      - name: year
        in: query
        required: false
        description: Four-digit calendar year.
        schema:
          type: integer
          minimum: 1999
          maximum: 2030
      - name: period
        in: query
        required: false
        description: Period.
        schema:
          type: string
          enum:
          - first_quarter
          - second_quarter
          - third_quarter
          - fourth_quarter
          - mid_year
          - year_end
      - name: type
        in: query
        required: false
        description: Filter results by type.
        schema:
          type: string
          maxLength: 8
      - name: page
        in: query
        required: false
        description: Page number (1-based) for paginated results.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: pageSize
        in: query
        required: false
        description: Number of results to return per page.
        schema:
          type: integer
          minimum: 1
          maximum: 25
          default: 10
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/msha-accidents:
    get:
      tags:
      - gov
      summary: Search MSHA mine safety accident records via US Department
      description: Search MSHA mine safety accident records via US Department of Labor Open Data Portal (~738k accidents at US mines). Each row carries mine id, contractor id, mine subunit (underground/surface/mill/etc.), FIPS state code, accident date, classification, narrative, injury degree + nature + body-part, occupation code, experience, schooling, sex, age. Filter by mine id, contractor id, FIPS state code, subunit code, accident date range, classification code. Source of truth for fatalities + injuries at every US coal + metal/nonmetal mine since 2000.
      operationId: gov_msha-accidents
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = MSHA mine safety accident records.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties: {}
                          additionalProperties: true
                          description: Raw DOL MSHA accident row with snake_case column names (mine_id, cntctr_id, subunit_cd, fips_state_cd, accident_dt, classification_cd, degree_inj_cd, …). Column set follows the DOL dataset and any fields projection.
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          nextOffset:
                            type: integer
                            nullable: true
                        required:
                        - nextOffset
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.msha-accidents
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: mineId
        in: query
        required: false
        description: Mine ID.
        schema:
          type: string
          pattern: ^\d{4,8}$
      - name: contractorId
        in: query
        required: false
        description: Contractor ID.
        schema:
          type: string
          pattern: ^[A-Z0-9]{3,10}$
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          pattern: ^\d{2}$
      - name: subunit
        in: query
        required: false
        description: Subunit.
        schema:
          type: string
          pattern: ^\d{2}$
      - name: accidentDateMin
        in: query
        required: false
        description: Accident date min.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: accidentDateMax
        in: query
        required: false
        description: Accident date max.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: classification
        in: query
        required: false
        description: Classification.
        schema:
          type: string
          pattern: ^\d{2,3}$
      - name: fields
        in: query
        required: false
        description: Fields.
        schema:
          type: string
          pattern: ^[a-z][a-z0-9_]*(,[a-z][a-z0-9_]*)*$
          maxLength: 400
      - name: sort
        in: query
        required: false
        description: Field to sort results by.
        schema:
          type: string
          pattern: ^-?[a-z][a-z0-9_]*$
          maxLength: 120
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/nfip-claims:
    get:
      tags:
      - gov
      summary: FEMA National Flood Insurance Program (NFIP) claims history
      description: 'FEMA National Flood Insurance Program (NFIP) claims history for a US location — the flood losses actually paid out in an area. Requires state (2-letter); optionally narrow by county (5-digit FIPS), ZIP, and yearOfLoss range (yearFrom/yearTo). Returns the total matching claim count plus recent redacted claim records (date of loss, county / census tract / ZIP, flood zone rated at time of loss, cause of damage, water depth, net building + contents payment in USD, building coverage, approximate lat/lon), largest net payout first (the notable losses). FEMA redacts the city field, so filter by county FIPS or ZIP. Free, public-domain (OpenFEMA). Distinct from geo.flood-zone (current SFHA designation) and gov.risk-index (modeled future risk): this is the realized loss track record — for insurance underwriting and property due diligence.'
      operationId: gov_nfip-claims
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      query:
                        type: object
                        properties:
                          state:
                            type: string
                          county:
                            type: string
                            nullable: true
                          zip:
                            type: string
                            nullable: true
                          yearFrom:
                            type: number
                            nullable: true
                          yearTo:
                            type: number
                            nullable: true
                          limit:
                            type: number
                        required:
                        - state
                        - county
                        - zip
                        - yearFrom
                        - yearTo
                        - limit
                        additionalProperties: false
                      totalClaims:
                        type: number
                        nullable: true
                      returned:
                        type: number
                      returnedSummary:
                        type: object
                        properties:
                          totalPaid:
                            type: number
                          averagePaid:
                            type: number
                            nullable: true
                        required:
                        - totalPaid
                        - averagePaid
                        additionalProperties: false
                      claims:
                        type: array
                        items:
                          type: object
                          properties:
                            dateOfLoss:
                              type: string
                              nullable: true
                            yearOfLoss:
                              type: number
                              nullable: true
                            countyCode:
                              type: string
                              nullable: true
                            censusTract:
                              type: string
                              nullable: true
                            zipCode:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            ratedFloodZone:
                              type: string
                              nullable: true
                            causeOfDamage:
                              type: string
                              nullable: true
                            waterDepth:
                              type: number
                              nullable: true
                            occupancyType:
                              type: number
                              nullable: true
                            netBuildingPaymentUSD:
                              type: number
                              nullable: true
                            netContentsPaymentUSD:
                              type: number
                              nullable: true
                            totalAmountPaid:
                              type: number
                              nullable: true
                            totalBuildingInsuranceCoverage:
                              type: number
                              nullable: true
                            latitude:
                              type: number
                              nullable: true
                            longitude:
                              type: number
                              nullable: true
                          required:
                          - dateOfLoss
                          - yearOfLoss
                          - countyCode
                          - censusTract
                          - zipCode
                          - state
                          - ratedFloodZone
                          - causeOfDamage
                          - waterDepth
                          - occupancyType
                          - netBuildingPaymentUSD
                          - netContentsPaymentUSD
                          - totalAmountPaid
                          - totalBuildingInsuranceCoverage
                          - latitude
                          - longitude
                          additionalProperties: false
                      source:
                        $ref: '#/components/schemas/Source'
                      note:
                        type: string
                    required:
                    - query
                    - totalClaims
                    - returned
                    - returnedSummary
                    - claims
                    - source
                    - note
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.nfip-claims
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: legacy
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: state
        in: query
        required: true
        description: 2-letter US state/territory code.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: county
        in: query
        required: false
        description: County name to filter by.
        schema:
          type: string
          pattern: ^\d{5}$
      - name: zip
        in: query
        required: false
        description: US ZIP code.
        schema:
          type: string
          pattern: ^\d{5}$
      - name: yearFrom
        in: query
        required: false
        description: Year from.
        schema:
          type: integer
          minimum: 1970
          maximum: 2100
      - name: yearTo
        in: query
        required: false
        description: Year to.
        schema:
          type: integer
          minimum: 1970
          maximum: 2100
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/osha-accidents:
    get:
      tags:
      - gov
      summary: Search OSHA-investigated workplace accident reports via US
      description: Search OSHA-investigated workplace accident reports via US Department of Labor Open Data Portal (~165k accidents). Each row carries summary number, related inspection number, report id, event date, narrative, nature of injury, body part affected, source of injury, occupation, age, sex, degree of injury (1 = fatality, 2 = hospitalized, 3 = no lost time, etc.). Filter by event date range, nature of injury code, fatality flag. Pair with /api/gov/osha-inspections + /api/gov/osha-violations to follow injury → investigation → citations.
      operationId: gov_osha-accidents
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = OSHA workplace accident reports.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties: {}
                          additionalProperties: true
                          description: Raw DOL OSHA accident row with snake_case column names (summary_nr, report_id, event_date, degree_of_inj, nature_of_inj, body_part_cd, …). Column set follows the DOL dataset and any fields projection.
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          nextOffset:
                            type: integer
                            nullable: true
                        required:
                        - nextOffset
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.osha-accidents
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: summaryNr
        in: query
        required: false
        description: Summary nr.
        schema:
          type: integer
          minimum: 1
      - name: activityNr
        in: query
        required: false
        description: Activity nr.
        schema:
          type: integer
          minimum: 1
      - name: reportId
        in: query
        required: false
        description: Report ID.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: eventDateMin
        in: query
        required: false
        description: Event date min.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: eventDateMax
        in: query
        required: false
        description: Event date max.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: natureOfInj
        in: query
        required: false
        description: Nature of inj.
        schema:
          type: string
          minLength: 1
          maxLength: 20
      - name: fields
        in: query
        required: false
        description: Fields.
        schema:
          type: string
          pattern: ^[a-z][a-z0-9_]*(,[a-z][a-z0-9_]*)*$
          maxLength: 400
      - name: sort
        in: query
        required: false
        description: Field to sort results by.
        schema:
          type: string
          pattern: ^-?[a-z][a-z0-9_]*$
          maxLength: 120
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/osha-inspections:
    get:
      tags:
      - gov
      summary: Search OSHA inspection records via the US Department of
      description: Search OSHA inspection records via the US Department of Labor Open Data Portal (~5M historical inspections). Filter by US state (2-letter), city, zip, or establishment-name substring (estabName, case-insensitive). Optional `filter` accepts raw OData-style clauses (joined with AND); `fields` selects columns; `sort` sorts (prefix with `-` for desc). Each row carries activity number, reporting id, establishment name + full site address, owner type/code, advance-notice flag, safety/health type, SIC + NAICS industry codes, open + close dates, host establishment number, union status. Backbone of workplace-safety + investigative-journalism agents.
      operationId: gov_osha-inspections
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = OSHA inspection records.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            activityNr:
                              type: number
                              description: OSHA inspection activity number — join key for /api/gov/osha-violations.
                            reportingId:
                              type: string
                              nullable: true
                            estabName:
                              type: string
                              nullable: true
                            siteAddress:
                              type: string
                              nullable: true
                            siteCity:
                              type: string
                              nullable: true
                            siteState:
                              type: string
                              nullable: true
                            siteZip:
                              type: string
                              nullable: true
                            ownerType:
                              type: string
                              nullable: true
                            ownerCode:
                              type: string
                              nullable: true
                            advNotice:
                              type: string
                              nullable: true
                              description: Advance-notice flag.
                            safetyHlth:
                              type: string
                              nullable: true
                              description: S = safety, H = health inspection.
                            sicCode:
                              type: string
                              nullable: true
                            naicsCode:
                              type: string
                              nullable: true
                            openDate:
                              type: string
                              nullable: true
                            caseMod:
                              type: string
                              nullable: true
                            closeCondDate:
                              type: string
                              nullable: true
                            closeCaseDate:
                              type: string
                              nullable: true
                            ldDate:
                              type: string
                              nullable: true
                            hostEstNum:
                              type: string
                              nullable: true
                            unionStatus:
                              type: string
                              nullable: true
                          additionalProperties: false
                          description: Fields are absent when a fields projection excludes their source column.
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          nextOffset:
                            type: integer
                            nullable: true
                        required:
                        - nextOffset
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.osha-inspections
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
      - name: city
        in: query
        required: false
        description: City name to filter by.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: zip
        in: query
        required: false
        description: US ZIP code.
        schema:
          type: string
          pattern: ^\d{5}$
      - name: estabName
        in: query
        required: false
        description: Estab name.
        schema:
          type: string
          minLength: 2
          maxLength: 120
      - name: fields
        in: query
        required: false
        description: Fields.
        schema:
          type: string
          minLength: 1
          maxLength: 400
      - name: filter
        in: query
        required: false
        description: Filter.
        schema:
          type: string
          minLength: 1
          maxLength: 600
      - name: sort
        in: query
        required: false
        description: Field to sort results by.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/osha-violations:
    get:
      tags:
      - gov
      summary: Search OSHA citation / violation records via US Department
      description: Search OSHA citation / violation records via US Department of Labor Open Data Portal (~13.2M citations). Each citation links to an inspection via `activityNr` — pair with /api/gov/osha-inspections to follow site → inspection → violations. Filter by activityNr, citationId, standard (29 CFR section, e.g. "19100132" for PPE general requirements), issuance date range, initial-penalty min/max, emphasis program code.
      operationId: gov_osha-violations
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = OSHA violation records.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties: {}
                          additionalProperties: true
                          description: Raw DOL OSHA citation row with snake_case column names (activity_nr, citation_id, standard, issuance_date, initial_penalty, emphasis, …). Column set follows the DOL dataset and any fields projection.
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          nextOffset:
                            type: integer
                            nullable: true
                        required:
                        - nextOffset
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.osha-violations
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: activityNr
        in: query
        required: false
        description: Activity nr.
        schema:
          type: integer
          minimum: 1
      - name: citationId
        in: query
        required: false
        description: Citation ID.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: standard
        in: query
        required: false
        description: Standard.
        schema:
          type: string
          minLength: 2
          maxLength: 40
      - name: issuanceDateMin
        in: query
        required: false
        description: Issuance date min.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: issuanceDateMax
        in: query
        required: false
        description: Issuance date max.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: initialPenalty
        in: query
        required: false
        description: Initial penalty.
        schema:
          type: object
          properties:
            min:
              type: number
              minimum: 0
            max:
              type: number
              minimum: 0
          additionalProperties: false
      - name: emphasis
        in: query
        required: false
        description: Emphasis.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: fields
        in: query
        required: false
        description: Fields.
        schema:
          type: string
          pattern: ^[a-z][a-z0-9_]*(,[a-z][a-z0-9_]*)*$
          maxLength: 400
      - name: sort
        in: query
        required: false
        description: Field to sort results by.
        schema:
          type: string
          pattern: ^-?[a-z][a-z0-9_]*$
          maxLength: 120
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        required: false
        description: Number of results to skip before returning (pagination offset).
        schema:
          type: integer
          minimum: 0
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/product-recalls:
    get:
      tags:
      - gov
      summary: CPSC consumer-product recalls from SaferProducts.gov
      description: 'CPSC consumer-product recalls from SaferProducts.gov, newest first. Covers products outside FDA (food/drug/device) and NHTSA (vehicles): strollers, appliances, lithium batteries, furniture, toys, power tools, and more. All filters optional (with none set, returns the last 12 months). Each record includes recall number + date, title, CPSC URL, description, affected products (name/model/units), hazards, remedies, reported injuries, manufacturers/importers/distributors/retailers, where sold, manufacturing countries, images, and consumer-contact info. Public-domain US government data.'
      operationId: gov_product-recalls
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = CPSC consumer-product recalls, newest first; total = upstream match count; meta.query echoes the search.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            recallId:
                              type: string
                              nullable: true
                            recallNumber:
                              type: string
                              nullable: true
                            recallDate:
                              type: string
                              nullable: true
                            lastPublishDate:
                              type: string
                              nullable: true
                            title:
                              type: string
                              nullable: true
                            url:
                              type: string
                              nullable: true
                            description:
                              type: string
                              nullable: true
                            products:
                              type: array
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                    nullable: true
                                  model:
                                    type: string
                                    nullable: true
                                  units:
                                    type: string
                                    nullable: true
                                required:
                                - name
                                - model
                                - units
                                additionalProperties: false
                            hazards:
                              type: array
                              items:
                                type: string
                            remedies:
                              type: array
                              items:
                                type: string
                            injuries:
                              type: array
                              items:
                                type: string
                            manufacturers:
                              type: array
                              items:
                                type: string
                            retailers:
                              type: array
                              items:
                                type: string
                            importers:
                              type: array
                              items:
                                type: string
                            distributors:
                              type: array
                              items:
                                type: string
                            soldAt:
                              type: string
                              nullable: true
                            manufacturerCountries:
                              type: array
                              items:
                                type: string
                            images:
                              type: array
                              items:
                                type: string
                            consumerContact:
                              type: string
                              nullable: true
                          required:
                          - recallId
                          - recallNumber
                          - recallDate
                          - lastPublishDate
                          - title
                          - url
                          - description
                          - products
                          - hazards
                          - remedies
                          - injuries
                          - manufacturers
                          - retailers
                          - importers
                          - distributors
                          - soldAt
                          - manufacturerCountries
                          - images
                          - consumerContact
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              title:
                                type: string
                                nullable: true
                              productName:
                                type: string
                                nullable: true
                              recallNumber:
                                type: string
                                nullable: true
                              dateStart:
                                type: string
                                nullable: true
                              dateEnd:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                            required:
                            - title
                            - productName
                            - recallNumber
                            - dateStart
                            - dateEnd
                            - limit
                            additionalProperties: false
                        required:
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.product-recalls
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: title
        in: query
        required: false
        description: 'Optional substring match on the recall title. Examples: "stroller", "lithium battery", "space heater".'
        schema:
          type: string
          minLength: 2
          maxLength: 100
      - name: productName
        in: query
        required: false
        description: Optional substring match on an affected product name.
        schema:
          type: string
          minLength: 2
          maxLength: 100
      - name: recallNumber
        in: query
        required: false
        description: Optional exact CPSC recall number, e.g., "26094".
        schema:
          type: string
          minLength: 3
          maxLength: 20
      - name: dateStart
        in: query
        required: false
        description: Optional earliest recall date (YYYY-MM-DD).
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: dateEnd
        in: query
        required: false
        description: Optional latest recall date (YYYY-MM-DD).
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: limit
        in: query
        required: false
        description: Max recalls to return (1-50). Default 20.
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 20
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/public-assistance:
    get:
      tags:
      - gov
      summary: FEMA Public Assistance (PA) funded project details - the
      description: FEMA Public Assistance (PA) funded project details — the post-disaster grants FEMA obligates to state/local/tribal governments and eligible nonprofits to repair public infrastructure and cover emergency response (debris removal, emergency protective measures, roads, buildings, utilities, parks). Filter by state (2-letter) and/or disasterNumber (one of the two is required); optionally refine by incidentType. Returns the total matching worksheet count plus projects (disaster number, declaration date, incident type, project worksheet number, application title, applicant, damage category, project size, status, county, federal share obligated / total obligated / project amount in USD, obligation date), largest federal share first. Free, public-domain (OpenFEMA). Distinct from gov.hazard-mitigation (future-risk mitigation grants) and gov.nfip-claims (flood losses paid) — this is disaster recovery funding for public infrastructure.
      operationId: gov_public-assistance
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [one PA result object]; total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            query:
                              type: object
                              properties:
                                state:
                                  type: string
                                  nullable: true
                                disasterNumber:
                                  type: number
                                  nullable: true
                                incidentType:
                                  type: string
                                  nullable: true
                                limit:
                                  type: number
                              required:
                              - state
                              - disasterNumber
                              - incidentType
                              - limit
                              additionalProperties: false
                            totalProjects:
                              type: number
                              nullable: true
                            returned:
                              type: number
                            returnedSummary:
                              type: object
                              properties:
                                totalFederalShareUSD:
                                  type: number
                                totalObligatedUSD:
                                  type: number
                              required:
                              - totalFederalShareUSD
                              - totalObligatedUSD
                              additionalProperties: false
                            projects:
                              type: array
                              items:
                                type: object
                                properties:
                                  disasterNumber:
                                    type: number
                                    nullable: true
                                  declarationDate:
                                    type: string
                                    nullable: true
                                  incidentType:
                                    type: string
                                    nullable: true
                                  pwNumber:
                                    type: string
                                    nullable: true
                                  applicationTitle:
                                    type: string
                                    nullable: true
                                  applicantId:
                                    type: string
                                    nullable: true
                                  damageCategory:
                                    type: string
                                    nullable: true
                                  damageCategoryCode:
                                    type: string
                                    nullable: true
                                  projectSize:
                                    type: string
                                    nullable: true
                                  projectStatus:
                                    type: string
                                    nullable: true
                                  county:
                                    type: string
                                    nullable: true
                                  countyCode:
                                    type: string
                                    nullable: true
                                  state:
                                    type: string
                                    nullable: true
                                  stateCode:
                                    type: string
                                    nullable: true
                                  projectAmountUSD:
                                    type: number
                                    nullable: true
                                  federalShareObligatedUSD:
                                    type: number
                                    nullable: true
                                  totalObligatedUSD:
                                    type: number
                                    nullable: true
                                  obligatedDate:
                                    type: string
                                    nullable: true
                                required:
                                - disasterNumber
                                - declarationDate
                                - incidentType
                                - pwNumber
                                - applicationTitle
                                - applicantId
                                - damageCategory
                                - damageCategoryCode
                                - projectSize
                                - projectStatus
                                - county
                                - countyCode
                                - state
                                - stateCode
                                - projectAmountUSD
                                - federalShareObligatedUSD
                                - totalObligatedUSD
                                - obligatedDate
                                additionalProperties: false
                            source:
                              $ref: '#/components/schemas/Source'
                            note:
                              type: string
                          required:
                          - query
                          - totalProjects
                          - returned
                          - returnedSummary
                          - projects
                          - source
                          - note
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.public-assistance
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: state
        in: query
        required: false
        description: 2-letter US state/territory code.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: disasterNumber
        in: query
        required: false
        description: Disaster number.
        schema:
          type: integer
          minimum: 1
          maximum: 100000
      - name: incidentType
        in: query
        required: false
        description: Incident type.
        schema:
          type: string
          minLength: 1
          maxLength: 40
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/representatives:
    get:
      tags:
      - gov
      summary: Your sitting members of the US Congress for a location
      description: Your sitting members of the US Congress for a location. Pass a US address (geocoded to its state + congressional district for you), or an explicit state (2-letter) with optional district number. Returns the current US House representative for that district plus the state's two US senators — each with full name, party, state/district, the Bioguide ID, DC office, phone, official website, and contact form. State-only returns just the two senators; territories/DC return their non-voting delegate (no senators). Bundled CC0 data (unitedstates/congress-legislators), refreshed periodically. Fills the gap after gov.district (which gives the district, not the people) — for civic lookup, advocacy, and constituent tooling.
      operationId: gov_representatives
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      query:
                        type: object
                        properties:
                          address:
                            type: string
                            nullable: true
                          state:
                            type: string
                            nullable: true
                          district:
                            type: string
                            nullable: true
                        required:
                        - address
                        - state
                        - district
                        additionalProperties: false
                      resolved:
                        type: object
                        properties:
                          matchedAddress:
                            type: string
                            nullable: true
                          state:
                            type: string
                            nullable: true
                          district:
                            type: string
                            nullable: true
                        required:
                        - matchedAddress
                        - state
                        - district
                        additionalProperties: false
                      house:
                        type: object
                        properties:
                          bioguideId:
                            type: string
                            nullable: true
                          name:
                            type: string
                            nullable: true
                          chamber:
                            type: string
                            enum:
                            - house
                          party:
                            type: string
                            nullable: true
                          state:
                            type: string
                            nullable: true
                          district:
                            type: string
                            nullable: true
                          phone:
                            type: string
                            nullable: true
                          office:
                            type: string
                            nullable: true
                          contactForm:
                            type: string
                            nullable: true
                          website:
                            type: string
                            nullable: true
                          termEnd:
                            type: string
                            nullable: true
                        required:
                        - bioguideId
                        - name
                        - chamber
                        - party
                        - state
                        - district
                        - phone
                        - office
                        - contactForm
                        - website
                        - termEnd
                        additionalProperties: false
                        nullable: true
                      senate:
                        type: array
                        items:
                          type: object
                          properties:
                            bioguideId:
                              type: string
                              nullable: true
                            name:
                              type: string
                              nullable: true
                            chamber:
                              type: string
                              enum:
                              - senate
                            party:
                              type: string
                              nullable: true
                            state:
                              type: string
                              nullable: true
                            district:
                              type: string
                              nullable: true
                            phone:
                              type: string
                              nullable: true
                            office:
                              type: string
                              nullable: true
                            contactForm:
                              type: string
                              nullable: true
                            website:
                              type: string
                              nullable: true
                            termEnd:
                              type: string
                              nullable: true
                          required:
                          - bioguideId
                          - name
                          - chamber
                          - party
                          - state
                          - district
                          - phone
                          - office
                          - contactForm
                          - website
                          - termEnd
                          additionalProperties: false
                      source:
                        type: array
                        items:
                          $ref: '#/components/schemas/Source'
                      note:
                        type: string
                    required:
                    - query
                    - resolved
                    - house
                    - senate
                    - source
                    - note
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.representatives
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: legacy
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: address
        in: query
        required: false
        description: Street address or full address string.
        schema:
          type: string
          minLength: 5
          maxLength: 200
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: district
        in: query
        required: false
        description: District.
        schema:
          anyOf:
          - type: string
          - type: number
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/risk-index:
    get:
      tags:
      - gov
      summary: FEMA National Risk Index for a US county - the
      description: FEMA National Risk Index for a US county — the authoritative natural-hazard risk profile. Look up by countyFips (5-digit STCOFIPS), by state + county name, or by a lat/lon point. Returns the composite Risk Index score/rating/national-percentile (an 18-hazard model combining Expected Annual Loss × Social Vulnerability ÷ Community Resilience), each component (expected annual loss in dollars, social vulnerability, community resilience) with its rating, and per-hazard risk ratings + expected-annual-loss for all 18 natural hazards (wildfire, earthquake, hurricane, riverine & coastal flooding, tornado, heat/cold wave, drought, etc.). The structural natural-hazard risk picture an LLM can't recall — for siting, insurance, and resilience planning. Free, public-domain. Complements geo.flood-zone (which is flood SFHA only).
      operationId: gov_risk-index
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      query:
                        type: object
                        properties:
                          countyFips:
                            type: string
                            nullable: true
                          state:
                            type: string
                            nullable: true
                          county:
                            type: string
                            nullable: true
                          lat:
                            type: number
                            nullable: true
                          lon:
                            type: number
                            nullable: true
                        required:
                        - countyFips
                        - state
                        - county
                        - lat
                        - lon
                        additionalProperties: false
                      found:
                        type: boolean
                      county:
                        type: string
                        nullable: true
                      state:
                        type: string
                        nullable: true
                      stateAbbrev:
                        type: string
                        nullable: true
                      countyFips:
                        type: string
                        nullable: true
                      population:
                        type: number
                        nullable: true
                      riskIndex:
                        type: object
                        properties:
                          score:
                            type: number
                            nullable: true
                          rating:
                            type: string
                            nullable: true
                          nationalPercentile:
                            type: number
                            nullable: true
                        required:
                        - score
                        - rating
                        - nationalPercentile
                        additionalProperties: false
                      expectedAnnualLoss:
                        type: object
                        properties:
                          totalUSD:
                            type: number
                            nullable: true
                          rating:
                            type: string
                            nullable: true
                          nationalPercentile:
                            type: number
                            nullable: true
                        required:
                        - totalUSD
                        - rating
                        - nationalPercentile
                        additionalProperties: false
                      socialVulnerability:
                        type: object
                        properties:
                          score:
                            type: number
                            nullable: true
                          rating:
                            type: string
                            nullable: true
                          nationalPercentile:
                            type: number
                            nullable: true
                        required:
                        - score
                        - rating
                        - nationalPercentile
                        additionalProperties: false
                      communityResilience:
                        type: object
                        properties:
                          score:
                            type: number
                            nullable: true
                          rating:
                            type: string
                            nullable: true
                          nationalPercentile:
                            type: number
                            nullable: true
                        required:
                        - score
                        - rating
                        - nationalPercentile
                        additionalProperties: false
                      hazards:
                        type: array
                        items:
                          type: object
                          properties:
                            code:
                              type: string
                            hazard:
                              type: string
                            riskRating:
                              type: string
                              nullable: true
                            riskScore:
                              type: number
                              nullable: true
                            expectedAnnualLossUSD:
                              type: number
                              nullable: true
                          required:
                          - code
                          - hazard
                          - riskRating
                          - riskScore
                          - expectedAnnualLossUSD
                          additionalProperties: false
                      sources:
                        type: array
                        items:
                          $ref: '#/components/schemas/Source'
                      note:
                        type: string
                        nullable: true
                    required:
                    - query
                    - found
                    - county
                    - state
                    - stateAbbrev
                    - countyFips
                    - population
                    - riskIndex
                    - expectedAnnualLoss
                    - socialVulnerability
                    - communityResilience
                    - hazards
                    - sources
                    - note
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.risk-index
      x-2s-version: null
      x-2s-price:
        usd: 0.0045
      x-2s-accepts:
      - x402
      x-2s-response-shape: legacy
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.004500'
        protocols:
        - x402: {}
      parameters:
      - name: countyFips
        in: query
        required: false
        description: County fips.
        schema:
          type: string
          pattern: ^\d{5}$
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 40
      - name: county
        in: query
        required: false
        description: County name to filter by.
        schema:
          type: string
          minLength: 2
          maxLength: 60
      - name: lat
        in: query
        required: false
        description: Latitude in decimal degrees (WGS84).
        schema:
          type: number
          minimum: -90
          maximum: 90
      - name: lon
        in: query
        required: false
        description: Longitude in decimal degrees (WGS84).
        schema:
          type: number
          minimum: -180
          maximum: 180
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/senate-votes:
    get:
      tags:
      - gov
      summary: US Senate roll-call votes, newest first by vote date
      description: 'US Senate roll-call votes, newest first by vote date. Each record includes congress + session + vote_number, vote question + result + title + majority requirement, vote date/time, document name (e.g., S. 5, H.R. 4499), document title, grand totals (yeas/nays/present/absent), AND per-party breakdown (D/R/I yea/nay/present/absent counts derived from member-level vote_cast). Filters (all optional, AND-combined): congress, session (1 or 2), result substring, document substring (e.g., ''S. 5''), since/until (vote_date), limit + offset. Locally aggregated from senate.gov XML feeds (refreshed daily). Public-domain US government records.'
      operationId: gov_senate-votes
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = US Senate roll-call votes with per-party totals; total = matching rows; meta carries the query echo + nextOffset/previousOffset.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            congress:
                              type: integer
                            session:
                              type: integer
                            voteNumber:
                              type: integer
                            congressYear:
                              type: integer
                              nullable: true
                            voteDate:
                              type: string
                              nullable: true
                            voteTime:
                              type: string
                              nullable: true
                            voteQuestion:
                              type: string
                              nullable: true
                            voteResult:
                              type: string
                              nullable: true
                            voteResultText:
                              type: string
                              nullable: true
                            voteTitle:
                              type: string
                              nullable: true
                            majorityRequirement:
                              type: string
                              nullable: true
                            documentName:
                              type: string
                              nullable: true
                            documentTitle:
                              type: string
                              nullable: true
                            totals:
                              type: object
                              properties:
                                yeas:
                                  type: integer
                                nays:
                                  type: integer
                                present:
                                  type: integer
                                absent:
                                  type: integer
                              required:
                              - yeas
                              - nays
                              - present
                              - absent
                              additionalProperties: false
                            totalsByParty:
                              type: object
                              additionalProperties:
                                type: object
                                properties:
                                  yea:
                                    type: integer
                                  nay:
                                    type: integer
                                  present:
                                    type: integer
                                  absent:
                                    type: integer
                                required:
                                - yea
                                - nay
                                - present
                                - absent
                                additionalProperties: false
                            sourceXmlUrl:
                              type: string
                              format: uri
                          required:
                          - congress
                          - session
                          - voteNumber
                          - congressYear
                          - voteDate
                          - voteTime
                          - voteQuestion
                          - voteResult
                          - voteResultText
                          - voteTitle
                          - majorityRequirement
                          - documentName
                          - documentTitle
                          - totals
                          - totalsByParty
                          - sourceXmlUrl
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              congress:
                                type: number
                                nullable: true
                              session:
                                type: number
                                nullable: true
                              result:
                                type: string
                                nullable: true
                              document:
                                type: string
                                nullable: true
                              since:
                                type: string
                                nullable: true
                              until:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                              offset:
                                type: integer
                            required:
                            - congress
                            - session
                            - result
                            - document
                            - since
                            - until
                            - limit
                            - offset
                            additionalProperties: false
                          nextOffset:
                            type: integer
                            nullable: true
                          previousOffset:
                            type: integer
                            nullable: true
                        required:
                        - query
                        - nextOffset
                        - previousOffset
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.senate-votes
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: congress
        in: query
        required: false
        description: Filter by Congress number. The 119th Congress = 2025-2026.
        schema:
          type: integer
          minimum: 100
          maximum: 200
      - name: session
        in: query
        required: false
        description: Filter by session (1 = odd year, 2 = even year of a Congress).
        schema:
          type: integer
      - name: result
        in: query
        required: false
        description: 'Filter by vote result (case-insensitive substring). Examples: "Agreed", "Rejected", "Cloture".'
        schema:
          type: string
          minLength: 2
          maxLength: 60
      - name: document
        in: query
        required: false
        description: 'Filter by document name substring (case-insensitive on document_name). Examples: "S. 5", "H.R. 4499", "H.R.".'
        schema:
          type: string
          minLength: 2
          maxLength: 40
      - name: since
        in: query
        required: false
        description: Earliest vote date (YYYY-MM-DD).
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: until
        in: query
        required: false
        description: Latest vote date (YYYY-MM-DD).
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: limit
        in: query
        required: false
        description: Max records (1-100). Default 25.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: offset
        in: query
        required: false
        description: Offset for pagination. Default 0.
        schema:
          type: integer
          minimum: 0
          maximum: 100000
          default: 0
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/uk-crime:
    get:
      tags:
      - gov
      summary: UK street-level crime around a location from the Home
      description: UK street-level crime around a location from the Home Office data.police.uk service. Give a latitude/longitude (and optional month YYYY-MM, defaults to the latest available — UK data lags ~2 months) and get the total crime count, a breakdown by category (anti-social behaviour, burglary, violent crime, vehicle crime, etc.), and recent individual records (category, approximate street, lat/lon, and outcome status). Free, Open Government Licence (commercial use permitted). Location-risk signal an LLM cannot recall — for property, insurance, and safety agents. Locations are anonymised to nearby map points by the Home Office.
      operationId: gov_uk-crime
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [one crime summary for the point]; total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            query:
                              type: object
                              properties:
                                lat:
                                  type: number
                                lng:
                                  type: number
                                month:
                                  type: string
                                  nullable: true
                              required:
                              - lat
                              - lng
                              - month
                              additionalProperties: false
                            total:
                              type: number
                            returned:
                              type: number
                            byCategory:
                              type: object
                              additionalProperties:
                                type: number
                            crimes:
                              type: array
                              items:
                                type: object
                                properties:
                                  category:
                                    type: string
                                    nullable: true
                                  month:
                                    type: string
                                    nullable: true
                                  street:
                                    type: string
                                    nullable: true
                                  latitude:
                                    type: number
                                    nullable: true
                                  longitude:
                                    type: number
                                    nullable: true
                                  outcome:
                                    type: string
                                    nullable: true
                                  outcomeDate:
                                    type: string
                                    nullable: true
                                required:
                                - category
                                - month
                                - street
                                - latitude
                                - longitude
                                - outcome
                                - outcomeDate
                                additionalProperties: false
                            source:
                              $ref: '#/components/schemas/Source'
                            note:
                              type: string
                          required:
                          - query
                          - total
                          - returned
                          - byCategory
                          - crimes
                          - source
                          - note
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.uk-crime
      x-2s-version: null
      x-2s-price:
        usd: 0.0027
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002700'
        protocols:
        - x402: {}
      parameters:
      - name: lat
        in: query
        required: true
        description: Latitude in decimal degrees (WGS84).
        schema:
          type: number
          minimum: -90
          maximum: 90
      - name: lng
        in: query
        required: true
        description: Longitude in decimal degrees (WGS84).
        schema:
          type: number
          minimum: -180
          maximum: 180
      - name: month
        in: query
        required: false
        description: Calendar month (1–12).
        schema:
          type: string
          pattern: ^\d{4}-\d{2}$
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/usajobs:
    get:
      tags:
      - gov
      summary: Search open US federal government job postings from the
      description: Search open US federal government job postings from the official USAJOBS API. Filter by keyword (title/skills), location (e.g. "Austin, Texas" or a state), and/or hiring organization; at least one is required. Returns the total matching count plus current openings with title, agency and department, location(s), salary range (USD) and pay interval, GS pay grade, work schedule, posting/close dates, and the official apply link. Keyless to the caller, public-domain (OPM). Live federal hiring data an LLM cannot recall — for job search, labor-market and workforce research.
      operationId: gov_usajobs
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = open federal job postings; total = full match count.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            positionId:
                              type: string
                              nullable: true
                            title:
                              type: string
                              nullable: true
                            organization:
                              type: string
                              nullable: true
                            department:
                              type: string
                              nullable: true
                            locations:
                              type: array
                              items:
                                type: string
                            salaryMinUSD:
                              type: number
                              nullable: true
                            salaryMaxUSD:
                              type: number
                              nullable: true
                            salaryInterval:
                              type: string
                              nullable: true
                            payGrade:
                              type: string
                              nullable: true
                            schedule:
                              type: string
                              nullable: true
                            postedDate:
                              type: string
                              nullable: true
                            closeDate:
                              type: string
                              nullable: true
                            applyUri:
                              type: string
                              nullable: true
                          required:
                          - positionId
                          - title
                          - organization
                          - department
                          - locations
                          - salaryMinUSD
                          - salaryMaxUSD
                          - salaryInterval
                          - payGrade
                          - schedule
                          - postedDate
                          - closeDate
                          - applyUri
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.usajobs
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - name: keyword
        in: query
        required: false
        description: Keyword.
        schema:
          type: string
          minLength: 1
          maxLength: 120
      - name: location
        in: query
        required: false
        description: Location.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: organization
        in: query
        required: false
        description: Organization.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 50
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/usaspending-awards:
    get:
      tags:
      - gov
      summary: Search federal awards (contracts, grants, loans, direct
      description: Search federal awards (contracts, grants, loans, direct payments) from USAspending.gov. Largest amount first within the date window. Each record includes award ID, recipient name, dollar amount, award type, awarding agency + sub-agency, start + end dates, description, and a permalink to the usaspending.gov detail page. Filter by recipient name, awarding agency name, recipient state, award type group, and date range. Backed by USAspending.gov's spending_by_award API; public-domain US government records.
      operationId: gov_usaspending-awards
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = federal awards (contracts, grants, loans, direct payments); total = null (USAspending does not report a match count on this search); meta.hasNext signals more pages, meta.query echoes the search.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            awardId:
                              type: string
                            recipientName:
                              type: string
                              nullable: true
                            amount:
                              type: number
                              nullable: true
                            awardType:
                              type: string
                              nullable: true
                            awardingAgency:
                              type: string
                              nullable: true
                            awardingSubAgency:
                              type: string
                              nullable: true
                            startDate:
                              type: string
                              nullable: true
                            endDate:
                              type: string
                              nullable: true
                            description:
                              type: string
                              nullable: true
                            usaspendingUrl:
                              type: string
                              format: uri
                              nullable: true
                          required:
                          - awardId
                          - recipientName
                          - amount
                          - awardType
                          - awardingAgency
                          - awardingSubAgency
                          - startDate
                          - endDate
                          - description
                          - usaspendingUrl
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              recipient:
                                type: string
                                nullable: true
                              agency:
                                type: string
                                nullable: true
                              recipientState:
                                type: string
                                nullable: true
                              awardType:
                                type: string
                              since:
                                type: string
                              until:
                                type: string
                              limit:
                                type: integer
                              page:
                                type: integer
                            required:
                            - recipient
                            - agency
                            - recipientState
                            - awardType
                            - since
                            - until
                            - limit
                            - page
                            additionalProperties: false
                          hasNext:
                            type: boolean
                        required:
                        - query
                        - hasNext
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.usaspending-awards
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: recipient
        in: query
        required: false
        description: 'Recipient (vendor/grantee) name substring. Examples: "Microsoft", "Lockheed Martin", "Stanford University".'
        schema:
          type: string
          minLength: 2
          maxLength: 120
      - name: agency
        in: query
        required: false
        description: 'Awarding top-tier agency name. Examples: "Department of Defense", "National Institutes of Health", "Department of Energy".'
        schema:
          type: string
          minLength: 2
          maxLength: 120
      - name: recipientState
        in: query
        required: false
        description: 2-letter US state of the recipient (e.g., "CA", "VA").
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
      - name: awardType
        in: query
        required: false
        description: Award type group. contracts = A/B/C/D; grants = 02/03/04/05; loans = 07/08; direct_payments = 06/10; other = 11. Default contracts.
        schema:
          type: string
          enum:
          - contracts
          - grants
          - loans
          - direct_payments
          - other
          default: contracts
      - name: since
        in: query
        required: false
        description: Earliest action date (YYYY-MM-DD). Default = 5 years ago.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: until
        in: query
        required: false
        description: Latest action date (YYYY-MM-DD). Default = today.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: limit
        in: query
        required: false
        description: Records per page (1-100). Default 25.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: page
        in: query
        required: false
        description: Page number (1-based). Default 1.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 1
      - $ref: '#/components/parameters/TrialMode'
  /api/gov/usgs-water:
    get:
      tags:
      - gov
      summary: Real-time water data from USGS NWIS stream / river /
      description: 'Real-time water data from USGS NWIS stream / river / groundwater gauges within a bounding box around lat/lon. Returns each site''s latest reading per requested variable: streamflow (00060, ft³/s), gage height (00065, ft), water temperature (00010, °C), precipitation (00045, in), and others. Each reading: site code + name, lat/lon, variable name + description + unit, value (or null if no data / sentinel), qualifier codes (e.g., ''P'' = provisional, ''A'' = approved), observed timestamp. Free public-domain data from waterservices.usgs.gov.'
      operationId: gov_usgs-water
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = latest USGS gauge readings (one per site+variable) in the bounding box; total = null (NWIS reports no match count); meta.query + meta.bbox echo the search window.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            siteCode:
                              type: string
                            siteName:
                              type: string
                            agencyCode:
                              type: string
                            latitude:
                              type: number
                            longitude:
                              type: number
                            variableCode:
                              type: string
                            variableName:
                              type: string
                            variableDescription:
                              type: string
                            unit:
                              type: string
                            value:
                              type: number
                              nullable: true
                            qualifiers:
                              type: array
                              items:
                                type: string
                            observedAt:
                              type: string
                              nullable: true
                            noDataValue:
                              type: number
                              nullable: true
                          required:
                          - siteCode
                          - siteName
                          - agencyCode
                          - latitude
                          - longitude
                          - variableCode
                          - variableName
                          - variableDescription
                          - unit
                          - value
                          - qualifiers
                          - observedAt
                          - noDataValue
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          query:
                            type: object
                            properties:
                              lat:
                                type: number
                              lon:
                                type: number
                              radiusDegrees:
                                type: number
                              variables:
                                type: array
                                items:
                                  type: string
                              limit:
                                type: integer
                            required:
                            - lat
                            - lon
                            - radiusDegrees
                            - variables
                            - limit
                            additionalProperties: false
                          bbox:
                            type: object
                            properties:
                              west:
                                type: number
                              south:
                                type: number
                              east:
                                type: number
                              north:
                                type: number
                            required:
                            - west
                            - south
                            - east
                            - north
                            additionalProperties: false
                        required:
                        - query
                        - bbox
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: gov.usgs-water
      x-2s-version: null
      x-2s-price:
        usd: 0.006
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.006000'
        protocols:
        - x402: {}
      parameters:
      - name: lat
        in: query
        required: true
        description: Center latitude (decimal degrees).
        schema:
          type: number
          minimum: -90
          maximum: 90
      - name: lon
        in: query
        required: true
        description: Center longitude (decimal degrees).
        schema:
          type: number
          minimum: -180
          maximum: 180
      - name: radius
        in: query
        required: false
        description: Half-side of bounding box, in decimal degrees. Default 0.5 (~35 mi).
        schema:
          type: number
          minimum: 0.05
          maximum: 2
          default: 0.5
      - name: variables
        in: query
        required: false
        description: Comma-separated USGS parameter codes (5-digit). Default "00060,00065,00010" (streamflow, gage height, water temp).
        schema:
          type: string
          pattern: ^(\d{5})(,\d{5})*$
      - name: limit
        in: query
        required: false
        description: Max readings to return (1-100). Default 25.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - $ref: '#/components/parameters/TrialMode'
components:
  schemas:
    Source:
      type: object
      description: 'Provenance of the data: upstream provider, source URL, and license.'
      properties:
        provider:
          type: string
          description: Upstream data provider.
        url:
          type: string
          description: Source URL or documentation link.
        license:
          type: string
          description: License / usage terms for the data.
    CallMeta:
      type: object
      description: Per-call meta envelope — endpoint id, cost, caller kind, settlement details.
    X402PaymentRequiredV2:
      type: object
      description: x402 v2 PaymentRequired envelope. Pick any entry from accepts[], sign for that rail, retry with the PAYMENT-SIGNATURE header.
      required:
      - x402Version
      - accepts
      properties:
        x402Version:
          type: integer
          const: 2
        error:
          type: string
          description: Human-readable reason payment is required.
        resource:
          type: string
          description: The resource URL being purchased.
        accepts:
          type: array
          description: Payment requirement options, one per supported network (Base USDC, Solana USDC).
          items:
            type: object
            required:
            - scheme
            - network
            - amount
            - asset
            - payTo
            - maxTimeoutSeconds
            properties:
              scheme:
                type: string
                enum:
                - exact
              network:
                type: string
                description: CAIP-2 network id, e.g. "eip155:8453" (Base) or "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp".
              amount:
                type: string
                description: Price in atomic asset units (USDC has 6 decimals).
              asset:
                type: string
                description: Asset contract address / mint.
              payTo:
                type: string
                description: Treasury address to pay.
              maxTimeoutSeconds:
                type: integer
              extra:
                type: object
                description: 'Rail-specific extras (EVM: EIP-712 domain name/version; Solana: feePayer).'
                additionalProperties: true
        extensions:
          type: object
          description: Optional discovery metadata (e.g. bazaar input/output schemas).
          additionalProperties: true
  responses:
    PaymentRequired:
      description: Payment required. Body contains the x402 PaymentRequirements envelope with a multi-network accepts array; the per-call price is in accepts[].amount (and on the operation as x-2s-price). Sign for whichever rail you hold USDC on (EIP-3009 for Base, partial SPL transfer for Solana) and retry with the PAYMENT-SIGNATURE header (X-PAYMENT also accepted for v1 clients).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/X402PaymentRequiredV2'
    UpstreamError:
      description: Upstream provider error.
    MethodNotAllowed:
      description: Method not allowed — see `Allow` header for the supported method.
    ServerError:
      description: Internal server error.
    BadRequest:
      description: Bad request — invalid parameters.
  parameters:
    TrialMode:
      name: trial
      in: query
      required: false
      description: 'Try before you buy. Set to 1 for one free real call per endpoint per hour — no wallet or payment needed — to verify the endpoint before paying. Equivalent to sending the "X-2s-Trial: 1" request header. Works on every endpoint.'
      schema:
        type: integer
        enum:
        - 1
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: 'x402 protocol v2: base64-encoded PaymentPayload. Call any paid endpoint without auth to receive a 402 with a multi-network PaymentRequirements envelope. Sign for either rail: EIP-3009 transferWithAuthorization (Base USDC) OR a partial SPL token transfer (Solana USDC). Retry with PAYMENT-SIGNATURE header. X-PAYMENT is also accepted for v1 buyer clients. See https://x402.org.'