openapi: 3.1.0 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: '2.0' servers: - url: https://ctan.org paths: /search/json: get: summary: Searching description: The search functionality can be used programmatically. parameters: - name: phrase in: query description: The search phrase, i.e. the words or search expressions to query for. required: true schema: type: string - name: offset in: query description: The offset for paging. The accompanying parameter `max` contains the page size. This parameter contains the first hit to be returned. If a negative number is passed in then it is replaced by `0`. If the offset is larger than the number of actual hits then the list of hits will be empty. schema: type: integer minimum: 0 - name: max in: query description: The number of hits maximally returned. Larger values will be reduced to `256`. Lower values will be replaced by the default value. schema: type: integer default: 16 maximum: 256 minimum: 1 - name: ext in: query description: Whether the sections are requested explicitly. If the value is `false` then all default sections are searched. Otherwise the sections to be searched have to be specified with additional parameters. schema: type: boolean default: false - name: PKG in: query description: Whether the package section should be included into the search. The package section contains the text fields of a package entry in the Catalogue. schema: type: boolean default: false - name: AUTHORS in: query description: Whether the author section should be included into the search. The author section contains the names of the contributors in the Catalogue. schema: type: boolean default: false - name: TOPICS in: query description: Whether the topics section should be included into the search. The topics section contains the text fields of the topics in the Catalogue. schema: type: boolean default: false - name: FILES in: query description: >- UNDOCUMENTED. Whether the file name in TeX archive should be included into the search. schema: type: boolean default: false $comment: Used in the search form of the CTAN web page. - name: PORTAL in: query description: Whether the portal section should be included into the search. The portal section contains the text of the portal pages. schema: type: boolean default: false - name: wildcard in: query description: |- UNDOCUMENTED. Enable prefix search. schema: type: boolean default: false $comment: Used in the search form of the CTAN web page. responses: '200': description: OK content: application/json: schema: description: Search result. type: object properties: numberOfHits: description: The total number of hits found. type: integer minimum: 0 offset: description: The offset at which the hits start. It is a repetition of the input argument `offset` which might have been adapted. type: integer minimum: 0 max: description: The maximal number of hits in this junk. It is a repetition of the input argument `max` which might have been adapted. type: integer maximum: 256 minimum: 1 phrase: description: The search phrase. It is a repetition of the input argument `phrase` which might have been adapted. type: string hits: description: The list of hits in this junk. type: array items: description: Search hit. type: object properties: title: description: The page title of the hit. type: string path: description: The absolute path on the CTAN Portal of the hit. type: string text: description: Some additional text to display. type: string required: - title - path - text title: SearchHit required: - numberOfHits - offset - max - phrase - hits title: SearchResult default: description: The body of the response contains more or less meaningless text. summary: Error externalDocs: url: https://ctan.org/help/json/2.0/searching components: schemas: SearchHit: description: Search hit. type: object properties: title: description: The page title of the hit. type: string path: description: The absolute path on the CTAN Portal of the hit. type: string text: description: Some additional text to display. type: string required: - title - path - text title: SearchHit SearchResult: description: Search result. type: object properties: numberOfHits: description: The total number of hits found. type: integer minimum: 0 offset: description: The offset at which the hits start. It is a repetition of the input argument `offset` which might have been adapted. type: integer minimum: 0 max: description: The maximal number of hits in this junk. It is a repetition of the input argument `max` which might have been adapted. type: integer maximum: 256 minimum: 1 phrase: description: The search phrase. It is a repetition of the input argument `phrase` which might have been adapted. type: string hits: description: The list of hits in this junk. type: array items: description: Search hit. type: object properties: title: description: The page title of the hit. type: string path: description: The absolute path on the CTAN Portal of the hit. type: string text: description: Some additional text to display. type: string required: - title - path - text title: SearchHit required: - numberOfHits - offset - max - phrase - hits title: SearchResult responses: Error: description: The body of the response contains more or less meaningless text. summary: Error externalDocs: url: https://ctan.org/help/json/2.0