Library of Congress treaty API

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 treaty API
  version: '3'
servers:
- url: /v3
security:
- ApiKeyAuth: []
tags:
- name: treaty
  description: Returns treaty data from the API
paths:
  /treaty:
    get:
      tags:
      - treaty
      summary: Returns a list of treaties sorted by date of last update.
      description: Returns a list of treaties sorted by date of last update.
      parameters:
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/fromDateTime'
      - $ref: '#/components/parameters/toDateTime'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Treaty'
            application/xml:
              schema:
                $ref: '#/components/schemas/Treaty'
        '400':
          description: Invalid status value
  /treaty/{congress}:
    get:
      tags:
      - treaty
      summary: Returns a list of treaties for the specified congress, sorted by date of last update.
      description: Returns a list of treaties for the specified congress, sorted by date of last update.
      parameters:
      - $ref: '#/components/parameters/congress'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/fromDateTime'
      - $ref: '#/components/parameters/toDateTime'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Treaty'
            application/xml:
              schema:
                $ref: '#/components/schemas/Treaty'
        '400':
          description: Invalid status value
  /treaty/{congress}/{treatyNumber}:
    get:
      tags:
      - treaty
      summary: Returns detailed information for a specified treaty.
      description: Returns detailed information for a specified treaty.
      parameters:
      - $ref: '#/components/parameters/congress'
      - $ref: '#/components/parameters/treatyNumber'
      - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreatyDetail'
            application/xml:
              schema:
                $ref: '#/components/schemas/TreatyDetail'
        '400':
          description: Invalid status value
  /treaty/{congress}/{treatyNumber}/{treatySuffix}:
    get:
      tags:
      - treaty
      summary: Returns detailed information for a specified partitioned treaty.
      description: Returns detailed information for a specified partitioned treaty.
      parameters:
      - $ref: '#/components/parameters/congress'
      - $ref: '#/components/parameters/treatyNumber'
      - $ref: '#/components/parameters/treatySuffix'
      - $ref: '#/components/parameters/format'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreatyDetail'
            application/xml:
              schema:
                $ref: '#/components/schemas/TreatyDetail'
        '400':
          description: Invalid status value
  /treaty/{congress}/{treatyNumber}/actions:
    get:
      tags:
      - treaty
      summary: Returns the list of actions on a specified treaty.
      description: Returns the list of actions on a specified treaty.
      parameters:
      - $ref: '#/components/parameters/congress'
      - $ref: '#/components/parameters/treatyNumber'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreatyActions'
            application/xml:
              schema:
                $ref: '#/components/schemas/TreatyActions'
        '400':
          description: Invalid status value
  /treaty/{congress}/{treatyNumber}/{treatySuffix}/actions:
    get:
      tags:
      - treaty
      summary: Returns the list of actions on a specified partitioned treaty.
      description: Returns the list of actions on a specified partitioned treaty.
      parameters:
      - $ref: '#/components/parameters/congress'
      - $ref: '#/components/parameters/treatyNumber'
      - $ref: '#/components/parameters/treatySuffix'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreatyActions'
            application/xml:
              schema:
                $ref: '#/components/schemas/TreatyActions'
        '400':
          description: Invalid status value
  /treaty/{congress}/{treatyNumber}/committees:
    get:
      tags:
      - treaty
      summary: Returns the list of committees associated with a specified treaty.
      description: Returns the list of committees associated with a specified treaty.
      parameters:
      - $ref: '#/components/parameters/congress'
      - $ref: '#/components/parameters/treatyNumber'
      - $ref: '#/components/parameters/format'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TreatyCommittees'
            application/xml:
              schema:
                $ref: '#/components/schemas/TreatyCommittees'
        '400':
          description: Invalid status value
components:
  parameters:
    treatyNumber:
      name: treatyNumber
      in: path
      description: The treaty’s assigned number. For example, the value can be 13.
      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
    fromDateTime:
      name: fromDateTime
      in: query
      description: 'The starting timestamp to filter by update date. Use format: YYYY-MM-DDT00:00:00Z.'
      required: false
      schema:
        type: string
    toDateTime:
      name: toDateTime
      in: query
      description: 'The ending timestamp to filter by update date. Use format: YYYY-MM-DDT00:00:00Z.'
      required: false
      schema:
        type: string
    treatySuffix:
      name: treatySuffix
      in: path
      description: The treaty’s partition letter value. For example, the value can be A.
      required: true
      schema:
        type: string
    congress:
      name: congress
      in: path
      description: The congress number. For example, can be 117.
      required: true
      schema:
        type: integer
        format: int32
    limit:
      name: limit
      in: query
      description: The number of records returned. The maximum limit is 250.
      required: false
      schema:
        type: integer
  schemas:
    Treaty:
      type: object
      properties:
        treaties:
          type: array
          items:
            $ref: '#/components/schemas/treaty'
    treatyCommittee:
      type: object
      properties:
        activities:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
                example: '1965-10-19T04:00:00Z'
              name:
                type: string
                example: Reported By
        chamber:
          type: string
          example: Senate
        name:
          type: string
          example: Foreign Relations Committee
        subcommittees:
          type: array
        systemCode:
          type: string
          example: ssfr00
        type:
          type: string
          example: Standing
        url:
          type: string
          example: https://api.congress.gov/v3/committee/senate/ssfr00?format=json
    TreatyCommittees:
      type: object
      properties:
        treatyCommittees:
          type: array
          items:
            $ref: '#/components/schemas/treatyCommittee'
    treaty:
      type: object
      properties:
        congressReceived:
          type: integer
          example: 89
        congressConsidered:
          type: integer
          example: 89
        number:
          type: integer
          example: 3
        parts:
          type: object
        suffix:
          type: string
          example: ''
        topic:
          type: string
          example: Dispute Settlement and Arbitration
        transmittedDate:
          type: string
          format: date-time
          example: '1965-05-17T00:00:00Z'
        updateDate:
          type: string
          format: date-time
          example: '2024-12-11T00:18:16Z'
        url:
          type: string
          format: url
          example: https://api.congress.gov/v3/treaty/89/3?format=json
    TreatyDetail:
      type: object
      properties:
        treaty:
          type: object
          properties:
            actions:
              type: object
              properties:
                count:
                  type: integer
                  example: 3
                url:
                  type: string
                  format: url
                  example: https://api.congress.gov/v3/treaty/89/7/actions?format=json
            congressConsidered:
              type: integer
              example: 89
            congressReceived:
              type: integer
              example: 89
            countriesParties:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: Belgium
            inForceDate:
              type: string
              example: ''
            indexTerms:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: ENGLISH
            number:
              type: integer
              example: 7
            oldNumber:
              type: string
              example: G. 89-1
            oldNumberDisplayName:
              type: string
              example: Ex. G, 89th Congress, 1st Session
            parts:
              type: object
            relatedDocs:
              type: array
            resolutionText:
              type: string
              example: ''
            suffix:
              type: string
              example: ''
            titles:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                    example: PROTOCOL MODIFYING CONVENTION WITH BELGIUM FOR THE AVOIDANCE OF DOUBLE TAXATION
                  titleType:
                    type: string
                    example: Treaty - Short Title
            topic:
              type: string
              example: Taxation
            transmitted:
              type: string
              format: date-time
              example: '1965-08-05T00:00:00Z'
            updateDate:
              type: string
              format: date-time
              example: '2022-02-26T16:25:25Z'
    TreatyActions:
      type: object
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/treatyAction'
    senatecommittee:
      type: object
      properties:
        name:
          type: string
          example: Armed Services Committee
        systemCode:
          type: string
          example: ssas00
        url:
          type: string
          format: url
          example: https://api.congress.gov/v3/committee/senate/ssas00?format=json
    treatyAction:
      type: object
      properties:
        actionCode:
          type: string
          example: S05291
        actionDate:
          type: string
          format: date
          example: '2022-08-03'
        committee:
          $ref: '#/components/schemas/senatecommittee'
        text:
          type: string
          example: 'Resolution of advice and consent to ratification agreed to as amended in Senate by Yea-Nay Vote. 95 - 1. Record Vote Number: 282.'
        type:
          type: string
          example: Floor
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key