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": [ { "name": "key", "in": "query", "schema": { "type": "string" }, "description": "If set, only items with keys starting with the given string will be returned." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "List of authors.", "type": "array", "items": { "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" }, "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": { "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" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "Not Found", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string", "const": "Not found" } } }, "required": [ "errors" ], "title": "NotFound" } } }, "$comment": "UNDOCUMENTED." } }, "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": [ { "name": "key", "in": "query", "schema": { "type": "string" }, "description": "If set, only items with keys starting with the given string will be returned." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "List of topics.", "type": "array", "items": { "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" }, "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": { "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" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "description": "Not Found", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string", "const": "Not found" } } }, "required": [ "errors" ], "title": "NotFound" } } }, "$comment": "UNDOCUMENTED." } }, "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": [ { "name": "key", "in": "query", "schema": { "type": "string" }, "description": "If set, only items with keys starting with the given string will be returned." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "List of package summaries.", "type": "array", "items": { "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" } } } } } }, "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" } } } }, { "name": "drop", "in": "query", "schema": { "type": "array", "items": { "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" }, "default": [] }, "style": "form", "explode": false, "description": "A comma separated list of fields to drop." }, { "name": "keep-url", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Always keeps valid URLs as attributes, instead of `ctan:`-prefixed ones." }, { "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 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "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": { "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" } }, "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": { "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": { "description": "The information about the copyright.", "type": "array", "items": { "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" } }, "license": { "description": "The keys of licenses.", "oneOf": [ { "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" }, { "title": "LicenseIdentifiers", "type": "array", "items": { "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" } } ] }, "version": { "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" }, "descriptions": { "description": "Long descriptions of the package.", "type": "array", "items": { "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" } }, "documentation": { "description": "List of references to documentation.", "type": "array", "items": { "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" } }, "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.",