ctan-openapi/dist/search.yml

OpenAPI descriptions for the CTAN API

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:
                $ref: '#/components/schemas/SearchResult'
        default:
          $ref: '#/components/responses/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:
            $ref: '#/components/schemas/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'