# This code is auto generated, at src/scripts/generate-docs with the version 2.0.0 do NOT alter it directly

openapi: 3.1.0
info:
  title: Broker API
  version: 1.0.0
paths:
  /api/v2/mqtt/topics:
    get:
      security:
        - ApiKeyHeader: []
      summary: List MQTT topics under a prefix
      description: >-
        Returns a paginated tree of MQTT topics starting from a given prefix
        with optional pagination.
      parameters:
        - name: prefix
          in: query
          description: The root prefix to start listing from
          required: true
          schema:
            type: string
            example: test/topic
        - name: depth
          in: query
          description: Depth to traverse in the topic tree
          required: false
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Maximum number of results to return
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          description: Offset to start listing from
          required: false
          schema:
            type: integer
            default: 0
        - name: last_node
          in: query
          description: Efficient jump to next offset by providing last queried topic node
          required: false
          schema:
            type: string
            example: test/topic/100
      responses:
        '200':
          description: List of matched MQTT topics
          content:
            application/json:
              schema:
                type: object
                required:
                  - jsonapi
                  - meta
                  - data
                  - included
                properties:
                  jsonapi:
                    type: object
                    required:
                      - version
                    properties:
                      version:
                        type: string
                  meta:
                    type: object
                    required:
                      - prefix
                      - depth
                      - limit
                      - offset
                    properties:
                      prefix:
                        type: string
                        description: >-
                          The prefix of the current listing in complete topic
                          segments
                        example: test/topic
                      depth:
                        type: integer
                        description: The depth of traversal from the root, 0 =< Depth =< 1
                        example: 1
                      limit:
                        type: integer
                        description: The maximum number of items returned
                        example: 10
                      offset:
                        type: integer
                        description: The starting index in the overall item list
                        example: 0
                      total:
                        type: integer
                        description: >-
                          The total number of matching items, not present when
                          last_node is used in query
                        example: 312074
                      last_node:
                        type: string
                        description: >-
                          The last node parameter used in query, not present
                          when there was no such used
                        example: test/topic/100
                  data:
                    type: array
                    description: A list of topic nodes
                    items:
                      type: object
                      required:
                        - id
                        - type
                        - attributes
                      properties:
                        id:
                          type: string
                          description: The full topic path from the root
                          example: test/100002
                        type:
                          type: string
                          enum:
                            - topic-nodes
                        attributes:
                          type: object
                          required:
                            - name
                            - isLeaf
                          properties:
                            name:
                              type: string
                              description: The name of the topic segment
                              example: '100002'
                            isLeaf:
                              type: boolean
                              description: Indicates whether the topic has no children
                            childCount:
                              type: number
                              description: Number of direct child topics
                  included:
                    type: array
        '400':
          description: Problem with query parameters
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  jsonapi:
                    type: object
                    properties:
                      version:
                        type: string
                        example: '1.1'
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          example: '400'
                        error:
                          type: string
                          example: Bad Request
                        message:
                          type: string
                          example: Parameter 'limit' must be an integer ≥ 1 (≤ 100).
        '404':
          description: No matched MQTT topics
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  jsonapi:
                    type: object
                    properties:
                      version:
                        type: string
                        example: '1.1'
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          example: '404'
                        error:
                          type: string
                          example: Not Found
                        message:
                          type: string
                          example: No topics found with prefix 'test2'.
        '413':
          description: >-
            Query would result too many nodes, user needs to narrow down the
            search
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  jsonapi:
                    type: object
                    properties:
                      version:
                        type: string
                        example: '1.1'
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          example: '413'
                        error:
                          type: string
                          example: Payload Too Large
                        message:
                          type: string
                          example: >-
                            Requested subtree is too large. Try reducing 'depth'
                            or narrowing 'prefix'.
        '429':
          description: >-
            Request had to stay in queue for more than 10s or queue already has
            10 waiting requests, default rate is 10 per second, max 3 concurrent
            running request
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  jsonapi:
                    type: object
                    properties:
                      version:
                        type: string
                        example: '1.1'
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          example: '429'
                        error:
                          type: string
                          example: Too Many Requests
                        message:
                          type: string
                          example: Global rate limit exceeded. Please retry later.
        '500':
          description: Query crashed for any reason
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  jsonapi:
                    type: object
                    properties:
                      version:
                        type: string
                        example: '1.1'
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          example: '500'
                        error:
                          type: string
                          example: Internal Server Error
                        message:
                          type: string
                          example: Unable to fetch topics. Please try again later.
        '504':
          description: Query processing took more than 10s
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  jsonapi:
                    type: object
                    properties:
                      version:
                        type: string
                        example: '1.1'
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        status:
                          type: string
                          example: '504'
                        error:
                          type: string
                          example: Gateway Timeout
                        message:
                          type: string
                          example: >-
                            Request timed out. Try reducing 'depth' or using
                            smaller 'limit'.
securityDefinitions:
  ApiKeyHeader:
    type: apiKey
    in: header
    name: Authorization
