openapi: 3.1.1
info:
  title: Querying the CTAN Database with JSON
  description: >-
    The CTAN provides mean to access the database and retrieve the information
    in form of JSON responses. Several entities can be queried.


    The queries can be sent to the portal in form of a HTTP `GET` or `POST`
    request with some parameters. The response has the JSON as body. The request
    URL and parameters as well as the response are described on the detail
    section.
  version: '1.0'
servers:
  - url: 'https://ctan.org/json/1.0'
paths:
  /authors:
    get:
      summary: List of Authors
      description: >-
        The list of authors can be obtained. The authors contained in this list
        are ordered ascending on the key of the author.


        Note that the authors information does not contain the email address of
        the author to protect the privacy.
      parameters:
        - $ref: '#/components/parameters/key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: List of authors.
                type: array
                items:
                  $ref: '#/components/schemas/Author'
                title: Authors
      externalDocs:
        url: 'https://ctan.org/help/json/1.0/authors'
  '/author/{key}':
    get:
      summary: Author
      description: >-
        The information about a single author can be obtained.


        Note that the authors information does not contain the email address of
        the author to protect the privacy.
      parameters:
        - name: key
          in: path
          description: >-
            The key of the author as used by CTAN. Those keys are also listed in
            the [list of authors](#/paths/~1json~11.0~1authors/get).
          required: true
          schema:
            type: string
            examples:
              knuth:
                value: knuth
        - name: ref
          in: query
          description: Requests the list of packages in which the author is mentioned.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Author'
        '404':
          $ref: '#/components/responses/NotFound'
      externalDocs:
        url: 'https://ctan.org/help/json/1.0/author'
  /topics:
    get:
      summary: List of Topics
      description: >-
        The list of topics can be obtained. The topics contained in this list
        are ordered ascending on the key of the topic.
      parameters:
        - $ref: '#/components/parameters/key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: List of topics.
                type: array
                items:
                  $ref: '#/components/schemas/Topic'
                title: Topics
      externalDocs:
        url: 'https://ctan.org/help/json/1.0/topics'
  '/topic/{key}':
    get:
      summary: Topic
      description: The information about a single topic can be obtained.
      parameters:
        - name: key
          in: path
          description: >-
            The key of the topic as used by CTAN. Those keys are also listed in
            the [list of topics](#/paths/~1json~11.0~1topics/get).
          required: true
          schema:
            type: string
            examples:
              abbrev:
                value: abbrev
              cv:
                value: cv
        - name: ref
          in: query
          description: >-
            Requests the list of packages in which the topic is mentioned. In
            this case the attribute `packages` contains a list of package keys.
            The keys are unique ~~and sorted alphabetically~~.


            ⚠️ Package keys do not seem to be sorted.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Topic'
        '404':
          $ref: '#/components/responses/NotFound'
      externalDocs:
        url: 'https://ctan.org/help/json/1.0/topic'
  /packages:
    get:
      summary: List of Packages
      description: >-
        The list of packages can be obtained. The packages contained in this
        list are ordered ascending on the key of the packages.
      parameters:
        - $ref: '#/components/parameters/key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: List of package summaries.
                type: array
                items:
                  $ref: '#/components/schemas/PackageSummary'
      externalDocs:
        url: 'https://ctan.org/help/json/1.0/packages'
  '/pkg/{key}':
    get:
      summary: Package
      description: The information about a single package can be obtained.
      parameters:
        - name: key
          in: path
          description: >-
            The key of the package as used by CTAN in the [list of
            packages](#/paths/~1json~11.0~1packages/get).
          required: true
          schema:
            type: string
            examples:
              tex:
                value: tex
              texlive:
                value: texlive
        - $ref: '#/components/parameters/drop'
        - $ref: '#/components/parameters/keep-url'
        - $ref: '#/components/parameters/author-name'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Package'
        '404':
          $ref: '#/components/responses/NotFound'
      externalDocs:
        url: 'https://ctan.org/help/json/1.0/pkg'
  /licenses:
    get:
      summary: List of Licenses
      description: >-
        The list of licenses can be obtained. The licenses contained in this
        list are ordered ascending on the key of the license.
      parameters:
        - $ref: '#/components/parameters/key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: List of licenses.
                type: array
                items:
                  $ref: '#/components/schemas/License'
                title: Licenses
      externalDocs:
        url: 'https://ctan.org/help/json/1.0/licenses'
  /version:
    get:
      summary: Version
      description: The information about the version of the interface can be obtained.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiVersion'
      externalDocs:
        url: 'https://ctan.org/help/json/1.0/version'
components:
  parameters:
    author-name:
      name: author-name
      in: query
      schema:
        type: boolean
        default: false
      description: >-
        ⚠️ This does not seem to be working.


        If the parameter `author-name` can be set to `true` to include the first
        name and family name of the author as well.
      deprecated: true
    drop:
      name: drop
      in: query
      schema:
        type: array
        items:
          $ref: '#/components/schemas/PackageAttribute'
        default: []
      style: form
      explode: false
      description: A comma separated list of fields to drop.
    keep-url:
      name: keep-url
      in: query
      schema:
        type: boolean
        default: false
      description: 'Always keeps valid URLs as attributes, instead of `ctan:`-prefixed ones.'
    key:
      name: key
      in: query
      schema:
        type: string
      description: >-
        If set, only items with keys starting with the given string will be
        returned.
  schemas:
    Author:
      description: Information about an author.
      type: object
      properties:
        key:
          description: The key of the author.
          type: string
        givenname:
          description: The given name.
          type: string
          default: ''
        familyname:
          description: The family name.
          type: string
          default: ''
        pkgs:
          description: >-
            ⚠️ This appears to have been renamed `packages`.


            List of ids of packages mentioning the author. This attribute is
            included if the query parameter `ref` is set to `true`.
          type: array
          items:
            type: string
          deprecated: true
        packages:
          description: >-
            UNDOCUMENTED.


            List of ids of packages mentioning the author. This attribute is
            included if the query parameter `ref` is set to `true`.
          type: array
          items:
            type: string
      examples:
        knuth:
          value:
            key: knuth
            givenname: Donald E.
            von: ''
            familyname: Knuth
            junior: ''
            female: false
            died: false
        knuth?ref=true:
          value:
            key: knuth
            givenname: Donald E.
            von: ''
            familyname: Knuth
            junior: ''
            female: false
            died: false
            pkgs:
              - latex-fonts
              - cweb
              - cm-mf
              - cm
              - cm-tfm
              - cm-pk
              - concrete
              - dvitype
              - gkpmac
              - gray
              - graphbase
              - gen
              - halftone
              - jablantile
              - knuth-errata
              - knuth-lib
              - knuth-letter
              - knuth-dist
              - knuth-local
              - knuth-base
              - list
              - llist
              - metafont
              - mfware
              - manual
              - mfbook
              - picmac
              - punk
              - punknova
              - ransom
              - selectpage
              - texware
              - testfont
              - tex
              - tangle
              - tex--xet
              - texbook
              - twocolumns
              - vfware
              - vf-knuth
              - web
              - weave
              - base
              - cmtest
              - mflogo-font
              - plain
      required:
        - key
      title: Author
    NotFound:
      description: Not Found
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
            const: Not found
      required:
        - errors
      title: NotFound
    Topic:
      description: Information about a topic.
      type: object
      properties:
        key:
          description: The key of the topic.
          type: string
        details:
          description: A short descriptive text about the meaning of the topic.
          type: string
        packages:
          description: >-
            UNDOCUMENTED.


            The list of ids of packages referring to the topic. This attribute
            is included if the parameter `ref` is set to `true`.
          type: array
          items:
            type: string
          uniqueItems: true
        references:
          description: >-
            ⚠️ This appears to have been renamed `packages`.


            The list of ids of packages referring to the topic. This attribute
            is included if the parameter `ref` is set to `true`.
          type: array
          items:
            type: string
          deprecated: true
          uniqueItems: true
      examples:
        cv:
          value:
            key: cv
            details: curriculum vitae/Resumé
      required:
        - key
        - details
      title: Topic
    PackageSummary:
      description: Summary of a package.
      type: object
      properties:
        key:
          description: The key of the package.
          type: string
        name:
          description: The name of the package.
          type: string
        caption:
          description: |-
            UNDOCUMENTED.

            A short descriptive text about the content of the package.
          type: string
        detailed:
          description: |-
            ⚠️ This appears to have been renamed `caption`.

            A short descriptive text about the content of the package.
          type: string
          deprecated: true
      required:
        - key
        - name
        - caption
      title: PackageSummary
    PackageAttribute:
      type: string
      $comment: >-
        ⚠️ `authors`, `descriptions`, and `topics` are UNDOCUMENTED.


        ⚠️ `author`, `description`, and `topic` do not seem to be valid field
        names.
      enum:
        - author
        - authors
        - bugs
        - copyright
        - ctan
        - description
        - descriptions
        - development
        - documentation
        - index
        - install
        - miktex
        - name
        - repository
        - support
        - texlive
        - topic
        - version
      title: PackageAttribute
    PackageAuthor:
      description: Information about a package author.
      type: object
      properties:
        id:
          description: The key of the author.
          type: string
        active:
          description: UNDOCUMENTED.
          type: boolean
      required:
        - id
        - active
      title: PackageAuthor
    Copyright:
      type: object
      properties:
        owner:
          description: The name of the copyright holder.
          type: string
        year:
          description: The year or years of the copyright.
          type:
            - string
            - 'null'
          $comment: ⚠️ The value of `null` is UNDOCUMENTED.
      required:
        - owner
        - year
      title: Copyright
    LicenseIdentifier:
      description: Identifier of a license.
      type: string
      enum:
        - apache2
        - artistic
        - artistic2
        - bsd
        - bsd2
        - bsd3
        - bsd4
        - cc-by-1
        - cc-by-2
        - cc-by-3
        - cc-by-4
        - cc-by-nc-1
        - cc-by-nc-2
        - cc-by-nc-3
        - cc-by-nc-4
        - cc-by-nc-nd-1
        - cc-by-nc-nd-2
        - cc-by-nc-nd-2.5
        - cc-by-nc-nd-3
        - cc-by-nc-nd-4
        - cc-by-nc-sa4
        - cc-by-nd-1
        - cc-by-nd-2
        - cc-by-nd-3
        - cc-by-nd-4
        - cc-by-sa-1
        - cc-by-sa-2
        - cc-by-sa-3
        - cc-by-sa-4
        - cc0
        - eupl
        - fdl
        - gfl
        - gfsl
        - gpl
        - gpl1
        - gpl1+
        - gpl2
        - gpl2+
        - gpl3
        - gpl3+
        - isc
        - knuth
        - lgpl
        - lgpl2.1
        - lgpl3
        - lppl
        - lppl1
        - lppl1.2
        - lppl1.3
        - lppl1.3a
        - lppl1.3b
        - lppl1.3c
        - mit
        - nocommercial
        - nosell
        - nosource
        - ofl
        - opl
        - other-free
        - other-nonfree
        - pd
        - shareware
        - x11
        - noinfo
      title: LicenseIdentifier
    PackageVersion:
      description: Information about the version of a package.
      type: object
      properties:
        number:
          description: The version number.
          type: string
        date:
          description: The version date.
          type: string
      minProperties: 1
      title: PackageVersion
    PackageDescription:
      description: A long description of a package.
      type: object
      properties:
        text:
          description: >-
            UNDOCUMENTED.


            The longer description of the package, which may include HTML
            markup. An inner tag `<ref>` is used to reference a package with
            attribute `refid`.
          type: string
          examples:
            texlive:
              value: |-
                <p>
                       A comprehensive TeX system that you can install on your hard disk.  It
                       includes support for most Unix system architectures, including
                       GNU/Linux and MacOS, and for Windows.  The <ref refid="mactex">MacTeX</ref>
                       distribution is an unchanged TeX Live plus some Mac-specific
                       software, but is distributed in a separate archive.
                    </p>
                  <p>
                       The TeX, PDF(e)TeX, XeTeX, LuaTeX, and other engines are provided in the
                       distribution, with several different running formats each; a wide
                       range of support programs and macro packages is also included.
                    </p>
                  <p>
                       Beware: the download from CTAN is large (several GB); it comes
                       in the form of an ISO image, and is available from CTAN mirrors
                       through the `Sources' link below.
                    </p>
                  <p>
                    <a href="https://tug.org/texlive/acquire.html">Other ways to
                      acquire TeX Live</ref> include network installation, tarballs, and
                      mirroring.
                    </p>
        description:
          description: >-
            ⚠️ This appears to have been renamed `text`.


            The longer description of the package, which may include HTML
            markup. An inner tag `<ref>` is used to reference a package with
            attribute `refid`.
          type: string
          deprecated: true
          examples:
            texlive:
              value: |-
                <p>
                       A comprehensive TeX system that you can install on your hard disk.  It
                       includes support for most Unix system architectures, including
                       GNU/Linux and MacOS, and for Windows.  The <ref refid="mactex">MacTeX</ref>
                       distribution is an unchanged TeX Live plus some Mac-specific
                       software, but is distributed in a separate archive.
                    </p>
                  <p>
                       The TeX, PDF(e)TeX, XeTeX, LuaTeX, and other engines are provided in the
                       distribution, with several different running formats each; a wide
                       range of support programs and macro packages is also included.
                    </p>
                  <p>
                       Beware: the download from CTAN is large (several GB); it comes
                       in the form of an ISO image, and is available from CTAN mirrors
                       through the `Sources' link below.
                    </p>
                  <p>
                    <a href="https://tug.org/texlive/acquire.html">Other ways to
                      acquire TeX Live</ref> include network installation, tarballs, and
                      mirroring.
                    </p>
        language:
          description: >-
            UNDOCUMENTED.


            The ISO code for the language of the description. Alternately it may
            be `null` to indicate the default language, i.e. English.
          type:
            - string
            - 'null'
        lang:
          description: >-
            ⚠️ This appears to have been renamed `lang`.


            The ISO code for the language of the description. Alternately it may
            be `null` to indicate the default language, i.e. English.
          type:
            - string
            - 'null'
          $comment: ⚠️ The value of `null` is UNDOCUMENTED.
          deprecated: true
      required: []
      title: PackageDescription
    PackageDocumentation:
      type: object
      properties:
        language:
          description: |-
            UNDOCUMENTED.

            The ISO code for the language of the description.
          type:
            - string
            - 'null'
        lang:
          description: |-
            ⚠️ This appears to have been renamed `language`.

            The ISO code for the language of the description.
          type:
            - string
            - 'null'
          $comment: ⚠️ The value of `null` is UNDOCUMENTED.
          deprecated: true
        details:
          description: The (English) text describing this documentation item.
          type: string
        href:
          description: >-
            A reference to the documentation. The prefix `ctan:` indicates a
            reference to a directory on CTAN. If the parameter `keep-url` is
            `true` then this attribute contains always a valid URL without the
            `ctan:` prefix.
          type: string
          format: uri
      required: []
      title: PackageDocumentation
    Package:
      description: Information about a package.
      type: object
      properties:
        id:
          description: The unique id of the package.
          type: string
        name:
          description: The print representation of the package name.
          type: string
        caption:
          description: A short description of the package.
          type: string
        authors:
          description: The list of authors.
          type: array
          items:
            $ref: '#/components/schemas/PackageAuthor'
        copyright:
          description: The information about the copyright.
          type: array
          items:
            $ref: '#/components/schemas/Copyright'
        license:
          description: The keys of licenses.
          oneOf:
            - $ref: '#/components/schemas/LicenseIdentifier'
            - title: LicenseIdentifiers
              type: array
              items:
                $ref: '#/components/schemas/LicenseIdentifier'
        version:
          $ref: '#/components/schemas/PackageVersion'
        descriptions:
          description: Long descriptions of the package.
          type: array
          items:
            $ref: '#/components/schemas/PackageDescription'
        documentation:
          description: List of references to documentation.
          type: array
          items:
            $ref: '#/components/schemas/PackageDocumentation'
        ctan:
          description: The location of the package in the CTAN tree.
          type: object
          properties:
            path:
              description: The relative path of the package in the CTAN tree.
              type: string
              format: uri-reference
            file:
              description: The indicator that this package consists of a single file only.
              type: boolean
              default: false
          required:
            - path
        install:
          oneOf:
            - type: string
              format: uri-reference
              description: >-
                UNDOCUMENTED.


                The location of the package on CTAN relative to the CTAN
                directory `/install` in form of an installable TDS-compliant zip
                archive.
            - type: object
              properties:
                path:
                  description: The path relative to the CTAN directory `/install`.
                  type: string
                  format: uri-reference
              required:
                - path
              description: >-
                ⚠️ This does not seem to be a correct type definition.


                The location of the package on CTAN relative to the CTAN
                directory `/install` in form of an installable TDS-compliant zip
                archive.
              deprecated: true
        miktex:
          oneOf:
            - type: string
              description: |-
                UNDOCUMENTED.

                The name of the package in MiKTeX.
            - type: object
              properties:
                location:
                  description: |-
                    ⚠️ This does not seem to be a correct type definition.

                    The name of the package in MiKTeX.
                  type: string
              required:
                - location
              deprecated: true
        texlive:
          oneOf:
            - type: string
              description: |-
                UNDOCUMENTED.

                The name of the package in TeX Live.
            - type: object
              properties:
                location:
                  description: |-
                    ⚠️ This does not seem to be a correct type definition.

                    The name of the package in TeX Live.
                  type: string
              deprecated: true
        index:
          description: A list of extra terms to be indexed for the search.
          type: array
          items:
            type: string
        topics:
          description: A list of topics keys for this entry.
          type: array
          items:
            type: string
        home:
          description: The URL of the home page of the package.
          type: string
          format: uri
        repository:
          description: The URL of the source code repository for the package.
          type: string
          format: uri
        also:
          description: UNDOCUMENTED.
          type: array
          items:
            type: string
      examples:
        tex:
          value:
            id: tex
            name: TeX
            aliases: []
            caption: A sophisticated typesetting engine
            authors:
              - id: knuth
                active: true
            copyright:
              - owner: D. E. Knuth
                year: null
            license: knuth
            version:
              number: '3.141592653'
              date: '2021-02-05'
            descriptions:
              - language: null
                text: |-
                  <p>
                              TeX is a typesetting system that incorporates a macro processor.
                              A TeX source document specifies or incorporates a number of macro
                              definitions that instruct the TeX engine how to typeset the
                              document.  The TeX engine also uses font metrics generated by
                              <ref refid="metafont">Metafont</ref>, or by any of several other
                              mechanisms that incorporate fonts from other sources into an
                              environment suitable for TeX.
                          </p>
                    <p>
                              TeX has been, and continues, a basis and an inspiration for
                              several other programs, including <ref refid="etex">e-TeX</ref>
                              and <ref refid="pdftex">PDFTeX</ref>.
                          </p>
                    <p>
                              The distribution includes the source of Knuth’s
                              <em>TeX book</em>; this source is there to read, as an
                              example of writing TeX — it should not be processed
                              without Knuth’s direct permission.
                          </p>
            support: 'https://lists.tug.org/tex-k'
            bugs: 'https://lists.tug.org/tex-k'
            repository: 'https://tug.org/svn/texlive/trunk/Build/source/texk/web2c/'
            ctan:
              path: /systems/knuth/dist/tex
              file: true
            miktex: miktex-tex-bin-2.9
            texlive: tex
            topics:
              - engine
        texlive:
          value:
            id: texlive
            name: texlive
            aliases: []
            caption: A comprehensive distribution of TeX and friends
            authors:
              - id: texlive
                active: true
            copyright: []
            license: other-free
            version:
              number: '2025'
              date: ''
            descriptions:
              - language: null
                text: |-
                  <p>
                         A comprehensive TeX system that you can install on your hard disk.  It
                         includes support for most Unix system architectures, including
                         GNU/Linux and MacOS, and for Windows.  The <ref refid="mactex">MacTeX</ref>
                         distribution is an unchanged TeX Live plus some Mac-specific
                         software, but is distributed in a separate archive.
                      </p>
                    <p>
                         The TeX, PDF(e)TeX, XeTeX, LuaTeX, and other engines are provided in the
                         distribution, with several different running formats each; a wide
                         range of support programs and macro packages is also included.
                      </p>
                    <p>
                         Beware: the download from CTAN is large (several GB); it comes
                         in the form of an ISO image, and is available from CTAN mirrors
                         through the `Sources' link below.
                      </p>
                    <p>
                      <a href="https://tug.org/texlive/acquire.html">Other ways to
                        acquire TeX Live</ref> include network installation, tarballs, and
                        mirroring.
                      </p>
            documentation:
              - language: null
                details: Readme
                href: 'ctan:/systems/texlive/Images/README.md'
            home: 'https://tug.org/texlive/'
            support: 'https://tug.org/texlive/lists.html'
            bugs: 'https://lists.tug.org/tex-live'
            repository: 'https://tug.org/texlive/svn/'
            ctan:
              path: /systems/texlive/Images
              file: true
            topics:
              - distribution
            also:
              - texlive-source
      required:
        - id
        - name
        - caption
        - authors
        - descriptions
        - documentation
      title: Package
    License:
      description: Information about a license.
      type: object
      properties:
        key:
          description: The key of the license.
          allOf:
            - $ref: '#/components/schemas/LicenseIdentifier'
        name:
          description: The printable name of the license.
          type: string
        free:
          description: The indication whether the license is considered free.
          type: boolean
      required:
        - key
        - name
        - free
      title: License
    ApiVersion:
      description: The information about the version of the interface.
      type: object
      properties:
        version:
          description: The version number as string.
          type: string
          const: '1.1'
      additionalProperties: false
      required:
        - version
      title: ApiVersion
  responses:
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFound'
      $comment: UNDOCUMENTED.
externalDocs:
  url: 'https://ctan.org/help/json/1.0'