Fenergo Categories API

openapi: 3.2.0
info:
  title: Fenergo Categories API
  version: '2.0'
  description: 'Operations tagged Categories across 2 of this provider''s published API definitions: fenergo-reportscommand-v2-0-openapi.json, fenergo-reportsquery-v2-0-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: /reportscommand
- url: /reportsquery
security:
- Bearer: []
tags:
- name: Categories
paths:
  /api/v2/Categories:
    post:
      tags:
      - Categories
      summary: Create a new query category
      operationId: CreateCategory
      parameters:
      - name: X-TENANT-ID
        in: header
        description: The UiD of the tenant representing organization
        required: true
        schema:
          type: string
        example: b11f8be3-f29b-4959-8964-956d4af7c468
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CreateCategoryDtoServiceRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedCategoryDtoServiceResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '409':
          description: Conflict saving changes in expected version
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectServiceResponse'
              example:
                data: {}
                messages:
                - message: There are conflicts that cannot be resolved automatically, get latest and apply your changes
                  type: Error
                  errorCode: CONFLICT
        '401':
          description: User is not authorized to perform this request
          content:
            application/json:
              example:
                message: Unauthorized
        '403':
          description: Access to resource is forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectServiceResponse'
              example:
                data: {}
                messages:
                - message: 'Access denied. Following permissions are required: Permission1, Permission2'
                  type: Forbidden
                  errorCode: Error Code
        '500':
          description: Internal server exception. Please, contact your provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectServiceResponse'
              example:
                data: null
                messages:
                - message: Internal server exception. Please, contact your provider.
                  type: Error
                  errorCode: INTERNAL_SERVER_ERROR
        '410':
          description: Endpoint marked as deprecated was terminated. This response will be present only if the endpoint was marked as deprecated and has reached the sunset date. During the deprecation period, the API will include additional 'sunset' and 'deprecation' headers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringServiceResponse'
              example:
                data: null
                messages:
                - message: This endpoint is obsolete and was terminated on yyyy-MM-dd
                  type: Error
                  errorCode: OBSOLETE_ENDPOINT
    get:
      tags:
      - Categories
      summary: Returns all non-deleted categories for the requesting tenant
      operationId: GetAllCategories
      parameters:
      - name: X-TENANT-ID
        in: header
        description: The UiD of the tenant representing organization
        required: true
        schema:
          type: string
        example: b11f8be3-f29b-4959-8964-956d4af7c468
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryDtoIEnumerableServiceResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectServiceResponse'
              example:
                data: {}
                messages:
                - message: Not Found
                  type: Error
                  errorCode: Error Code
        '401':
          description: User is not authorized to perform this request
          content:
            application/json:
              example:
                message: Unauthorized
        '403':
          description: Access to resource is forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectServiceResponse'
              example:
                data: {}
                messages:
                - message: 'Access denied. Following permissions are required: Permission1, Permission2'
                  type: Forbidden
                  errorCode: Error Code
        '500':
          description: Internal server exception. Please, contact your provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectServiceResponse'
              example:
                data: null
                messages:
                - message: Internal server exception. Please, contact your provider.
                  type: Error
                  errorCode: INTERNAL_SERVER_ERROR
        '410':
          description: Endpoint marked as deprecated was terminated. This response will be present only if the endpoint was marked as deprecated and has reached the sunset date. During the deprecation period, the API will include additional 'sunset' and 'deprecation' headers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringServiceResponse'
              example:
                data: null
                messages:
                - message: This endpoint is obsolete and was terminated on yyyy-MM-dd
                  type: Error
                  errorCode: OBSOLETE_ENDPOINT
    servers:
    - url: /reportscommand
  /api/v2/Categories/{categoryId}:
    put:
      tags:
      - Categories
      summary: Update an existing query category
      operationId: UpdateCategory
      parameters:
      - name: categoryId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-TENANT-ID
        in: header
        description: The UiD of the tenant representing organization
        required: true
        schema:
          type: string
        example: b11f8be3-f29b-4959-8964-956d4af7c468
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/UpdateCategoryDtoServiceRequest'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectServiceResponse'
              example:
                data: {}
                messages:
                - message: Not Found
                  type: Error
                  errorCode: Error Code
        '401':
          description: User is not authorized to perform this request
          content:
            application/json:
              example:
                message: Unauthorized
        '403':
          description: Access to resource is forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectServiceResponse'
              example:
                data: {}
                messages:
                - message: 'Access denied. Following permissions are required: Permission1, Permission2'
                  type: Forbidden
                  errorCode: Error Code
        '500':
          description: Internal server exception. Please, contact your provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectServiceResponse'
              example:
                data: null
                messages:
                - message: Internal server exception. Please, contact your provider.
                  type: Error
                  errorCode: INTERNAL_SERVER_ERROR
        '410':
          description: Endpoint marked as deprecated was terminated. This response will be present only if the endpoint was marked as deprecated and has reached the sunset date. During the deprecation period, the API will include additional 'sunset' and 'deprecation' headers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringServiceResponse'
              example:
                data: null
                messages:
                - message: This endpoint is obsolete and was terminated on yyyy-MM-dd
                  type: Error
                  errorCode: OBSOLETE_ENDPOINT
    delete:
      tags:
      - Categories
      summary: Delete (soft-delete) a query category
      operationId: DeleteCategory
      parameters:
      - name: categoryId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: X-TENANT-ID
        in: header
        description: The UiD of the tenant representing organization
        required: true
        schema:
          type: string
        example: b11f8be3-f29b-4959-8964-956d4af7c468
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectServiceResponse'
              example:
                data: {}
                messages:
                - message: Not Found
                  type: Error
                  errorCode: Error Code
        '401':
          description: User is not authorized to perform this request
          content:
            application/json:
              example:
                message: Unauthorized
        '403':
          description: Access to resource is forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectServiceResponse'
              example:
                data: {}
                messages:
                - message: 'Access denied. Following permissions are required: Permission1, Permission2'
                  type: Forbidden
                  errorCode: Error Code
        '500':
          description: Internal server exception. Please, contact your provider.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectServiceResponse'
              example:
                data: null
                messages:
                - message: Internal server exception. Please, contact your provider.
                  type: Error
                  errorCode: INTERNAL_SERVER_ERROR
        '410':
          description: Endpoint marked as deprecated was terminated. This response will be present only if the endpoint was marked as deprecated and has reached the sunset date. During the deprecation period, the API will include additional 'sunset' and 'deprecation' headers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StringServiceResponse'
              example:
                data: null
                messages:
                - message: This endpoint is obsolete and was terminated on yyyy-MM-dd
                  type: Error
                  errorCode: OBSOLETE_ENDPOINT
    servers:
    - url: /reportscommand
components:
  schemas:
    ServiceResponseMessage:
      type: object
      properties:
        message:
          type:
          - string
          - 'null'
        type:
          type:
          - string
          - 'null'
        errorCode:
          type:
          - string
          - 'null'
      additionalProperties: false
    CreateCategoryDto:
      required:
      - colour
      - name
      type: object
      properties:
        name:
          maxLength: 24
          minLength: 1
          type: string
          description: Category display name (max 24 characters)
        colour:
          minLength: 1
          type: string
          description: 'Hex colour code for the category badge (e.g. #FF5733)'
      additionalProperties: false
      description: Data required to create a new query category
    CreatedCategoryDtoServiceResponse:
      type: object
      properties:
        data:
          allOf:
          - $ref: '#/components/schemas/CreatedCategoryDto'
          description: Response returned after a category is created
        messages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ServiceResponseMessage'
      additionalProperties: false
    UpdateCategoryDtoServiceRequest:
      type: object
      properties:
        data:
          allOf:
          - $ref: '#/components/schemas/UpdateCategoryDto'
          description: Data for updating a query category
      additionalProperties: false
    UpdateCategoryDto:
      type: object
      properties:
        name:
          maxLength: 24
          type:
          - string
          - 'null'
          description: New display name (max 24 characters, optional — null preserves existing)
        colour:
          type:
          - string
          - 'null'
          description: 'New hex colour code (e.g. #FF5733, optional — null preserves existing)'
      additionalProperties: false
      description: Data for updating a query category
    ServiceResponse:
      type: object
      properties:
        data:
          type:
          - string
          - 'null'
        messages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ServiceResponseMessage'
      additionalProperties: false
    CreatedCategoryDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
      additionalProperties: false
      description: Response returned after a category is created
    ObjectServiceResponse:
      type: object
      properties:
        data: {}
        messages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ServiceResponseMessage'
      additionalProperties: false
    CreateCategoryDtoServiceRequest:
      type: object
      properties:
        data:
          allOf:
          - $ref: '#/components/schemas/CreateCategoryDto'
          description: Data required to create a new query category
      additionalProperties: false
    StringServiceResponse:
      type: object
      properties:
        data:
          type:
          - string
          - 'null'
        messages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ServiceResponseMessage'
      additionalProperties: false
    CategoryDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type:
          - string
          - 'null'
        colour:
          type:
          - string
          - 'null'
        queryCount:
          type: integer
          format: int32
      additionalProperties: false
      description: A single query category returned in the list
    CategoryDtoIEnumerableServiceResponse:
      type: object
      properties:
        data:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CategoryDto'
        messages:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ServiceResponseMessage'
      additionalProperties: false
  securitySchemes:
    Bearer:
      type: apiKey
      description: Please insert JWT with Bearer into field
      name: Authorization
      in: header
x-refined-from:
- fenergo-reportscommand-v2-0-openapi.json
- fenergo-reportsquery-v2-0-openapi.json