swagger: '2.0'
info:
  title: eCFR API Documentation Admin Service Versioner Service API
  description: Access eCFR metadata through JSON
host: www.ecfr.gov
tags:
- name: Versioner Service
  description: Access CFR content and structure files through JSON and XML
paths:
  /api/versioner/v1/ancestry/{date}/title-{title}.json:
    get:
      summary: Ancestors route returns all ancestors (including self) from a given level through the top title node.
      description: "The Ancestry service can be used to determine the complete ancestry to a leaf node at a specific point in time.\n### Example\nThe complete hierarchy for **2 CFR 1532.137** is\n```\nTitle 2\n  Subtitle B\n    Chapter XV\n      Part 1532\n        Subpart A\n          Section 1532.137\n```\nTo retrieve this complete hierarchy you can use the ancestry endpoint and provide a Title, Part and Section (you can provide additional layers of the hierarchy) to retrieve a full ancestry.\nSee sample json responses below.\n"
      parameters:
      - name: date
        description: YYYY-MM-DD
        in: path
        type: string
        format: date
        required: 'true'
      - name: title
        description: 'Title Number: ''1'', ''2'', ''50'', etc'
        in: path
        type: string
        required: 'true'
      - name: subtitle
        description: Uppercase letter. 'A', 'B', 'C'
        in: query
        type: string
      - name: chapter
        description: Roman Numerals and digits 0-9. 'I', 'X', '1'
        in: query
        type: string
      - name: subchapter
        description: A SUBCHAPTER REQUIRES A CHAPTER. Uppercase letters with optional underscore or dash. 'A', 'B', 'I'
        in: query
        type: string
      - name: part
        description: Uppercase letters with optional underscore or dash. 'A', 'B', 'I'
        in: query
        type: string
      - name: subpart
        description: A SUBPART REQUIRES A PART. Generally an uppercase letter. 'A', 'B', 'C'
        in: query
        type: string
      - name: section
        description: A SECTION REQUIRES A PART. Generally a number followed by a dot and another number. '121.1', '13.4', '1.9'
        in: query
        type: string
      - name: appendix
        description: AN APPENDIX REQUIRES A SUBTITLE, CHAPTER or PART. Multiple formats. 'A', 'III', 'App. A'
        in: query
        type: string
      responses:
        '200':
          description: "```json\n  [\n    {\n        \"type\": \"title\",\n        \"label\": \"Title 2 - Federal Financial Assistance\",\n        \"label_level\": \"Title 2\",\n        \"label_description\": \"Federal Financial Assistance\",\n        \"identifier\": \"2\"\n    },\n    {\n        \"type\": \"subtitle\",\n        \"label\": \"Subtitle B - Federal Agency Regulations for Grants and Agreements\",\n        \"label_level\": \"Subtitle B\",\n        \"label_description\": \"Federal Agency Regulations for Grants and Agreements\",\n        \"identifier\": \"B\",\n        \"reserved\": false,\n        \"section_range\": \"§§ 300.1 – 5900.101\"\n    },\n    {\n        \"type\": \"chapter\",\n        \"label\": \"Chapter XV - Environmental Protection Agency\",\n        \"label_level\": \"Chapter XV\",\n        \"label_description\": \"Environmental Protection Agency\",\n        \"identifier\": \"XV\",\n        \"reserved\": false,\n        \"section_range\": \"§§ 1500.1 – 1536.505\"\n    },\n    {\n        \"type\": \"part\",\n        \"label\": \"Part 1532 - Nonprocurement Debarment and Suspension\",\n        \"label_level\": \"Part 1532\",\n        \"label_description\": \"Nonprocurement Debarment and Suspension\",\n        \"identifier\": \"1532\",\n        \"reserved\": false,\n        \"section_range\": \"§§ 1532.10 – 1532.1600\"\n    },\n    {\n        \"type\": \"subpart\",\n        \"label\": \"Subpart A - General\",\n        \"label_level\": \"Subpart A\",\n        \"label_description\": \"General\",\n        \"identifier\": \"A\",\n        \"reserved\": false,\n        \"section_range\": \"§ 1532.137\"\n    },\n    {\n        \"type\": \"section\",\n        \"label\": \"§ 1532.137 Who in the EPA may grant an exception to let an excluded person participate in a covered transaction?\",\n        \"label_level\": \"§ 1532.137\",\n        \"label_description\": \"Who in the EPA may grant an exception to let an excluded person participate in a covered transaction?\",\n        \"identifier\": \"1532.137\",\n        \"reserved\": false\n    }\n  ]\n```\n"
        '404':
          description: null // Invalid input or missing some hierarchy
      tags:
      - Versioner Service
  /api/versioner/v1/full/{date}/title-{title}.xml:
    get:
      description: 'The title source route can be used to retrieve the source xml for a complete title or subset. The subset of xml is determined by the lowest leaf node given. For example, if you request Title 1, Chapter I, Part 1, you''ll receive the XML only for Part 1 and its children.

        If you request a section you''ll receive the section XML inside its parent Part as well as relevant non-section sibling nodes (Auth, Source, etc).

        The largest title source xml files can be dozens of megabytes.


        [GPO eCFR XML User guide](https://github.com/usgpo/bulk-data/blob/master/ECFR-XML-User-Guide.md)

        '
      summary: Source XML for a title or subset of a title. Requests can be for entire titles or part level and below.  Downloadable XML document is returned for title requests.  Processed XML is returned if part, subpart, section, or appendix is requested.
      parameters:
      - name: date
        description: YYYY-MM-DD
        in: path
        type: string
        format: date
        required: 'true'
      - name: title
        description: 'Title Number: ''1'', ''2'', ''50'', etc'
        in: path
        type: string
        required: 'true'
      - name: subtitle
        description: Uppercase letter. 'A', 'B', 'C'
        in: query
        type: string
      - name: chapter
        description: Roman Numerals and digits 0-9. 'I', 'X', '1'
        in: query
        type: string
      - name: subchapter
        description: A SUBCHAPTER REQUIRES A CHAPTER. Uppercase letters with optional underscore or dash. 'A', 'B', 'I'
        in: query
        type: string
      - name: part
        description: Uppercase letters with optional underscore or dash. 'A', 'B', 'I'
        in: query
        type: string
      - name: subpart
        description: A SUBPART REQUIRES A PART. Generally an uppercase letter. 'A', 'B', 'C'
        in: query
        type: string
      - name: section
        description: A SECTION REQUIRES A PART. Generally a number followed by a dot and another number. '121.1', '13.4', '1.9'
        in: query
        type: string
      - name: appendix
        description: AN APPENDIX REQUIRES A SUBTITLE, CHAPTER or PART. Multiple formats. 'A', 'III', 'App. A'
        in: query
        type: string
      produces:
      - application/xml
      responses:
        '200':
          description: A downloadable Title XML document for entire Title requests or processed XML for part level and below requests.
          headers:
            Content-Type: application/xml
        '400':
          description: 'Bad parameter: invalid date.'
        '404':
          description: No matching content found.
      tags:
      - Versioner Service
  /api/versioner/v1/structure/{date}/title-{title}.json:
    get:
      summary: Structure JSON for a title
      parameters:
      - name: date
        description: YYYY-MM-DD
        in: path
        type: string
        format: date
        required: 'true'
      - name: title
        description: 'Title Number: ''1'', ''2'', ''50'', etc'
        in: path
        type: string
        required: 'true'
      description: The structure JSON endpoint returns the complete structure of a title back as json. This format does not include the content of the title but does include all structure and content nodes as well as their meta data including their type, label, description, identifier and children.
      responses:
        '200':
          description: "```json\n  {\n    \"type\": \"title\",\n    \"label\": \"Title 3 - The President\",\n    \"label_level\": \"Title 3\",\n    \"label_description\": \"The President\",\n    \"identifier\": \"3\",\n    \"children\": [\n      {\n        \"type\": \"chapter\",\n        \"label\": \"Chapter I - Executive Office of the President\",\n        \"label_level\": \"Chapter I\",\n        \"label_description\": \"Executive Office of the President\",\n        \"identifier\": \"I\",\n        \"reserved\": false,\n        \"children\": [\n          {\n            \"type\": \"part\",\n            \"label\": \"Part 100 - Standards of Conduct\",\n            \"label_level\": \"Part 100\",\n            \"label_description\": \"Standards of Conduct\",\n            \"identifier\": \"100\",\n            \"reserved\": false,\n            \"children\": [\n              {\n                \"type\": \"section\",\n                \"label\": \"§ 100.1 Ethical conduct standards and financial disclosure regulations.\",\n                \"label_level\": \"§ 100.1\",\n                \"label_description\": \"Ethical conduct standards and financial disclosure regulations.\",\n                \"identifier\": \"100.1\",\n                \"reserved\": false\n              }\n            ],\n            \"section_range\": \"§ 100.1\"\n          },\n        ],\n      }\n    ]\n  }\n```|\n"
        '404':
          description: Invalid input.
      tags:
      - Versioner Service
  /api/versioner/v1/titles.json:
    get:
      summary: Summary information about each title
      description: The Title service can be used to determine the status of each individual title and of the overall status of title imports and reprocessings. It returns an array of all titles containing a hash for each with the name of the title, the latest amended date, latest issue date, up-to-date date, reserved status, and if applicable, processing in progress status. The meta data returned indicates the latest issue date and whether titles are currently being reprocessed.
      parameters: []
      responses:
        '200':
          description: "```json\n  {\n    \"titles\": [\n      {\n        \"number\": 1,\n        \"name\": \"General Provisions\",\n        \"latest_amended_on\": \"2022-05-04\",\n        \"latest_issue_date\": \"2022-05-04\",\n        \"up_to_date_as_of\": \"2022-07-28\",\n        \"reserved\": false\n      },\n      {\n        \"number\": 2,\n        \"name\": \"Federal Financial Assistance\",\n        \"latest_amended_on\": \"2022-05-19\",\n        \"latest_issue_date\": \"2022-06-03\",\n        \"up_to_date_as_of\": \"2022-07-28\",\n        \"reserved\": false,\n        \"processing_in_progress\": true\n      },\n      {\n        \"number\": 3,\n        \"name\": \"The President\",\n        \"latest_amended_on\": \"2015-03-17\",\n        \"latest_issue_date\": \"2019-06-27\",\n        \"up_to_date_as_of\": \"2022-07-28\",\n        \"reserved\": false\n      },\n      ...\n    ],\n    meta\": {\n      \"date\": \"2022-07-29\",\n      \"import_in_progress\": true\n    }\n  }\n```\n"
      tags:
      - Versioner Service
  /api/versioner/v1/versions/title-{title}.json:
    get:
      summary: Returns an array of all sections and appendices inside a title.
      description: 'Returns the content versions meeting the specified criteria. Each content object includes its identifier, parent hierarchy, last amendment date and issue date it was last updated. Queries return content versions `on` an issue date, or before or on a specific issue date `lte` or on or after `gte` a specific issue date. At least one issue date parameter must be provided. The `gte` and `lte` parameters may be combined. Use of the `on` parameter precludes use of `gte` or `lte`. Responses are paginated at 1000 records per page. In the response, the `date` field is identical to `amendment_date` and is deprecated.

        <br>

        A response of `400 Bad Request` indicates that your request could not be processed. If possible the response will include a message indicating the problem.

        <br>

        A response of `503 Service Unavailable` indicates that the title is currently unavailable, typlically because it is currently being processed. The value of the `Retry-After` header suggests a number of seconds to wait before retrying the request.

        '
      parameters:
      - name: title
        description: 'Title Number: ''1'', ''2'', ''50'', etc'
        in: path
        type: string
        required: 'true'
      - name: issue_date[on]
        in: query
        type: string
        format: date
        description: One issue date is required. Select content added on the supplied issue date
      - name: issue_date[lte]
        in: query
        type: string
        format: date
        description: One issue date is required. Select content added on or before the supplied issue date
      - name: issue_date[gte]
        in: query
        type: string
        format: date
        description: One issue date is required. Select content added on or after the supplied issue date
      - name: page
        description: Page number for paginated content version responses. Upto 1000 results are returned at a time.
        in: query
        type: integer
      - name: subtitle
        description: Uppercase letter. 'A', 'B', 'C'
        in: query
        type: string
      - name: chapter
        description: Roman Numerals and digits 0-9. 'I', 'X', '1'
        in: query
        type: string
      - name: subchapter
        description: A SUBCHAPTER REQUIRES A CHAPTER. Uppercase letters with optional underscore or dash. 'A', 'B', 'I'
        in: query
        type: string
      - name: part
        description: Uppercase letters with optional underscore or dash. 'A', 'B', 'I'
        in: query
        type: string
      - name: subpart
        description: A SUBPART REQUIRES A PART. Generally an uppercase letter. 'A', 'B', 'C'
        in: query
        type: string
      - name: section
        description: A SECTION REQUIRES A PART. Generally a number followed by a dot and another number. '121.1', '13.4', '1.9'
        in: query
        type: string
      - name: appendix
        description: AN APPENDIX REQUIRES A SUBTITLE, CHAPTER or PART. Multiple formats. 'A', 'III', 'App. A'
        in: query
        type: string
      x-required-one-of:
      - - issue_date[on]
        - issue_date[lte]
        - issue_date[gte]
      responses:
        '200':
          description: "```json\n{\n  \"content_versions\": [\n    {\n      \"date\": \"2017-01-19\",\n      \"amendment_date\": \"2017-01-19\",\n      \"issue_date\": \"2017-01-19\",\n      \"identifier\": \"3474.20\",\n      \"name\": \"§ 3474.20   xxx\",\n      \"part\": \"3474\",\n      \"substantive\": true,\n      \"removed\": false,\n      \"subpart\": null,\n      \"title\": \"2\",\n      \"type\": \"section\"\n    },\n    {\n      \"date\": \"2017-03-21\",\n      \"amendment_date\": \"2017-03-21\",\n      \"issue_date\": \"2017-03-21\",\n      \"identifier\": \"3474.20\",\n      \"name\": \"§ 3474.20   xxx\",\n      \"part\": \"3474\",\n      \"substantive\": true,\n      \"removed\": false,\n      \"subpart\": null,\n      \"title\": \"2\",\n      \"type\": \"section\"\n    },\n    {\n      \"date\": \"2017-05-17\",\n      \"amendment_date\": \"2017-05-17\",\n      \"issue_date\": \"2017-05-17\",\n      \"identifier\": \"200.110\",\n      \"name\": \"§ 200.110   Effective/applicability date.\",\n      \"part\": \"200\",\n      \"substantive\": true,\n      \"removed\": false,\n      \"subpart\": \"B\",\n      \"title\": \"2\",\n      \"type\": \"section\"\n    },\n    {\n      \"date\": \"2017-05-22\",\n      \"amendment_date\": \"2017-05-22\",\n      \"issue_date\": \"2017-05-22\",\n      \"identifier\": \"3474.20\",\n      \"name\": \"§ 3474.20   Open licensing requirement for competitive grant programs.\",\n      \"part\": \"3474\",\n      \"substantive\": true,\n      \"removed\": false,\n      \"subpart\": null,\n      \"title\": \"2\",\n      \"type\": \"section\"\n    }\n  ],\n  \"meta\": {\n    \"title\": \"2\",\n    \"result_count\": \"4\",\n    \"issue_date\": {\n      \"lte\": \"2018-01-01\",\n      \"gte\": \"2017-01-01\"\n    },\n    \"latest_amendment_date\": \"2017-05-22\",\n    \"latest_issue_date\": \"2017-05-22\"\n  }\n}\n```\n"
        '400':
          description: "```json\n{\n  \"error\": \"Bad date: '2025-16-01'\"\n}\n\n# or\n\n{\n  \"error\": \"Found unpermitted parameter: :iss_date.\"\n}\n\n# or\n\n{\n  \"errors\": \"Bad parameters: An issue_date parameter must be provided.\"\n}\n```\n"
        '503':
          description: "```json\n{\n  \"message\": \"Title 2 currently unavailable\"\n}\n```\n"
      tags:
      - Versioner Service