openapi: 3.0.3
info:
  title: Congress.gov Bills API
  description: The Congress.gov API provides programmatic access to congressional data from the Library of Congress. It is a REST API offering machine-readable data covering bills, amendments, congressional records, committees, members, nominations, treaties, and other collections. An API key is required for access. Version 3 is the current stable release.
  version: v3
  contact:
    url: https://www.loc.gov/apis/additional-apis/congress-dot-gov-api/
  license:
    name: US Government Work
    url: https://www.usa.gov/government-works
servers:
- url: https://api.congress.gov/v3
  description: Congress.gov API v3 Production Server
security:
- ApiKeyQuery: []
tags:
- name: Bills
  description: Legislative bills and resolutions
paths:
  /bill:
    get:
      operationId: listBills
      summary: List Bills
      description: Returns a paginated list of congressional bills across all congresses.
      tags:
      - Bills
      parameters:
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/formatParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: fromDateTime
        in: query
        description: Start date/time filter for bill updates (ISO 8601)
        required: false
        schema:
          type: string
          format: date-time
      - name: toDateTime
        in: query
        description: End date/time filter for bill updates (ISO 8601)
        required: false
        schema:
          type: string
          format: date-time
      - name: sort
        in: query
        description: Sort order for results
        required: false
        schema:
          type: string
          enum:
          - updateDate+asc
          - updateDate+desc
          default: updateDate+desc
      responses:
        '200':
          description: A paginated list of bills
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillListResponse'
        '400':
          description: Bad request
        '403':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
  /bill/{congress}:
    get:
      operationId: listBillsByCongress
      summary: List Bills by Congress
      description: Returns bills introduced in a specific Congress.
      tags:
      - Bills
      parameters:
      - $ref: '#/components/parameters/congressParam'
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/formatParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: billType
        in: query
        description: Filter by bill type
        required: false
        schema:
          type: string
          enum:
          - hr
          - s
          - hjres
          - sjres
          - hconres
          - sconres
          - hres
          - sres
      responses:
        '200':
          description: A paginated list of bills for the specified Congress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillListResponse'
        '404':
          description: Congress not found
  /bill/{congress}/{type}:
    get:
      operationId: listBillsByType
      summary: List Bills by Congress and Type
      description: Returns bills of a specific type introduced in a specific Congress.
      tags:
      - Bills
      parameters:
      - $ref: '#/components/parameters/congressParam'
      - name: type
        in: path
        description: Bill type (e.g., hr, s, hjres)
        required: true
        schema:
          type: string
          enum:
          - hr
          - s
          - hjres
          - sjres
          - hconres
          - sconres
          - hres
          - sres
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/formatParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: A list of bills of the specified type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillListResponse'
  /bill/{congress}/{type}/{number}:
    get:
      operationId: getBill
      summary: Get Bill Details
      description: Returns detailed information for a specific bill.
      tags:
      - Bills
      parameters:
      - $ref: '#/components/parameters/congressParam'
      - name: type
        in: path
        description: Bill type (e.g., hr, s)
        required: true
        schema:
          type: string
      - name: number
        in: path
        description: Bill number
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/formatParam'
      responses:
        '200':
          description: Detailed bill information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillDetailResponse'
        '404':
          description: Bill not found
  /bill/{congress}/{type}/{number}/actions:
    get:
      operationId: getBillActions
      summary: Get Bill Actions
      description: Returns the legislative actions taken on a specific bill.
      tags:
      - Bills
      parameters:
      - $ref: '#/components/parameters/congressParam'
      - name: type
        in: path
        description: Bill type
        required: true
        schema:
          type: string
      - name: number
        in: path
        description: Bill number
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/formatParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: List of actions on the bill
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillActionsResponse'
  /bill/{congress}/{type}/{number}/cosponsors:
    get:
      operationId: getBillCosponsors
      summary: Get Bill Cosponsors
      description: Returns the cosponsors of a specific bill.
      tags:
      - Bills
      parameters:
      - $ref: '#/components/parameters/congressParam'
      - name: type
        in: path
        required: true
        schema:
          type: string
      - name: number
        in: path
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/formatParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: List of cosponsors
          content:
            application/json:
              schema:
                type: object
  /bill/{congress}/{type}/{number}/summaries:
    get:
      operationId: getBillSummaries
      summary: Get Bill Summaries
      description: Returns summaries for a specific bill.
      tags:
      - Bills
      parameters:
      - $ref: '#/components/parameters/congressParam'
      - name: type
        in: path
        required: true
        schema:
          type: string
      - name: number
        in: path
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/formatParam'
      responses:
        '200':
          description: List of summaries for the bill
          content:
            application/json:
              schema:
                type: object
  /bill/{congress}/{type}/{number}/text:
    get:
      operationId: getBillText
      summary: Get Bill Text Versions
      description: Returns the available text versions for a specific bill.
      tags:
      - Bills
      parameters:
      - $ref: '#/components/parameters/congressParam'
      - name: type
        in: path
        required: true
        schema:
          type: string
      - name: number
        in: path
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/apiKeyParam'
      - $ref: '#/components/parameters/formatParam'
      responses:
        '200':
          description: Available text versions of the bill
          content:
            application/json:
              schema:
                type: object
components:
  schemas:
    BillDetailResponse:
      type: object
      properties:
        bill:
          type: object
          properties:
            congress:
              type: integer
            type:
              type: string
            number:
              type: string
            title:
              type: string
            introducedDate:
              type: string
              format: date
            sponsors:
              type: array
              items:
                type: object
            cosponsors:
              type: object
            committees:
              type: object
            actions:
              type: object
            subjects:
              type: object
            summaries:
              type: object
            textVersions:
              type: object
        request:
          $ref: '#/components/schemas/RequestInfo'
    RequestInfo:
      type: object
      properties:
        billNumber:
          type: string
        billType:
          type: string
        congress:
          type: string
        contentType:
          type: string
        format:
          type: string
    BillSummary:
      type: object
      properties:
        congress:
          type: integer
          description: Congress number the bill was introduced in
        type:
          type: string
          description: Bill type code (hr, s, hjres, etc.)
        number:
          type: string
          description: Bill number
        title:
          type: string
          description: Official title of the bill
        originChamber:
          type: string
          description: Chamber where the bill originated (House or Senate)
        originChamberCode:
          type: string
          description: Chamber code (H or S)
        introducedDate:
          type: string
          format: date
          description: Date the bill was introduced
        latestAction:
          type: object
          properties:
            actionDate:
              type: string
              format: date
            text:
              type: string
        updateDate:
          type: string
          format: date-time
        url:
          type: string
          description: API URL for the bill details
    BillListResponse:
      type: object
      properties:
        bills:
          type: array
          items:
            $ref: '#/components/schemas/BillSummary'
        pagination:
          $ref: '#/components/schemas/Pagination'
        request:
          $ref: '#/components/schemas/RequestInfo'
    BillActionsResponse:
      type: object
      properties:
        actions:
          type: array
          items:
            type: object
            properties:
              actionDate:
                type: string
                format: date
              text:
                type: string
              type:
                type: string
              actionCode:
                type: string
              committees:
                type: array
                items:
                  type: object
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      properties:
        count:
          type: integer
          description: Total number of records matching the query
        next:
          type: string
          description: URL for the next page of results
        prev:
          type: string
          description: URL for the previous page of results
  parameters:
    congressParam:
      name: congress
      in: path
      description: The Congress number (e.g., 118 for the 118th Congress)
      required: true
      schema:
        type: integer
        minimum: 1
    limitParam:
      name: limit
      in: query
      description: Number of results to return per request (max 250)
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 250
        default: 20
    formatParam:
      name: format
      in: query
      description: Response format
      required: false
      schema:
        type: string
        enum:
        - json
        - xml
        default: json
    offsetParam:
      name: offset
      in: query
      description: Starting record number for pagination
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    apiKeyParam:
      name: api_key
      in: query
      description: API key for authentication
      required: false
      schema:
        type: string
  responses:
    Unauthorized:
      description: API key missing or invalid
    RateLimitExceeded:
      description: Rate limit exceeded (5000 requests per hour)
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key required for all requests. Register at https://api.congress.gov/sign-up to obtain a key.