ctan-openapi
Version:
OpenAPI descriptions for the CTAN API
1,050 lines (1,009 loc) • 32.6 kB
YAML
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.2'
servers:
- url: 'https://ctan.org/json/1.2'
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.2/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.2~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.2/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.2/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.2~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.2/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.2/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.2~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.2/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.2/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.2/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: ''
female:
description: The boolean indicator that the author is female.
type: boolean
default: false
died:
description: The indicator that the author is deceased.
type: boolean
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
- died
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:
- announce
- author
- authors
- bugs
- caption
- copyright
- ctan
- description
- descriptions
- development
- documentation
- home
- index
- install
- miktex
- name
- repository
- support
- texlive
- topic
- topics
- 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
support:
description: The URL of the support for the package.
type: string
format: uri
announce:
description: The URL of the announcements for the package.
type: string
format: uri
bugs:
description: The URL of the bug tracker for the package.
type: string
format: uri
repository:
description: The URL of the source code repository for the package.
type: string
format: uri
development:
description: The URL of the developer community 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.2'
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.2'