openapi: 3.0.3
info:
  description: 'Congress.gov shares its application programming interface (API) with the public to ingest the Congressional data. <a href="sign-up/" target="_blank">Sign up for an API key</a> from api.data.gov that you can use to access web services provided by Congress.gov. To learn more, view our <a href="https://github.com/LibraryOfCongress/api.congress.gov/" target="_blank">GitHub repository</a>.

    '
  title: Congress.gov amendments hearing API
  version: '3'
servers:
- url: /v3
security:
- ApiKeyAuth: []
tags:
- name: hearing
  description: Returns hearing data from the API
paths:
  /hearing:
    get:
      tags:
      - hearing
      summary: Returns a list of hearings.
      description: Returns a list of hearings.
      parameters:
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hearings'
            application/xml:
              schema:
                $ref: '#/components/schemas/Hearings'
        '400':
          description: Invalid status value
  /hearing/{congress}:
    get:
      tags:
      - hearing
      summary: Returns a list of hearings filtered by specified congress.
      description: Returns a list of hearings filtered by specified congress.
      parameters:
      - $ref: '#/components/parameters/congress'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hearings'
            application/xml:
              schema:
                $ref: '#/components/schemas/Hearings'
        '400':
          description: Invalid status value
  /hearing/{congress}/{chamber}:
    get:
      tags:
      - hearing
      summary: Returns a list of hearings filtered by specified congress and chamber.
      description: Returns a list of hearings filtered by specified congress and chamber.
      parameters:
      - $ref: '#/components/parameters/congress'
      - $ref: '#/components/parameters/chamber'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hearings'
            application/xml:
              schema:
                $ref: '#/components/schemas/Hearings'
        '400':
          description: Invalid status value
  /hearing/{congress}/{chamber}/{jacketNumber}:
    get:
      tags:
      - hearing
      summary: Returns detailed information for a specified hearing.
      description: Returns detailed information for a specified hearing.
      parameters:
      - $ref: '#/components/parameters/congress'
      - $ref: '#/components/parameters/chamber'
      - $ref: '#/components/parameters/jacketNumber'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HearingDetail'
            application/xml:
              schema:
                $ref: '#/components/schemas/HearingDetail'
        '400':
          description: Invalid status value
components:
  schemas:
    Hearings:
      type: array
      items:
        $ref: '#/components/schemas/hearing'
    hearing:
      type: object
      properties:
        chamber:
          type: string
          example: House
        congress:
          type: integer
          example: 117
        jacketNumber:
          type: integer
          example: 48144
        updateDate:
          type: string
          format: date-time
          example: '2022-08-01 21:19:33+00:00'
        url:
          type: string
          format: url
          example: https://api.congress.gov/v3/hearing/117/house/41365?format=json
    formats:
      type: object
      properties:
        type:
          type: string
          example: Formatted Text
        url:
          type: string
          format: url
          example: https://www.congress.gov/117/bills/hr3076/BILLS-117hr3076enr.htm
    HearingDetail:
      type: object
      properties:
        associatedMeeting:
          $ref: '#/components/schemas/associatedMeeting'
        chamber:
          type: string
          example: House
        citation:
          type: string
          example: H.Hrg.118
        committees:
          type: array
          items:
            $ref: '#/components/schemas/subcommittees'
        congress:
          type: integer
          example: 118
        dates:
          type: array
          items:
            type: string
            format: date
            example: '2022-08-01'
        formats:
          type: array
          items:
            $ref: '#/components/schemas/formats'
        jacketNumber:
          type: integer
          example: 50896
        libraryOfCongressidentifier:
          type: string
          example: LC70380
        title:
          type: string
          example: 'FEDERAL PANDEMIC SPENDING: A PRESCRIPTION FOR WASTE, FRAUD AND ABUSE'
        updateDate:
          type: string
          format: date-time
          example: '2025-11-04T03:21:12Z'
    subcommittees:
      type: object
      properties:
        name:
          type: string
          example: Investigations and Oversight Subcommittee
        systemCode:
          type: string
          example: hspw01
        url:
          type: string
          format: url
          example: https://api.congress.gov/v3/committee/house/hspw01?format=json
    associatedMeeting:
      type: object
      properties:
        eventId:
          type: string
          example: '115266'
        url:
          type: string
          format: url
          example: https://api.congress.gov/v3/committee-meeting/117/house/115266?format=json
  parameters:
    congress:
      name: congress
      in: path
      description: The congress number. For example, can be 117.
      required: true
      schema:
        type: integer
        format: int32
    jacketNumber:
      name: jacketNumber
      in: path
      description: The jacket number for the print. For example, the value can be 48144.
      required: true
      schema:
        type: integer
    offset:
      name: offset
      in: query
      description: The starting record returned. 0 is the first record.
      required: false
      schema:
        type: integer
    format:
      name: format
      in: query
      description: The data format. Value can be xml or json.
      required: false
      schema:
        type: string
        default: xml
        enum:
        - xml
        - json
    chamber:
      name: chamber
      in: path
      description: The chamber name. Value can be house, senate, or joint.
      required: true
      schema:
        type: string
        enum:
        - house
        - senate
        - joint
    limit:
      name: limit
      in: query
      description: The number of records returned. The maximum limit is 250.
      required: false
      schema:
        type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key