api.yml

---
openapi: "3.0.0"
info:
  title: IETF Author Tools API
  version: 6.6.6
servers:
  - url: https://author-tools.ietf.org
    description: Alpha server
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Personal API can be generated from datatracker (https://datatracker.ietf.org/accounts/apikey). (optional)
security:
  - apiKeyAuth: []
paths:
  /api/render/text:
    post:
      summary: Convert draft to text format.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: kramdown-rfc/mmark (.md, .mkd) file or xml2rfc v2/v3 (.xml) file or text draft (.txt)
                apikey:
                  type: string
                  description: Personal API can be generated from datatracker (https://datatracker.ietf.org/accounts/apikey). API Key can be submitted as X-API-KEY in headers as well. (optional)
      responses:
        '200':
          description: Returns temporary URL to the draft in requested format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: list of errors
                    items:
                      type: string
                      description: error description
                  warnings:
                    type: array
                    description: list of warnings
                    items:
                      type: string
                      description: warning description
                  url:
                    type: string
                    description: Temporary URL to requested format
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
  /api/render/xml:
    post:
      summary: Convert draft to xml2rfc v3 format.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: kramdown-rfc/mmark (.md, .mkd) file or xml2rfc v2/v3 (.xml) file or text draft (.txt)
                apikey:
                  type: string
                  description: Personal API can be generated from datatracker (https://datatracker.ietf.org/accounts/apikey). API Key can be submitted as X-API-KEY in headers as well. (optional)
      responses:
        '200':
          description: Returns temporary URL to the draft in requested format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: list of errors
                    items:
                      type: string
                      description: error description
                  warnings:
                    type: array
                    description: list of warnings
                    items:
                      type: string
                      description: warning description
                  url:
                    type: string
                    description: Temporary URL to requested format
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
  /api/render/html:
    post:
      summary: Convert draft to HTML format.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: kramdown-rfc/mmark (.md, .mkd) file or xml2rfc v2/v3 (.xml) file or text draft (.txt)
                apikey:
                  type: string
                  description: Personal API can be generated from datatracker (https://datatracker.ietf.org/accounts/apikey). API Key can be submitted as X-API-KEY in headers as well. (optional)
      responses:
        '200':
          description: Returns temporary URL to the draft in requested format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: list of errors
                    items:
                      type: string
                      description: error description
                  warnings:
                    type: array
                    description: list of warnings
                    items:
                      type: string
                      description: warning description
                  url:
                    type: string
                    description: Temporary URL to requested format
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
  /api/render/pdf:
    post:
      summary: Renders draft to PDF format.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: kramdown-rfc/mmark (.md, .mkd) file or xml2rfc v2/v3 (.xml) file or text draft (.txt)
                apikey:
                  type: string
                  description: Personal API can be generated from datatracker (https://datatracker.ietf.org/accounts/apikey). API Key can be submitted as X-API-KEY in headers as well. (optional)
      responses:
        '200':
          description: Returns temporary URL to the draft in requested format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: list of errors
                    items:
                      type: string
                      description: error description
                  warnings:
                    type: array
                    description: list of warnings
                    items:
                      type: string
                      description: warning description
                  url:
                    type: string
                    description: Temporary URL to requested format
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
  /api/validate:
    post:
      summary: Validates the draft
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: kramdown-rfc/mmark (.md, .mkd) file or xml2rfc v2/v3 (.xml) file or text draft (.txt)
                apikey:
                  type: string
                  description: Personal API can be generated from datatracker (https://datatracker.ietf.org/accounts/apikey). API Key can be submitted as X-API-KEY in headers as well. (optional)
      responses:
        '200':
          description: Returns errors, warnings and idnits output
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: list of errors
                    items:
                      type: string
                      description: error description
                  warnings:
                    type: array
                    description: list of warnings
                    items:
                      type: string
                      description: warning description
                  idnits:
                    type: string
                    description: idnits output
                  non_ascii:
                    type: string
                    description: kramdown-rfc echars output
                  bare_unicode:
                    type: array
                    description: list of bare Unicode (non-ascci) usage report
                    items:
                      type: string
                      description: warning description
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
  /api/iddiff:
    post:
      summary: Compare two documents with iddiff
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file_1:
                  type: string
                  format: binary
                  description: kramdown-rfc/mmark (.md, .mkd) file or xml2rfc v2/v3 (.xml) file or text document (.txt)
                file_2:
                  type: string
                  format: binary
                  description: kramdown-rfc/mmark (.md, .mkd) file or xml2rfc v2/v3 (.xml) file or text document (.txt). This is optional. If file_2, doc_2 or url_2 is not provided, second document will be identified based on the first document or first document file name.
                doc_1:
                  type: string
                  description: First document name unless file_1 is provided.
                doc_2:
                  type: string
                  description: Second document name unless file_2 is provided. This is optional. If file_2, doc_2 or url_2 is not provided, second document will be identified based on the first document or first document file name.
                url_1:
                  type: string
                  description: First document URL unless file_1 or doc_1 is provided.
                url_2:
                  type: string
                  description: Second document URL unless file_2 or doc_2 is provided. This is optional. If file_2, doc_2 or url_2 is not provided, second document will be identified based on the first document or first document file name.
                wdiff:
                  type: string
                  description: If this property is set, HTML wdiff is returned.
                chbars:
                  type: string
                  description: If this property is set, changebar output is returned.
                abdiff:
                  type: string
                  description: If this property is set, before-after output is returned.
                table:
                  type: string
                  description: If this property is set, HTML table is returned. (ignored if wdiff is set)
                latest:
                  type: string
                  description: If this property is set and second document is not provided, use the latest document from datatracker for comparison.
                url1:
                  type: string
                  description: (rfcdiff compatibility parameter) First document URL or document name.
                url2:
                  type: string
                  description: (rfcdiff compatibility parameter) Second document URL or document name.
                difftype:
                  type: string
                  description: (rfcdiff compatibility parameter) Diff type; Accepts wdiff, hwdiff, chbars and abdiff.
                rfcdiff:
                  type: string
                  description: Use rfcdiff instead of iddiff (no op, this API call uses rfcdiff by default)
                iddiff:
                  type: string
                  description: Use iddiff instead of iddiff (experimental)
                raw:
                  type: string
                  description: If this property is set, input files are not converted to text.
                apikey:
                  type: string
                  description: Personal API can be generated from datatracker (https://datatracker.ietf.org/accounts/apikey). API Key can be submitted as X-API-KEY in headers as well. (optional)
      responses:
        '200':
          description: Returns iddiff as HTML or text
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
    get:
      summary: Compare two documents with iddiff
      parameters:
        - in: query
          name: doc_1
          schema:
            type: string
          description: First document name unless url_1 is provided.
        - in: query
          name: doc_2
          schema:
            type: string
          description: Second document name unless url_2 is provided. This is optional. If doc_2 and url_2 are not provided, second document will be identified based on the first document or first document file name.
        - in: query
          name: url_1
          schema:
            type: string
          description: First document URL unless doc_1 is provided.
        - in: query
          name: url_2
          schema:
            type: string
          description: Second document URL unless doc_2 is provided. This is optional. If doc_2 and url_2 are not provided, second document will be identified based on the first document or first document file name.
        - in: query
          name: wdiff
          schema:
            type: string
          description: If this property is set, HTML wdiff is returned.
        - in: query
          name: chbars
          schema:
            type: string
          description: If this property is set, changebar output is returned.
        - in: query
          name: abdiff
          schema:
            type: string
          description: If this property is set, before-after output is returned.
        - in: query
          name: table
          schema:
            type: string
          description: If this property is set, HTML table is returned. (ignored if wdiff is set)
        - in: query
          name: rfcdiff
          schema:
            type: string
          description: Use rfcdiff instead of iddiff (no op, this API call uses rfcdiff by default)
        - in: query
          name: iddiff
          schema:
            type: string
          description: Use iddiff instead of iddiff (experimental)
        - in: query
          name: raw
          schema:
            type: string
          description: If this property is set, input files are not converted to text.
        - in: query
          name: url1
          schema:
            type: string
          description: (rfcdiff compatibility parameter) First document URL or document name.
        - in: query
          name: url2
          schema:
            type: string
          description: (rfcdiff compatibility parameter) Second document URL or document name.
      responses:
        '200':
          description: Returns iddiff as HTML or text
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
  /api/idnits:
    get:
      summary: Get idnits output
      parameters:
        - in: query
          name: url
          schema:
            type: string
          required: true
          description: Draft URL
        - in: query
          name: verbose
          schema:
            type: integer
            minimum: 0
            default: 0
            maximum: 2
          description: Sets verbose level from 0 to 2.
        - in: query
          name: hidetext
          schema:
            type: string
          description: Set this to remove draft text from output.
        - in: query
          name: year
          schema:
            type: integer
          description: Use the given year in the boilerplate (instead of the current year).
        - in: query
          name: submitcheck
          schema:
            type: string
          description: Set this to do submission checks
      responses:
        '200':
          description: Returns idnits output
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
    post:
      summary: Get idnits output
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: kramdown-rfc/mmark (.md, .mkd) file or xml2rfc v2/v3 (.xml) file or text draft (.txt)
                verbose:
                  type: integer
                  minimum: 0
                  default: 0
                  maximum: 2
                  description: Sets verbose level from 0 to 2.
                hidetext:
                  type: string
                  description: Set this to remove draft text from output.
                year:
                  type: integer
                  description: Use the given year in the boilerplate (instead of the current year).
                submitcheck:
                  type: string
                  description: Set this to do submission checks
      responses:
        '200':
          description: Returns idnits output
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
  /api/idnits3:
    get:
      summary: Get idnits v3 output. idnits v3 is still in alpha state.
      parameters:
        - in: query
          name: url
          schema:
            type: string
          required: true
          description: Draft URL
        - in: query
          name: year
          schema:
            type: integer
          description: Use the given year in the boilerplate (instead of the current year).
        - in: query
          name: submitcheck
          schema:
            type: string
          description: Set this to do submission checks
      responses:
        '200':
          description: Returns idnits output
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
    post:
      summary: Get idnits v3 output. idnits v3 is still in alpha state.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: kramdown-rfc/mmark (.md, .mkd) file or xml2rfc v2/v3 (.xml) file or text draft (.txt)
                year:
                  type: integer
                  description: Use the given year in the boilerplate (instead of the current year).
                submitcheck:
                  type: string
                  description: Set this to do submission checks
      responses:
        '200':
          description: Returns idnits output
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
  /api/abnf/extract:
    get:
      summary: Extract ABNF using BAP aex
      parameters:
        - in: query
          name: url
          schema:
            type: string
          description: Document URL
        - in: query
          name: doc
          schema:
            type: string
          description: Document name
      responses:
        '200':
          description: Returns bap aex output
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
  /api/abnf/parse:
    post:
      summary: Parse ABNF using BAP
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                input:
                  type: string
                  description: ABNF input
      responses:
        '200':
          description: Returns bap output
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: string
                    description: BAP errors
                  abnf:
                    type: string
                    description: Parsed ABNF from BAP
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
  /api/svgcheck:
    post:
      summary: Returns svgcheck output with parsed SVG
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: SVG file with .svg extension
                apikey:
                  type: string
                  description: Personal API can be generated from datatracker (https://datatracker.ietf.org/accounts/apikey). API Key can be submitted as X-API-KEY in headers as well. (optional)
      responses:
        '200':
          description: Returns svgcheck output
          content:
            application/json:
              schema:
                type: object
                properties:
                  svg:
                    type: string
                    description: Parsed SVG output
                  svgcheck:
                    type: string
                    description: svgcheck output logs
                  errors:
                    type: string
                    description: svgcheck errors
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
  /api/clean_svg_ids:
    post:
      summary: Changes SVG duplicate ids in SVG
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: XML file with .xml extension
                apikey:
                  type: string
                  description: Personal API can be generated from datatracker (https://datatracker.ietf.org/accounts/apikey). API Key can be submitted as X-API-KEY in headers as well. (optional)
      responses:
        '200':
          description: Returns temporary URL to the draft in requested format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: Temporary URL to requested format
        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        '401':
          description: Failed to authenticate.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
  /api/version:
    get:
      summary: Returns version information.
      responses:
        '200':
          description: Returns version information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions:
                    type: object
                    properties:
                      author_tools_api:
                        type: string
                        description: Author Tools API version
                      xml2rfc:
                        type: string
                        description: xml2rfc version
                      kramdown-rfc:
                        type: string
                        description: kramdown-rfc version
                      mmark:
                        type: string
                        description: mmark version
                      id2xml:
                        type: string
                        description: id2xml version
                      weasyprint:
                        type: string
                        description: weasyprint version
                      idnits:
                        type: string
                        description: idnits version
                      idnits3:
                        type: string
                        description: idnits v3 version
                      iddiff:
                        type: string
                        description: iddiff version
                      aasvg:
                        type: string
                        description: aasvg version
                      bap:
                        type: string
                        description: bap version
                      svgcheck:
                        type: string
                        description: svgcheck version
                      rfcdiff:
                        type: string
                        description: rfcdiff version