ctan-openapi

{ "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.\n\nThe 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": "2.0" }, "servers": [ { "url": "https://ctan.org/json/2.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.\n\nNote 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/2.0/authors" } } }, "/author/{key}": { "get": { "summary": "Author", "description": "The information about a single author can be obtained.\n\nNote 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~12.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/2.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/2.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~12.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~~.\n\n⚠️ 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/2.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/2.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~12.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/2.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/2.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/2.0/version" } } } }, "components": { "parameters": { "author-name": { "name": "author-name", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "⚠️ This does not seem to be working.\n\nIf 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" }, "title": { "description": "⚠️ This attribute no longer appears to be available.\n\nThe title of the author.", "type": "string", "deprecated": true }, "givenname": { "description": "The given name.", "type": "string", "default": "" }, "von": { "description": "The von part of the author's name. It is usually in lower case and has values like _von_, _van_, or _de_.", "type": "string", "default": "" }, "familyname": { "description": "The family name.", "type": "string", "default": "" }, "junior": { "description": "The junior part of the author's name. It is usually an addition to the name like _jr._, _sr._, or a numeral like _I_, _II_, _III_, _IV_.", "type": "string", "default": "" }, "pseudonym": { "description": "The alias name to protect the privacy of an author who requests it.", "type": "string" }, "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`.\n\nList 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.\n\nList 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.\n\nThe 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`.\n\nThe 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.\n\nA short descriptive text about the content of the package.", "type": "string" }, "detailed": { "description": "⚠️ This appears to have been renamed `caption`.\n\nA 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.\n\n⚠️ `author`, `description`, and `topic` do not seem to be valid field names.", "enum": [ "aliases", "announce", "author", "authors", "bugs", "caption", "copyright", "ctan", "description", "descriptions", "development", "documentation", "home", "index", "install", "miktex", "name", "repository", "support", "texlive", "topic", "topics", "version" ], "title": "PackageAttribute" }, "PackageAlias": { "description": "Information about an alias of the package.", "type": "object", "properties": { "id": { "description": "The id of the alias.", "type": "string" }, "name": { "description": "The name of the alias.", "type": "string" } }, "required": [ "id", "name" ], "title": "PackageAlias" }, "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.\n\nThe 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": "\n A comprehensive TeX system that you can install on your hard disk. It\n includes support for most Unix system architectures, including\n GNU/Linux and MacOS, and for Windows. The <ref refid=\"mactex\">MacTeX</ref>\n distribution is an unchanged TeX Live plus some Mac-specific\n software, but is distributed in a separate archive.\n \n \n The TeX, PDF(e)TeX, XeTeX, LuaTeX, and other engines are provided in the\n distribution, with several different running formats each; a wide\n range of support programs and macro packages is also included.\n \n \n Beware: the download from CTAN is large (several GB); it comes\n in the form of an ISO image, and is available from CTAN mirrors\n through the `Sources' link below.\n \n \n <a href=\"https://tug.org/texlive/acquire.html\">Other ways to\n acquire TeX Live</ref> include network installation, tarballs, and\n mirroring.\n " } } }, "description": { "description": "⚠️ This appears to have been renamed `text`.\n\nThe 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": "\n A comprehensive TeX system that you can install on your hard disk. It\n includes support for most Unix system architectures, including\n GNU/Linux and MacOS, and for Windows. The <ref refid=\"mactex\">MacTeX</ref>\n distribution is an unchanged TeX Live plus some Mac-specific\n software, but is distributed in a separate archive.\n \n \n The TeX, PDF(e)TeX, XeTeX, LuaTeX, and other engines are provided in the\n distribution, with several different running formats each; a wide\n range of support programs and macro packages is also included.\n \n \n Beware: the download from CTAN is large (several GB); it comes\n in the form of an ISO image, and is available from CTAN mirrors\n through the `Sources' link below.\n \n \n <a href=\"https://tug.org/texlive/acquire.html\">Other ways to\n acquire TeX Live</ref> include network installation, tarballs, and\n mirroring.\n " } } }, "language": { "description": "UNDOCUMENTED.\n\nThe 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`.\n\nThe 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.\n\nThe ISO code for the language of the description.", "type": [ "string", "null" ] }, "lang": { "description": "⚠️ This appears to have been renamed `language`.\n\nThe 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" }, "aliases": { "description": "A list of aliases for the package.", "type": "array", "items": { "$ref": "#/components/schemas/PackageAlias" } }, "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.\n\nThe 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.\n\nThe 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.\n\nThe name of the package in MiKTeX." }, { "type": "object", "properties": { "location": { "description": "⚠️ This does not seem to be a correct type definition.\n\nThe name of the package in MiKTeX.", "type": "string" } }, "required": [ "location" ], "deprecated": true } ] }, "texlive": { "oneOf": [ { "type": "string", "description": "UNDOCUMENTED.\n\nThe name of the package in TeX Live." }, { "type": "object", "properties": { "location": { "description": "⚠️ This does not seem to be a correct type definition.\n\nThe 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": "\n TeX is a typesetting system that incorporates a macro processor.\n A TeX source document specifies or incorporates a number of macro\n definitions that instruct the TeX engine how to typeset the\n document. The TeX engine also uses font metrics generated by\n <ref refid=\"metafont\">Metafont</ref>, or by any of several other\n mechanisms that incorporate fonts from other sources into an\n environment suitable for TeX.\n \n \n TeX has been, and continues, a basis and an inspiration for\n several other programs, including <ref refid=\"etex\">e-TeX</ref>\n and <ref refid=\"pdftex\">PDFTeX</ref>.\n \n \n The distribution includes the source of Knuth’s\n TeX book; this source is there to read, as an\n example of writing TeX — it should not be processed\n without Knuth’s direct permission.\n " } ], "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": "\n A comprehensive TeX system that you can install on your hard disk. It\n includes support for most Unix system architectures, including\n GNU/Linux and MacOS, and for Windows. The <ref refid=\"mactex\">MacTeX</ref>\n distribution is an unchanged TeX Live plus some Mac-specific\n software, but is distributed in a separate archive.\n \n \n The TeX, PDF(e)TeX, XeTeX, LuaTeX, and other engines are provided in the\n distribution, with several different running formats each; a wide\n range of support programs and macro packages is also included.\n \n \n Beware: the download from CTAN is large (several GB); it comes\n in the form of an ISO image, and is available from CTAN mirrors\n through the `Sources' link below.\n \n \n <a href=\"https://tug.org/texlive/acquire.html\">Other ways to\n acquire TeX Live</ref> include network installation, tarballs, and\n mirroring.\n " } ], "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": "2.0" } }, "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/2.0" } }