get:
  tags:
    - categories
  summary: Get a list of categories
  description: >
    This route retrieve the list of categories currently available to the
    accessing user. It doesn't necessarily mean that the user can *enter*
    the category, as that is a separate privilege. Specifically, this route
    will return all categories that grant the calling user the "Find
    Category" privilege.


    Subcategories are also returned, nested under a category's `children` property.
  responses:
    "200":
      description: A list of category objects currently available to the accessing user
      content:
        application/json:
          schema:
            allOf:
              - type: object
                properties:
                  title:
                    description: The page title
                    type: string
                  selectCategoryLabel:
                    type: string
                    description: Label to use for the category selector
                  categories:
                    description: A collection of category data objects
                    type: array
                    items:
                      allOf:
                        - $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject
                        - type: object
                          properties:
                            tagWhitelist:
                              type: array
                              items:
                                type: string
                            unread-class:
                              type: string
                            children:
                              type: array
                              items:
                                allOf:
                                  - $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject
                                  - type: object
                                    properties:
                                      tagWhitelist:
                                        type: array
                                        items:
                                          type: string
                                      unread-class:
                                        type: string
                                      children:
                                        type: array
                                        items:
                                          $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject
                                      parent:
                                        allOf:
                                          - $ref: ../components/schemas/CategoryObject.yaml#/CategoryObject
                                          - type: object
                                            properties:
                                              tagWhitelist:
                                                type: array
                                                items:
                                                  type: string
                                              unread-class:
                                                type: string
                                      posts:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            pid:
                                              type: number
                                            timestamp:
                                              type: number
                                            content:
                                              type: string
                                            timestampISO:
                                              type: string
                                              description: An ISO 8601 formatted date string (complementing `timestamp`)
                                            user:
                                              type: object
                                              properties:
                                                uid:
                                                  type: number
                                                  description: A user identifier
                                                username:
                                                  type: string
                                                  description: A friendly name for a given user account
                                                userslug:
                                                  type: string
                                                  description: An URL-safe variant of the username (i.e. lower-cased, spaces
                                                    removed, etc.)
                                                picture:
                                                  nullable: true
                                                  type: string
                                                icon:text:
                                                  type: string
                                                  description: A single-letter representation of a username. This is used in the
                                                    auto-generated icon given to
                                                    users without an avatar
                                                icon:bgColor:
                                                  type: string
                                                  description: A six-character hexadecimal colour code assigned to the user. This
                                                    value is used in conjunction
                                                    with `icon:text` for the user's
                                                    auto-generated icon
                                                  example: "#f44336"
                                            index:
                                              type: number
                                            cid:
                                              type: number
                                              description: A category identifier
                                            topic:
                                              type: object
                                              properties:
                                                slug:
                                                  type: string
                                                title:
                                                  type: string
                                      imageClass:
                                        type: string
                                      timesClicked:
                                        type: number
                            posts:
                              type: array
                              items:
                                type: object
                                properties:
                                  pid:
                                    type: number
                                  timestamp:
                                    type: number
                                  content:
                                    type: string
                                  timestampISO:
                                    type: string
                                    description: An ISO 8601 formatted date string (complementing `timestamp`)
                                  user:
                                    type: object
                                    properties:
                                      uid:
                                        type: number
                                        description: A user identifier
                                      username:
                                        type: string
                                        description: A friendly name for a given user account
                                      displayname:
                                        type: string
                                        description: This is either username or fullname depending on forum and user settings
                                      userslug:
                                        type: string
                                        description: An URL-safe variant of the username (i.e. lower-cased, spaces
                                          removed, etc.)
                                      picture:
                                        nullable: true
                                        type: string
                                      icon:text:
                                        type: string
                                        description: A single-letter representation of a username. This is used in the
                                          auto-generated icon given to users
                                          without an avatar
                                      icon:bgColor:
                                        type: string
                                        description: A six-character hexadecimal colour code assigned to the user. This
                                          value is used in conjunction with
                                          `icon:text` for the user's
                                          auto-generated icon
                                        example: "#f44336"
                                  index:
                                    type: number
                                  cid:
                                    type: number
                                    description: A category identifier
                                  topic:
                                    type: object
                                    properties:
                                      slug:
                                        type: string
                                      title:
                                        type: string
                            teaser:
                              type: object
                              properties:
                                url:
                                  type: string
                                timestampISO:
                                  type: string
                                  description: An ISO 8601 formatted date string (complementing `timestamp`)
                                pid:
                                  type: number
                                topic:
                                  type: object
                                  properties:
                                    slug:
                                      type: string
                                    title:
                                      type: string
                            imageClass:
                              type: string
              - $ref: ../components/schemas/Pagination.yaml#/Pagination
              - $ref: ../components/schemas/Breadcrumbs.yaml#/Breadcrumbs
              - $ref: ../components/schemas/CommonProps.yaml#/CommonProps