openapi: 3.0.1
info:
  title: Apiera REST API
  description: >-
    The Apiera REST API provides programmatic access to the Apiera platform,
    enabling seamless integration with your existing systems and workflows.
  version: 1.0.0
servers:
  - url: http://localhost:5281/
paths:
  /v1/tags:
    get:
      tags:
        - Tags
      summary: List tags
      description: Retrieves a paginated list of tags with optional filtering.
      parameters:
        - name: name[eq]
          in: query
          description: Filter by exact name match.
          schema:
            type: string
        - name: name[contains]
          in: query
          description: Filter by partial name match.
          schema:
            type: string
        - name: name[starts]
          in: query
          description: Filter by name prefix.
          schema:
            type: string
        - name: name[ends]
          in: query
          description: Filter by name suffix.
          schema:
            type: string
        - name: name[order]
          in: query
          description: 'Sort order for name field. Values: asc, desc.'
          schema:
            type: string
        - name: status[eq]
          in: query
          description: Filter by exact status match.
          schema:
            enum:
              - draft
              - published
              - unpublished
              - removed
            type: string
        - name: status[order]
          in: query
          description: 'Sort order for status field. Values: asc, desc.'
          schema:
            type: string
        - name: createdAt[eq]
          in: query
          description: Filter by exact creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[min]
          in: query
          description: Filter by minimum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[max]
          in: query
          description: Filter by maximum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[order]
          in: query
          description: 'Sort order for creation timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: updatedAt[eq]
          in: query
          description: Filter by exact update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[min]
          in: query
          description: Filter by minimum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[max]
          in: query
          description: Filter by maximum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[order]
          in: query
          description: 'Sort order for update timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: isRemoved[eq]
          in: query
          description: 'Filter by removed status. Values: true, false.'
          schema:
            type: boolean
        - name: page
          in: query
          description: Page number for pagination. Default is 1.
          schema:
            type: integer
            format: int32
        - name: size
          in: query
          description: Page size for pagination. Default is 20.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Successfully retrieved paginated list of tags.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfTagResponse'
              examples:
                published-tag:
                  summary: Published tag
                  description: Tag available for use on products
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Bestseller
                    description: Products with high sales volume
                draft-tag:
                  summary: Draft tag
                  description: Tag under development
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Limited Edition
                    description: Products available in limited quantities
                tag-without-description:
                  summary: Minimal tag
                  description: Tag with only required fields
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: New Arrival
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/tags
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/tags
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    post:
      tags:
        - Tags
      summary: Create tag
      description: Creates a new tag.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagCreateRequest'
        required: true
      responses:
        '201':
          description: Tag created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagResponse'
              examples:
                tag-with-description:
                  summary: Tag with description
                  description: New tag starts in draft status
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Bestseller
                    description: Products with high sales volume
                minimal-tag:
                  summary: Minimal tag
                  description: Tag with only required fields
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Sale
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/tags
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Conflict occurred.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/tags
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: TAG_NAME_TOO_LONG
                    message: Tag name must not exceed 100 characters.
                  - code: TAG_DESCRIPTION_TOO_LONG
                    message: Tag description must not exceed 500 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/tags
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/tags
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/tags/bulk:
    post:
      tags:
        - Tags
      summary: Bulk create tags
      description: Creates multiple tags in a single atomic operation.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TagBulkCreateRequest'
        required: true
      responses:
        '201':
          description: Tags created successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TagResponse'
              examples:
                multiple-tags:
                  summary: Multiple tags created
                  description: Batch creation of product tags
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      name: Bestseller
                      description: Products with high sales volume
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      name: New Arrival
                      description: Recently added products
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      name: Sale
                      description: Products currently on sale
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/tags/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Conflict occurred.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/tags/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: BULK_LIMIT_EXCEEDED
                    message: >-
                      The number of items exceeds the maximum allowed for bulk
                      operations.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/tags/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/tags/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Tags
      summary: Bulk update tags
      description: Updates multiple tags in a single operation.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/TagBulkUpdateRequest'
        required: true
      responses:
        '200':
          description: Tags updated successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TagResponse'
              examples:
                bulk-updated:
                  summary: Multiple tags updated
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      name: Top Seller
                      description: Products with highest sales volume
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      name: Fresh Arrival
                      description: Recently added products
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/tags/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/tags/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: BULK_LIMIT_EXCEEDED
                    message: >-
                      The number of items exceeds the maximum allowed for bulk
                      operations.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/tags/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/tags/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/tags/{tagUuid}:
    get:
      tags:
        - Tags
      summary: Get tag
      description: Retrieves complete details for a single tag.
      parameters:
        - name: tagUuid
          in: path
          description: Unique identifier of the tag.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved tag.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagResponse'
              examples:
                published-tag:
                  summary: Published tag
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Bestseller
                    description: Products with high sales volume
                draft-tag:
                  summary: Draft tag
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Limited Edition
                    description: Products available in limited quantities
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/tags/{tagUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Tag not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/tags/{tagUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/tags/{tagUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Tags
      summary: Update tag
      description: Updates an existing tag. Only provided fields are updated.
      parameters:
        - name: tagUuid
          in: path
          description: Unique identifier of the tag.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagUpdateRequest'
        required: true
      responses:
        '200':
          description: Tag updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagResponse'
              examples:
                updated-tag:
                  summary: Updated tag
                  description: Tag with modified properties
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Top Seller
                    description: Products with highest sales volume
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/tags/{tagUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Tag not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/tags/{tagUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/tags/{tagUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: TAG_NAME_TOO_LONG
                    message: Tag name must not exceed 100 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/tags/{tagUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/tags/{tagUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Tags
      summary: Delete tag
      description: Permanently deletes a tag. Cannot be undone.
      parameters:
        - name: tagUuid
          in: path
          description: Unique identifier of the tag.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Tag deleted successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/tags/{tagUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Tag not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/tags/{tagUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/tags/{tagUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/tags/{tagUuid}/actions/lifecycle:
    patch:
      tags:
        - Tags
      summary: Transition tag lifecycle
      description: >-
        Transitions a tag to a different lifecycle state. Valid transitions
        depend on current status.
      parameters:
        - name: tagUuid
          in: path
          description: Unique identifier of the tag.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagLifecycleRequest'
        required: true
      responses:
        '200':
          description: Tag transitioned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagResponse'
              examples:
                published:
                  summary: Transitioned to published
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Bestseller
                    description: Products with high sales volume
                unpublished:
                  summary: Transitioned to unpublished
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: unpublished
                    name: Bestseller
                    description: Products with high sales volume
                removed:
                  summary: Transitioned to removed
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    removedAt: '2025-11-20T13:00:00.000000Z'
                    status: removed
                    name: Bestseller
                    description: Products with high sales volume
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/tags/{tagUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Tag not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/tags/{tagUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Invalid transition for current status.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: TAG_INVALID_STAGE
                    message: Cannot transition from Published via Publish
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/tags/{tagUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/tags/{tagUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/tags/bulk/actions/lifecycle:
    patch:
      tags:
        - Tags
      summary: Bulk transition tag lifecycle
      description: >-
        Transitions multiple tags to a different lifecycle state in a single
        operation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagBulkLifecycleRequest'
        required: true
      responses:
        '200':
          description: Tags transitioned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TagResponse'
              examples:
                bulk-published:
                  summary: Multiple tags published
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      name: Bestseller
                      description: Products with high sales volume
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      name: New Arrival
                      description: Recently added products
                bulk-removed:
                  summary: Multiple tags removed
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      removedAt: '2025-11-20T13:00:00.000000Z'
                      status: removed
                      name: Bestseller
                      description: Products with high sales volume
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/tags/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Invalid transition.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: TAG_INVALID_STAGE
                    message: Cannot transition from Published via Publish
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/tags/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/tags/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/skus:
    get:
      tags:
        - Skus
      summary: List SKUs
      description: Retrieves a paginated list of SKUs with optional filtering.
      parameters:
        - name: code[eq]
          in: query
          description: Filter by exact code match.
          schema:
            type: string
        - name: code[contains]
          in: query
          description: Filter by partial code match.
          schema:
            type: string
        - name: code[starts]
          in: query
          description: Filter by code prefix.
          schema:
            type: string
        - name: code[ends]
          in: query
          description: Filter by code suffix.
          schema:
            type: string
        - name: code[order]
          in: query
          description: 'Sort order for code field. Values: asc, desc.'
          schema:
            type: string
        - name: status[eq]
          in: query
          description: Filter by exact status match.
          schema:
            enum:
              - draft
              - published
              - unpublished
              - removed
            type: string
        - name: status[order]
          in: query
          description: 'Sort order for status field. Values: asc, desc.'
          schema:
            type: string
        - name: createdAt[eq]
          in: query
          description: Filter by exact creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[min]
          in: query
          description: Filter by minimum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[max]
          in: query
          description: Filter by maximum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[order]
          in: query
          description: 'Sort order for creation timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: updatedAt[eq]
          in: query
          description: Filter by exact update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[min]
          in: query
          description: Filter by minimum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[max]
          in: query
          description: Filter by maximum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[order]
          in: query
          description: 'Sort order for update timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: isRemoved[eq]
          in: query
          description: 'Filter by removed status. Values: true, false.'
          schema:
            type: boolean
        - name: page
          in: query
          description: Page number for pagination. Default is 1.
          schema:
            type: integer
            format: int32
        - name: size
          in: query
          description: Page size for pagination. Default is 20.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Successfully retrieved paginated list of SKUs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfSkuResponse'
              examples:
                published-sku:
                  summary: Published SKU
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    code: SKU-LAPTOP-001
                draft-sku:
                  summary: Draft SKU
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    code: SKU-PHONE-002
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    post:
      tags:
        - Skus
      summary: Create SKU
      description: Creates a new SKU.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuCreateRequest'
        required: true
      responses:
        '201':
          description: SKU created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkuResponse'
              examples:
                new-sku:
                  summary: Newly created SKU
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    code: SKU-LAPTOP-001
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: SKU code already exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/skus
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: SKU_CODE_TOO_LONG
                    message: SKU code must not exceed 55 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/skus
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/skus/bulk:
    post:
      tags:
        - Skus
      summary: Bulk create SKUs
      description: Creates multiple SKUs in a single operation.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SkuBulkCreateRequest'
        required: true
      responses:
        '201':
          description: SKUs created successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuResponse'
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: One or more SKU codes already exist.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/skus/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: SKU_CODE_TOO_LONG
                    message: SKU code must not exceed 55 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/skus/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Skus
      summary: Bulk update SKUs
      description: Updates multiple SKUs in a single operation.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/SkuBulkUpdateRequest'
        required: true
      responses:
        '200':
          description: SKUs updated successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuResponse'
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/skus/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: SKU_CODE_TOO_LONG
                    message: SKU code must not exceed 55 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/skus/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/skus/{skuUuid}:
    get:
      tags:
        - Skus
      summary: Get SKU
      description: Retrieves complete details for a single SKU.
      parameters:
        - name: skuUuid
          in: path
          description: Unique identifier of the SKU.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved SKU.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkuResponse'
              examples:
                published-sku:
                  summary: Published SKU
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    code: SKU-LAPTOP-001
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/{skuUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: SKU not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/skus/{skuUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/{skuUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Skus
      summary: Update SKU
      description: Updates an existing SKU. Only provided fields are updated.
      parameters:
        - name: skuUuid
          in: path
          description: Unique identifier of the SKU.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuUpdateRequest'
        required: true
      responses:
        '200':
          description: SKU updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkuResponse'
              examples:
                updated-sku:
                  summary: Updated SKU
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    code: SKU-LAPTOP-001-V2
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/{skuUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: SKU not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/skus/{skuUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/skus/{skuUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: SKU_CODE_TOO_LONG
                    message: SKU code must not exceed 55 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/skus/{skuUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/{skuUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Skus
      summary: Delete SKU
      description: Permanently deletes a SKU. Cannot be undone.
      parameters:
        - name: skuUuid
          in: path
          description: Unique identifier of the SKU.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: SKU deleted successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/{skuUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: SKU not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/skus/{skuUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/{skuUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/skus/{skuUuid}/actions/lifecycle:
    patch:
      tags:
        - Skus
      summary: Transition SKU lifecycle
      description: >-
        Transitions a SKU to a different lifecycle state. Valid transitions
        depend on current status.
      parameters:
        - name: skuUuid
          in: path
          description: Unique identifier of the SKU.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuLifecycleRequest'
        required: true
      responses:
        '200':
          description: SKU transitioned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SkuResponse'
              examples:
                published:
                  summary: Transitioned to published
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    code: SKU-LAPTOP-001
                unpublished:
                  summary: Transitioned to unpublished
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: unpublished
                    code: SKU-LAPTOP-001
                removed:
                  summary: Transitioned to removed
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    removedAt: '2025-11-20T13:00:00.000000Z'
                    status: removed
                    code: SKU-LAPTOP-001
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/{skuUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: SKU not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/skus/{skuUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Invalid transition for current status.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: SKU_INVALID_STAGE
                    message: Cannot transition from Published via Publish
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/skus/{skuUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/{skuUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/skus/bulk/actions/lifecycle:
    patch:
      tags:
        - Skus
      summary: Bulk transition SKU lifecycle
      description: >-
        Transitions multiple SKUs to a different lifecycle state in a single
        operation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuBulkLifecycleRequest'
        required: true
      responses:
        '200':
          description: SKUs transitioned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SkuResponse'
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Invalid transition.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: SKU_INVALID_STAGE
                    message: Cannot transition from Published via Publish
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/skus/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/skus/{skuUuid}/dimension:
    post:
      tags:
        - Sku Dimensions
      summary: Set SKU dimensions
      description: >-
        Sets dimensions for a SKU. Values are provided in the organization's
        base dimension unit.
      parameters:
        - name: skuUuid
          in: path
          description: Unique identifier of the SKU.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DimensionCreateRequest'
        required: true
      responses:
        '201':
          description: Dimensions set successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DimensionResponse'
              examples:
                dimension-with-conversions:
                  summary: Dimensions with conversions
                  value:
                    skuUuid: 123e4567-e89b-12d3-a456-426614174001
                    unit: millimeter
                    length: 350
                    width: 250
                    height: 25
                    conversions:
                      centimeter:
                        length: 35
                        width: 25
                        height: 2.5
                      inch:
                        length: 13.78
                        width: 9.84
                        height: 0.98
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Dimensions already exist for this SKU.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: DIMENSION_VALUE_INVALID
                    message: Dimension value must not exceed 99999999999999.9999.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    get:
      tags:
        - Sku Dimensions
      summary: Get SKU dimensions
      description: Retrieves dimensions for a SKU including system-calculated conversions.
      parameters:
        - name: skuUuid
          in: path
          description: Unique identifier of the SKU.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved dimensions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DimensionResponse'
              examples:
                dimension-with-conversions:
                  summary: Dimensions with conversions
                  value:
                    skuUuid: 123e4567-e89b-12d3-a456-426614174001
                    unit: millimeter
                    length: 350
                    width: 250
                    height: 25
                    conversions:
                      centimeter:
                        length: 35
                        width: 25
                        height: 2.5
                      inch:
                        length: 13.78
                        width: 9.84
                        height: 0.98
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: SKU or dimensions not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Sku Dimensions
      summary: Update SKU dimensions
      description: Updates dimensions for a SKU. Only provided fields are updated.
      parameters:
        - name: skuUuid
          in: path
          description: Unique identifier of the SKU.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DimensionUpdateRequest'
        required: true
      responses:
        '200':
          description: Dimensions updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DimensionResponse'
              examples:
                updated-dimensions:
                  summary: Updated dimensions
                  value:
                    skuUuid: 123e4567-e89b-12d3-a456-426614174001
                    unit: millimeter
                    length: 400
                    width: 320
                    height: 30
                    conversions:
                      centimeter:
                        length: 40
                        width: 32
                        height: 3
                      inch:
                        length: 15.75
                        width: 12.6
                        height: 1.18
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: SKU or dimensions not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: DIMENSION_VALUE_INVALID
                    message: Dimension value must not exceed 99999999999999.9999.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Sku Dimensions
      summary: Delete SKU dimensions
      description: Removes dimensions from a SKU.
      parameters:
        - name: skuUuid
          in: path
          description: Unique identifier of the SKU.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Dimensions deleted successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: SKU or dimensions not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/{skuUuid}/dimension
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/skus/{skuUuid}/weight:
    post:
      tags:
        - Sku Weights
      summary: Set SKU weight
      description: >-
        Sets weight for a SKU. Value is provided in the organization's base
        weight unit.
      parameters:
        - name: skuUuid
          in: path
          description: Unique identifier of the SKU.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WeightCreateRequest'
        required: true
      responses:
        '201':
          description: Weight set successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeightResponse'
              examples:
                weight-with-conversions:
                  summary: Weight with conversions
                  value:
                    skuUuid: 123e4567-e89b-12d3-a456-426614174001
                    unit: gram
                    weight: 1850
                    conversions:
                      kilogram: 1.85
                      ounce: 65.26
                      pound: 4.08
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Weight already exists for this SKU.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: WEIGHT_VALUE_INVALID
                    message: Weight value must not exceed 99999999999999.9999.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    get:
      tags:
        - Sku Weights
      summary: Get SKU weight
      description: Retrieves weight for a SKU including system-calculated conversions.
      parameters:
        - name: skuUuid
          in: path
          description: Unique identifier of the SKU.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved weight.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeightResponse'
              examples:
                weight-with-conversions:
                  summary: Weight with conversions
                  value:
                    skuUuid: 123e4567-e89b-12d3-a456-426614174001
                    unit: gram
                    weight: 1850
                    conversions:
                      kilogram: 1.85
                      ounce: 65.26
                      pound: 4.08
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: SKU or weight not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Sku Weights
      summary: Update SKU weight
      description: Updates weight for a SKU.
      parameters:
        - name: skuUuid
          in: path
          description: Unique identifier of the SKU.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WeightUpdateRequest'
        required: true
      responses:
        '200':
          description: Weight updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeightResponse'
              examples:
                updated-weight:
                  summary: Updated weight
                  value:
                    skuUuid: 123e4567-e89b-12d3-a456-426614174001
                    unit: gram
                    weight: 2500
                    conversions:
                      kilogram: 2.5
                      ounce: 88.18
                      pound: 5.51
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: SKU or weight not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: WEIGHT_VALUE_INVALID
                    message: Weight value must not exceed 99999999999999.9999.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Sku Weights
      summary: Delete SKU weight
      description: Removes weight from a SKU.
      parameters:
        - name: skuUuid
          in: path
          description: Unique identifier of the SKU.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Weight deleted successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: SKU or weight not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/skus/{skuUuid}/weight
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/families/{familyUuid}/attributes:
    get:
      tags:
        - Family Attributes
      summary: List family attributes
      description: Retrieves a paginated list of attribute associations for a family.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          description: Page number for pagination. Default is 1.
          schema:
            type: integer
            format: int32
            default: 1
        - name: size
          in: query
          description: Page size for pagination. Default is 20.
          schema:
            type: integer
            format: int32
            default: 20
      responses:
        '200':
          description: Successfully retrieved attribute associations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfFamilyAttributeResponse'
              examples:
                attribute-associations:
                  summary: Family attribute associations
                  description: List of attributes associated with this family
                  value:
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      requirementLevel: must
                      isAutoPopulated: false
                      attributeName: Brand
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      requirementLevel: must
                      isAutoPopulated: false
                      attributeName: Model Number
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      requirementLevel: should
                      isAutoPopulated: false
                      attributeName: Color
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/attributes
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/attributes
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    post:
      tags:
        - Family Attributes
      summary: Associate attribute with family
      description: Creates a new attribute association for a family.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyAttributeCreateRequest'
        required: true
      responses:
        '201':
          description: Attribute association created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyAttributeResponse'
              examples:
                required-attribute:
                  summary: Required attribute
                  description: Attribute that must be provided for product completeness
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    familyUuid: 123e4567-e89b-12d3-a456-426614174001
                    attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    requirementLevel: must
                    isAutoPopulated: false
                    attributeName: Brand
                auto-populated-attribute:
                  summary: Auto-populated attribute
                  description: Attribute automatically added to new products
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    familyUuid: 123e4567-e89b-12d3-a456-426614174001
                    attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    requirementLevel: must
                    isAutoPopulated: true
                    attributeName: Product Type
                optional-attribute:
                  summary: Optional attribute
                  description: Attribute that may be provided
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    familyUuid: 123e4567-e89b-12d3-a456-426614174001
                    attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    requirementLevel: may
                    isAutoPopulated: false
                    attributeName: Warranty Period
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/attributes
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Attribute already associated with this family.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/families/{familyUuid}/attributes
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ATTRIBUTE_NOT_FOUND
                    message: The specified attribute does not exist.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/{familyUuid}/attributes
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/attributes
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/families/{familyUuid}/attributes/{familyAttributeUuid}:
    get:
      tags:
        - Family Attributes
      summary: Get family attribute association
      description: Retrieves a single attribute association for a family.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
        - name: familyAttributeUuid
          in: path
          description: Unique identifier of the attribute association.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved attribute association.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyAttributeResponse'
              examples:
                attribute-association:
                  summary: Attribute association
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    familyUuid: 123e4567-e89b-12d3-a456-426614174001
                    attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    requirementLevel: must
                    isAutoPopulated: false
                    attributeName: Brand
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/attributes/{familyAttributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Attribute association not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/families/{familyUuid}/attributes/{familyAttributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/attributes/{familyAttributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Family Attributes
      summary: Update family attribute association
      description: >-
        Updates an existing attribute association. Only provided fields are
        updated.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
        - name: familyAttributeUuid
          in: path
          description: Unique identifier of the attribute association.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyAttributeUpdateRequest'
        required: true
      responses:
        '200':
          description: Attribute association updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyAttributeResponse'
              examples:
                updated-association:
                  summary: Updated attribute association
                  description: Association with modified requirement level
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    familyUuid: 123e4567-e89b-12d3-a456-426614174001
                    attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    requirementLevel: should
                    isAutoPopulated: false
                    attributeName: Brand
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/attributes/{familyAttributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Attribute association not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/families/{familyUuid}/attributes/{familyAttributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/families/{familyUuid}/attributes/{familyAttributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: INVALID_REQUIREMENT_LEVEL
                    message: The specified requirement level is not valid.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/{familyUuid}/attributes/{familyAttributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/attributes/{familyAttributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Family Attributes
      summary: Remove attribute from family
      description: Permanently removes an attribute association from a family.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
        - name: familyAttributeUuid
          in: path
          description: Unique identifier of the attribute association.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Attribute association removed successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/attributes/{familyAttributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Attribute association not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/families/{familyUuid}/attributes/{familyAttributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/attributes/{familyAttributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/families/{familyUuid}/attributes/bulk:
    post:
      tags:
        - Family Attributes
      summary: Bulk associate attributes with family
      description: >-
        Creates multiple attribute associations for a family in a single
        operation.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FamilyAttributeBulkCreateRequest'
        required: true
      responses:
        '201':
          description: Attribute associations created successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FamilyAttributeResponse'
              examples:
                multiple-attributes:
                  summary: Multiple attribute associations
                  description: Bulk creation of attribute requirements
                  value:
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      requirementLevel: must
                      isAutoPopulated: false
                      attributeName: Brand
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      requirementLevel: must
                      isAutoPopulated: false
                      attributeName: Model Number
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      requirementLevel: should
                      isAutoPopulated: false
                      attributeName: Color
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      requirementLevel: may
                      isAutoPopulated: false
                      attributeName: Warranty Period
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: One or more attributes already associated.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/families/{familyUuid}/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: BULK_LIMIT_EXCEEDED
                    message: >-
                      The number of items exceeds the maximum allowed for bulk
                      operations.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/{familyUuid}/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Family Attributes
      summary: Bulk update family attribute associations
      description: Updates multiple attribute associations in a single operation.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FamilyAttributeBulkUpdateRequest'
        required: true
      responses:
        '200':
          description: Attribute associations updated successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FamilyAttributeResponse'
              examples:
                bulk-updated:
                  summary: Multiple associations updated
                  value:
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      requirementLevel: should
                      isAutoPopulated: false
                      attributeName: Brand
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      attributeUuid: ddd44444-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      requirementLevel: must
                      isAutoPopulated: true
                      attributeName: Model Number
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/families/{familyUuid}/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: BULK_LIMIT_EXCEEDED
                    message: >-
                      The number of items exceeds the maximum allowed for bulk
                      operations.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/{familyUuid}/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/families/{familyUuid}/categories:
    get:
      tags:
        - Family Categories
      summary: List family categories
      description: Retrieves a paginated list of category associations for a family.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          description: Page number for pagination. Default is 1.
          schema:
            type: integer
            format: int32
            default: 1
        - name: size
          in: query
          description: Page size for pagination. Default is 20.
          schema:
            type: integer
            format: int32
            default: 20
      responses:
        '200':
          description: Successfully retrieved category associations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfFamilyCategoryResponse'
              examples:
                category-associations:
                  summary: Family category associations
                  description: List of categories associated with this family
                  value:
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      categoryUuid: ccc33333-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      requirementLevel: must
                      isAutoPopulated: true
                      categoryName: Consumer Electronics
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      categoryUuid: ccc33333-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      requirementLevel: should
                      isAutoPopulated: false
                      categoryName: Computers
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/categories
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/categories
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    post:
      tags:
        - Family Categories
      summary: Associate category with family
      description: Creates a new category association for a family.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyCategoryCreateRequest'
        required: true
      responses:
        '201':
          description: Category association created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyCategoryResponse'
              examples:
                required-category:
                  summary: Required category
                  description: Category that must be assigned to products
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    familyUuid: 123e4567-e89b-12d3-a456-426614174001
                    categoryUuid: ccc33333-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    requirementLevel: must
                    isAutoPopulated: true
                    categoryName: Consumer Electronics
                optional-category:
                  summary: Optional category
                  description: Category that may be assigned to products
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    familyUuid: 123e4567-e89b-12d3-a456-426614174001
                    categoryUuid: ccc33333-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    requirementLevel: may
                    isAutoPopulated: false
                    categoryName: Premium Products
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/categories
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Category already associated with this family.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/families/{familyUuid}/categories
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: CATEGORY_NOT_FOUND
                    message: The specified category does not exist.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/{familyUuid}/categories
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/categories
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/families/{familyUuid}/categories/{familyCategoryUuid}:
    get:
      tags:
        - Family Categories
      summary: Get family category association
      description: Retrieves a single category association for a family.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
        - name: familyCategoryUuid
          in: path
          description: Unique identifier of the category association.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved category association.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyCategoryResponse'
              examples:
                category-association:
                  summary: Category association
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    familyUuid: 123e4567-e89b-12d3-a456-426614174001
                    categoryUuid: ccc33333-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    requirementLevel: must
                    isAutoPopulated: true
                    categoryName: Consumer Electronics
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/categories/{familyCategoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Category association not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/families/{familyUuid}/categories/{familyCategoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/categories/{familyCategoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Family Categories
      summary: Update family category association
      description: >-
        Updates an existing category association. Only provided fields are
        updated.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
        - name: familyCategoryUuid
          in: path
          description: Unique identifier of the category association.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyCategoryUpdateRequest'
        required: true
      responses:
        '200':
          description: Category association updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyCategoryResponse'
              examples:
                updated-association:
                  summary: Updated category association
                  description: Association with modified requirement level
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    familyUuid: 123e4567-e89b-12d3-a456-426614174001
                    categoryUuid: ccc33333-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    requirementLevel: should
                    isAutoPopulated: true
                    categoryName: Consumer Electronics
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/categories/{familyCategoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Category association not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/families/{familyUuid}/categories/{familyCategoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/families/{familyUuid}/categories/{familyCategoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: INVALID_REQUIREMENT_LEVEL
                    message: The specified requirement level is not valid.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/{familyUuid}/categories/{familyCategoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/categories/{familyCategoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Family Categories
      summary: Remove category from family
      description: Permanently removes a category association from a family.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
        - name: familyCategoryUuid
          in: path
          description: Unique identifier of the category association.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Category association removed successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/categories/{familyCategoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Category association not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/families/{familyUuid}/categories/{familyCategoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/categories/{familyCategoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/families/{familyUuid}/categories/bulk:
    post:
      tags:
        - Family Categories
      summary: Bulk associate categories with family
      description: >-
        Creates multiple category associations for a family in a single
        operation.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FamilyCategoryBulkCreateRequest'
        required: true
      responses:
        '201':
          description: Category associations created successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FamilyCategoryResponse'
              examples:
                multiple-categories:
                  summary: Multiple category associations
                  description: Bulk creation of category requirements
                  value:
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      categoryUuid: ccc33333-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      requirementLevel: must
                      isAutoPopulated: true
                      categoryName: Consumer Electronics
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      categoryUuid: ccc33333-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      requirementLevel: should
                      isAutoPopulated: false
                      categoryName: Computers
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      categoryUuid: ccc33333-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      requirementLevel: may
                      isAutoPopulated: false
                      categoryName: Premium Products
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: One or more categories already associated.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/families/{familyUuid}/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: BULK_LIMIT_EXCEEDED
                    message: >-
                      The number of items exceeds the maximum allowed for bulk
                      operations.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/{familyUuid}/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Family Categories
      summary: Bulk update family category associations
      description: Updates multiple category associations in a single operation.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FamilyCategoryBulkUpdateRequest'
        required: true
      responses:
        '200':
          description: Category associations updated successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FamilyCategoryResponse'
              examples:
                bulk-updated:
                  summary: Multiple associations updated
                  value:
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      categoryUuid: ccc33333-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      requirementLevel: should
                      isAutoPopulated: true
                      categoryName: Consumer Electronics
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      familyUuid: 123e4567-e89b-12d3-a456-426614174001
                      categoryUuid: ccc33333-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      requirementLevel: must
                      isAutoPopulated: true
                      categoryName: Computers
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/families/{familyUuid}/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: BULK_LIMIT_EXCEEDED
                    message: >-
                      The number of items exceeds the maximum allowed for bulk
                      operations.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/{familyUuid}/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/families:
    get:
      tags:
        - Families
      summary: List families
      description: Retrieves a paginated list of families with optional filtering.
      parameters:
        - name: name[eq]
          in: query
          description: Filter by exact name match.
          schema:
            type: string
        - name: name[contains]
          in: query
          description: Filter by partial name match.
          schema:
            type: string
        - name: name[starts]
          in: query
          description: Filter by name prefix.
          schema:
            type: string
        - name: name[ends]
          in: query
          description: Filter by name suffix.
          schema:
            type: string
        - name: name[order]
          in: query
          description: 'Sort order for name field. Values: asc, desc.'
          schema:
            type: string
        - name: status[eq]
          in: query
          description: Filter by exact status match.
          schema:
            enum:
              - draft
              - active
              - inactive
              - removed
            type: string
        - name: status[order]
          in: query
          description: 'Sort order for status field. Values: asc, desc.'
          schema:
            type: string
        - name: parentUuid[eq]
          in: query
          description: Filter by parent family UUID.
          schema:
            type: string
            format: uuid
        - name: isRemoved[eq]
          in: query
          description: 'Filter by removed status. Values: true, false.'
          schema:
            type: boolean
        - name: createdAt[eq]
          in: query
          description: Filter by exact creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[min]
          in: query
          description: Filter by minimum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[max]
          in: query
          description: Filter by maximum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[order]
          in: query
          description: 'Sort order for creation timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: updatedAt[eq]
          in: query
          description: Filter by exact update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[min]
          in: query
          description: Filter by minimum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[max]
          in: query
          description: Filter by maximum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[order]
          in: query
          description: 'Sort order for update timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: page
          in: query
          description: Page number for pagination. Default is 1.
          schema:
            type: integer
            format: int32
        - name: size
          in: query
          description: Page size for pagination. Default is 20.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Successfully retrieved paginated list of families.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfFamilyResponse'
              examples:
                active-family:
                  summary: Active family
                  description: Family in active status ready for use
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: active
                    name: Electronics
                    description: Product family for electronics catalog
                draft-family:
                  summary: Draft family
                  description: Family under construction
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Apparel
                    description: Product family for apparel catalog
                hierarchical-family:
                  summary: Child family
                  description: Family with parent relationship
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    parentUuid: 11111111-e89b-12d3-a456-426614174000
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: active
                    name: Laptops
                    description: Product family for laptops catalog
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    post:
      tags:
        - Families
      summary: Create family
      description: >-
        Creates a new family. Categories and attributes must be added separately
        after creation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyCreateRequest'
        required: true
      responses:
        '201':
          description: Family created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyResponse'
              examples:
                root-family:
                  summary: Root family created
                  description: New family without parent relationship
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Electronics
                    description: Product family for electronics catalog
                child-family:
                  summary: Child family created
                  description: New family with parent hierarchy
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    parentUuid: 11111111-e89b-12d3-a456-426614174000
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Laptops
                    description: Product family for laptops catalog
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Conflict occurred.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/families
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: FAMILY_NAME_TOO_LONG
                    message: Family name must not exceed 255 characters.
                  - code: FAMILY_DESCRIPTION_TOO_LONG
                    message: Family description must not exceed 1000 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/families/{familyUuid}:
    get:
      tags:
        - Families
      summary: Get family
      description: Retrieves complete details for a single family.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved family.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyResponse'
              examples:
                active-family:
                  summary: Active family
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: active
                    name: Electronics
                    description: Product family for electronics catalog
                hierarchical-family:
                  summary: Child family with parent
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    parentUuid: 11111111-e89b-12d3-a456-426614174000
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: active
                    name: Laptops
                    description: Product family for laptops catalog
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Family not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/families/{familyUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Families
      summary: Update family
      description: Updates an existing family. Only provided fields are updated.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyUpdateRequest'
        required: true
      responses:
        '200':
          description: Family updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyResponse'
              examples:
                updated-family:
                  summary: Updated family
                  description: Family with modified properties
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: active
                    name: Electronics - Updated
                    description: Product family for electronics - updated catalog
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Family not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/families/{familyUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/families/{familyUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: FAMILY_NAME_TOO_LONG
                    message: Family name must not exceed 255 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/{familyUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Families
      summary: Delete family
      description: Permanently deletes a family. Cannot be undone.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Family deleted successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Family not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/families/{familyUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/families/bulk:
    post:
      tags:
        - Families
      summary: Bulk create families
      description: Creates multiple families in a single atomic operation.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FamilyBulkCreateRequest'
        required: true
      responses:
        '201':
          description: Families created successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FamilyResponse'
              examples:
                multiple-families:
                  summary: Multiple families created
                  description: Batch creation of different family types
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      name: Electronics
                      description: Product family for electronics catalog
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      name: Apparel
                      description: Product family for apparel catalog
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      name: Home & Garden
                      description: Product family for home & garden catalog
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Conflict occurred.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/families/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: FAMILY_NAME_TOO_LONG
                    message: Family name must not exceed 255 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Families
      summary: Bulk update families
      description: Updates multiple families in a single operation.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FamilyBulkUpdateRequest'
        required: true
      responses:
        '200':
          description: Families updated successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FamilyResponse'
              examples:
                bulk-updated:
                  summary: Multiple families updated
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: active
                      name: Electronics - Updated
                      description: Product family for electronics - updated catalog
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: active
                      name: Apparel - Updated
                      description: Product family for apparel - updated catalog
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/families/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: FAMILY_NAME_TOO_LONG
                    message: Family name must not exceed 255 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/families/{familyUuid}/actions/lifecycle:
    patch:
      tags:
        - Families
      summary: Transition family lifecycle
      description: >-
        Transitions a family to a different lifecycle state. Valid transitions
        depend on current status.
      parameters:
        - name: familyUuid
          in: path
          description: Unique identifier of the family.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyLifecycleRequest'
        required: true
      responses:
        '200':
          description: Family transitioned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FamilyResponse'
              examples:
                activated:
                  summary: Transitioned to active
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: active
                    name: Electronics
                    description: Product family for electronics catalog
                deactivated:
                  summary: Transitioned to inactive
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: inactive
                    name: Electronics
                    description: Product family for electronics catalog
                removed:
                  summary: Transitioned to removed
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    removedAt: '2025-11-20T13:00:00.000000Z'
                    status: removed
                    name: Electronics
                    description: Product family for electronics catalog
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/{familyUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Family not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/families/{familyUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Invalid transition for current status.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: FAMILY_INVALID_STAGE
                    message: Cannot transition from Active via Activate
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/{familyUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/{familyUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/families/bulk/actions/lifecycle:
    patch:
      tags:
        - Families
      summary: Bulk transition family lifecycle
      description: >-
        Transitions multiple families to a different lifecycle state in a single
        operation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FamilyBulkLifecycleRequest'
        required: true
      responses:
        '200':
          description: Families transitioned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FamilyResponse'
              examples:
                bulk-activated:
                  summary: Multiple families activated
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: active
                      name: Electronics
                      description: Product family for electronics catalog
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: active
                      name: Apparel
                      description: Product family for apparel catalog
                bulk-removed:
                  summary: Multiple families removed
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      removedAt: '2025-11-20T13:00:00.000000Z'
                      status: removed
                      name: Electronics
                      description: Product family for electronics catalog
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/families/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Invalid transition.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: FAMILY_INVALID_STAGE
                    message: Cannot transition from Active via Activate
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/families/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/families/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/organizations/current/members:
    get:
      tags:
        - Organization Members
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            default: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            default: 20
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfMemberResponse'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
    post:
      tags:
        - Organization Members
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberCreateRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberResponse'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
  /v1/organizations/current/members/{accountUuid}:
    get:
      tags:
        - Organization Members
      parameters:
        - name: accountUuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberResponse'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
    delete:
      tags:
        - Organization Members
      parameters:
        - name: accountUuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
  /v1/organizations/current/members/{accountUuid}/role:
    patch:
      tags:
        - Organization Members
      parameters:
        - name: accountUuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberChangeRoleRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberResponse'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
  /v1/organizations/current/members/{accountUuid}/actions/lifecycle:
    patch:
      tags:
        - Organization Members
      parameters:
        - name: accountUuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberLifecycleRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberResponse'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
  /v1/organizations/current:
    get:
      tags:
        - Organizations
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationResponse'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
    patch:
      tags:
        - Organizations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationUpdateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationResponse'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
  /v1/organizations/current/roles:
    get:
      tags:
        - Organization Roles
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            default: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            default: 20
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfRoleResponse'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
    post:
      tags:
        - Organization Roles
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleCreateRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
  /v1/organizations/current/roles/{organizationRoleUuid}:
    get:
      tags:
        - Organization Roles
      parameters:
        - name: organizationRoleUuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
    patch:
      tags:
        - Organization Roles
      parameters:
        - name: organizationRoleUuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RoleUpdateRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleResponse'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
    delete:
      tags:
        - Organization Roles
      parameters:
        - name: organizationRoleUuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '422':
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
  /v1/organizations/current/roles/{organizationRoleUuid}/permissions/{permissionUuid}:
    post:
      tags:
        - Organization Roles
      parameters:
        - name: organizationRoleUuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: permissionUuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '409':
          description: Conflict
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
    delete:
      tags:
        - Organization Roles
      parameters:
        - name: organizationRoleUuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: permissionUuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
      security:
        - Bearer: []
  /v1/categories:
    get:
      tags:
        - Categories
      summary: List categories
      description: Retrieves a paginated list of categories with optional filtering.
      parameters:
        - name: parentUuid[eq]
          in: query
          description: Filter by parent category UUID.
          schema:
            type: string
            format: uuid
        - name: name[eq]
          in: query
          description: Filter by exact name match.
          schema:
            type: string
        - name: name[contains]
          in: query
          description: Filter by partial name match.
          schema:
            type: string
        - name: name[starts]
          in: query
          description: Filter by name prefix.
          schema:
            type: string
        - name: name[ends]
          in: query
          description: Filter by name suffix.
          schema:
            type: string
        - name: name[order]
          in: query
          description: 'Sort order for name field. Values: asc, desc.'
          schema:
            type: string
        - name: status[eq]
          in: query
          description: Filter by exact status match.
          schema:
            enum:
              - draft
              - published
              - unpublished
              - removed
            type: string
        - name: status[order]
          in: query
          description: 'Sort order for status field. Values: asc, desc.'
          schema:
            type: string
        - name: createdAt[eq]
          in: query
          description: Filter by exact creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[min]
          in: query
          description: Filter by minimum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[max]
          in: query
          description: Filter by maximum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[order]
          in: query
          description: 'Sort order for creation timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: updatedAt[eq]
          in: query
          description: Filter by exact update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[min]
          in: query
          description: Filter by minimum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[max]
          in: query
          description: Filter by maximum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[order]
          in: query
          description: 'Sort order for update timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: isRemoved[eq]
          in: query
          description: 'Filter by removed status. Values: true, false.'
          schema:
            type: boolean
        - name: page
          in: query
          description: Page number for pagination. Default is 1.
          schema:
            type: integer
            format: int32
        - name: size
          in: query
          description: Page size for pagination. Default is 20.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Successfully retrieved paginated list of categories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfCategoryResponse'
              examples:
                published-category:
                  summary: Published category
                  description: Category available for product assignment
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Electronics
                    description: Product category for electronics
                draft-category:
                  summary: Draft category
                  description: Category under construction
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Home & Garden
                    description: Product category for home & garden
                hierarchical-category:
                  summary: Child category
                  description: Category with parent relationship
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    parentUuid: 11111111-e89b-12d3-a456-426614174000
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Laptops
                    description: Product category for laptops
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/categories
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/categories
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    post:
      tags:
        - Categories
      summary: Create category
      description: Creates a new category.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryCreateRequest'
        required: true
      responses:
        '201':
          description: Category created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
              examples:
                root-category:
                  summary: Root category created
                  description: New category without parent relationship
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Electronics
                    description: Product category for electronics
                child-category:
                  summary: Child category created
                  description: New category with parent hierarchy
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    parentUuid: 11111111-e89b-12d3-a456-426614174000
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Laptops
                    description: Product category for laptops
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/categories
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Conflict occurred.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/categories
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: CATEGORY_NAME_TOO_LONG
                    message: Category name must not exceed 255 characters.
                  - code: CATEGORY_DESCRIPTION_TOO_LONG
                    message: Category description must not exceed 1000 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/categories
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/categories
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/categories/bulk:
    post:
      tags:
        - Categories
      summary: Bulk create categories
      description: Creates multiple categories in a single atomic operation.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CategoryBulkCreateRequest'
        required: true
      responses:
        '201':
          description: Categories created successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryResponse'
              examples:
                multiple-categories:
                  summary: Multiple categories created
                  description: Batch creation of product categories
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      name: Electronics
                      description: Product category for electronics
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      name: Clothing
                      description: Product category for clothing
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      name: Home & Garden
                      description: Product category for home & garden
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Conflict occurred.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: CATEGORY_NAME_TOO_LONG
                    message: Category name must not exceed 255 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Categories
      summary: Bulk update categories
      description: Updates multiple categories in a single operation.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CategoryBulkUpdateRequest'
        required: true
      responses:
        '200':
          description: Categories updated successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryResponse'
              examples:
                bulk-updated:
                  summary: Multiple categories updated
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      name: Electronics - Updated
                      description: Product category for electronics - updated
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      name: Clothing - Updated
                      description: Product category for clothing - updated
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: CATEGORY_NAME_TOO_LONG
                    message: Category name must not exceed 255 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/categories/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/categories/{categoryUuid}:
    get:
      tags:
        - Categories
      summary: Get category
      description: Retrieves complete details for a single category.
      parameters:
        - name: categoryUuid
          in: path
          description: Unique identifier of the category.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
              examples:
                published-category:
                  summary: Published category
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Electronics
                    description: Consumer electronics and accessories
                draft-category:
                  summary: Draft category
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Seasonal
                    description: Seasonal and holiday products
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/categories/{categoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Category not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/categories/{categoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/categories/{categoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Categories
      summary: Update category
      description: Updates an existing category. Only provided fields are updated.
      parameters:
        - name: categoryUuid
          in: path
          description: Unique identifier of the category.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryUpdateRequest'
        required: true
      responses:
        '200':
          description: Category updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
              examples:
                updated-category:
                  summary: Updated category
                  description: Category with modified properties
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Electronics - Updated
                    description: Product category for electronics - updated
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/categories/{categoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Category not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/categories/{categoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/categories/{categoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: CATEGORY_NAME_TOO_LONG
                    message: Category name must not exceed 255 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/categories/{categoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/categories/{categoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Categories
      summary: Delete category
      description: Permanently deletes a category. Cannot be undone.
      parameters:
        - name: categoryUuid
          in: path
          description: Unique identifier of the category.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Category deleted successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/categories/{categoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Category not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/categories/{categoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/categories/{categoryUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/categories/{categoryUuid}/actions/lifecycle:
    patch:
      tags:
        - Categories
      summary: Transition category lifecycle
      description: >-
        Transitions a category to a different lifecycle state. Valid transitions
        depend on current status.
      parameters:
        - name: categoryUuid
          in: path
          description: Unique identifier of the category.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryLifecycleRequest'
        required: true
      responses:
        '200':
          description: Category transitioned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryResponse'
              examples:
                published:
                  summary: Category published
                  description: Category transitioned from draft to published
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Electronics
                    description: Product category for electronics
                removed:
                  summary: Category removed
                  description: Category marked as removed
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    removedAt: '2025-11-20T13:00:00.000000Z'
                    status: removed
                    name: Discontinued
                    description: Product category for discontinued
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/categories/{categoryUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Category not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/categories/{categoryUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Invalid transition.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: CATEGORY_INVALID_STAGE
                    message: Cannot transition from Published via Publish
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/categories/{categoryUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/categories/{categoryUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/categories/bulk/actions/lifecycle:
    patch:
      tags:
        - Categories
      summary: Bulk transition category lifecycle
      description: >-
        Transitions multiple categories to a different lifecycle state in a
        single operation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryBulkLifecycleRequest'
        required: true
      responses:
        '200':
          description: Categories transitioned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoryResponse'
              examples:
                bulk-published:
                  summary: Multiple categories published
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      name: Electronics
                      description: Product category for electronics
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      name: Clothing
                      description: Product category for clothing
                bulk-removed:
                  summary: Multiple categories removed
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      removedAt: '2025-11-20T13:00:00.000000Z'
                      status: removed
                      name: Electronics
                      description: Product category for electronics
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/categories/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Invalid transition.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: CATEGORY_INVALID_STAGE
                    message: Cannot transition from Published via Publish
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/categories/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/categories/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/attributes:
    get:
      tags:
        - Attributes
      summary: List attributes
      description: Retrieves a paginated list of attributes with optional filtering.
      parameters:
        - name: name[eq]
          in: query
          description: Filter by exact name match.
          schema:
            type: string
        - name: name[contains]
          in: query
          description: Filter by partial name match.
          schema:
            type: string
        - name: name[starts]
          in: query
          description: Filter by name prefix.
          schema:
            type: string
        - name: name[ends]
          in: query
          description: Filter by name suffix.
          schema:
            type: string
        - name: name[order]
          in: query
          description: 'Sort order for name field. Values: asc, desc.'
          schema:
            type: string
        - name: status[eq]
          in: query
          description: Filter by exact status match.
          schema:
            enum:
              - draft
              - published
              - unpublished
              - removed
            type: string
        - name: status[order]
          in: query
          description: 'Sort order for status field. Values: asc, desc.'
          schema:
            type: string
        - name: createdAt[eq]
          in: query
          description: Filter by exact creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[min]
          in: query
          description: Filter by minimum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[max]
          in: query
          description: Filter by maximum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[order]
          in: query
          description: 'Sort order for creation timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: updatedAt[eq]
          in: query
          description: Filter by exact update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[min]
          in: query
          description: Filter by minimum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[max]
          in: query
          description: Filter by maximum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[order]
          in: query
          description: 'Sort order for update timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: isRemoved[eq]
          in: query
          description: 'Filter by removed status. Values: true, false.'
          schema:
            type: boolean
        - name: page
          in: query
          description: Page number for pagination. Default is 1.
          schema:
            type: integer
            format: int32
        - name: size
          in: query
          description: Page size for pagination. Default is 20.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Successfully retrieved paginated list of attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfAttributeResponse'
              examples:
                published-attribute:
                  summary: Published attribute
                  description: Attribute available for use in products
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Brand
                    description: Product manufacturer or brand name
                draft-attribute:
                  summary: Draft attribute
                  description: Attribute under development
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Warranty Period
                    description: Length of manufacturer warranty
                attribute-without-description:
                  summary: Minimal attribute
                  description: Attribute with only required fields
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Color
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    post:
      tags:
        - Attributes
      summary: Create attribute
      description: Creates a new attribute. Terms must be added separately after creation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributeCreateRequest'
        required: true
      responses:
        '201':
          description: Attribute created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeResponse'
              examples:
                attribute-with-description:
                  summary: Attribute with description
                  description: New attribute starts in draft status
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Brand
                    description: Product manufacturer or brand name
                minimal-attribute:
                  summary: Minimal attribute
                  description: Attribute with only required fields
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Color
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Conflict occurred.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/attributes
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ATTRIBUTE_NAME_TOO_LONG
                    message: Attribute name must not exceed 100 characters.
                  - code: ATTRIBUTE_DESCRIPTION_TOO_LONG
                    message: Attribute description must not exceed 500 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/attributes
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/attributes/bulk:
    post:
      tags:
        - Attributes
      summary: Bulk create attributes
      description: Creates multiple attributes in a single atomic operation.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AttributeBulkCreateRequest'
        required: true
      responses:
        '201':
          description: Attributes created successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AttributeResponse'
              examples:
                multiple-attributes:
                  summary: Multiple attributes created
                  description: Batch creation of product attributes
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      name: Brand
                      description: Product manufacturer or brand name
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      name: Color
                      description: Product color or finish
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      name: Material
                      description: Primary material composition
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Conflict occurred.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: BULK_LIMIT_EXCEEDED
                    message: >-
                      The number of items exceeds the maximum allowed for bulk
                      operations.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Attributes
      summary: Bulk update attributes
      description: Updates multiple attributes in a single operation.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AttributeBulkUpdateRequest'
        required: true
      responses:
        '200':
          description: Attributes updated successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AttributeResponse'
              examples:
                bulk-updated:
                  summary: Multiple attributes updated
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      name: Brand Name
                      description: Official brand or manufacturer name
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      name: Product Color
                      description: Available color options
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: BULK_LIMIT_EXCEEDED
                    message: >-
                      The number of items exceeds the maximum allowed for bulk
                      operations.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/attributes/{attributeUuid}:
    get:
      tags:
        - Attributes
      summary: Get attribute
      description: Retrieves complete details for a single attribute.
      parameters:
        - name: attributeUuid
          in: path
          description: Unique identifier of the attribute.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved attribute.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeResponse'
              examples:
                published-attribute:
                  summary: Published attribute
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Brand
                    description: Product manufacturer or brand name
                draft-attribute:
                  summary: Draft attribute
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    name: Warranty Period
                    description: Length of manufacturer warranty
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes/{attributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Attribute not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/attributes/{attributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes/{attributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Attributes
      summary: Update attribute
      description: Updates an existing attribute. Only provided fields are updated.
      parameters:
        - name: attributeUuid
          in: path
          description: Unique identifier of the attribute.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributeUpdateRequest'
        required: true
      responses:
        '200':
          description: Attribute updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeResponse'
              examples:
                updated-attribute:
                  summary: Updated attribute
                  description: Attribute with modified properties
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Brand Name
                    description: Official brand or manufacturer name
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes/{attributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Attribute not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/attributes/{attributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/attributes/{attributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ATTRIBUTE_NAME_TOO_LONG
                    message: Attribute name must not exceed 100 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/attributes/{attributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes/{attributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Attributes
      summary: Delete attribute
      description: Permanently deletes an attribute. Cannot be undone.
      parameters:
        - name: attributeUuid
          in: path
          description: Unique identifier of the attribute.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Attribute deleted successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes/{attributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Attribute not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/attributes/{attributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes/{attributeUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/attributes/{attributeUuid}/actions/lifecycle:
    patch:
      tags:
        - Attributes
      summary: Transition attribute lifecycle
      description: >-
        Transitions an attribute to a different lifecycle state. Valid
        transitions depend on current status.
      parameters:
        - name: attributeUuid
          in: path
          description: Unique identifier of the attribute.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributeLifecycleRequest'
        required: true
      responses:
        '200':
          description: Attribute transitioned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeResponse'
              examples:
                published:
                  summary: Transitioned to published
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    name: Brand
                    description: Product manufacturer or brand name
                unpublished:
                  summary: Transitioned to unpublished
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: unpublished
                    name: Brand
                    description: Product manufacturer or brand name
                removed:
                  summary: Transitioned to removed
                  value:
                    uuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    removedAt: '2025-11-20T13:00:00.000000Z'
                    status: removed
                    name: Brand
                    description: Product manufacturer or brand name
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes/{attributeUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Attribute not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/attributes/{attributeUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Invalid transition for current status.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ATTRIBUTE_INVALID_STAGE
                    message: Cannot transition from Published via Publish
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/attributes/{attributeUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes/{attributeUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/attributes/bulk/actions/lifecycle:
    patch:
      tags:
        - Attributes
      summary: Bulk transition attribute lifecycle
      description: >-
        Transitions multiple attributes to a different lifecycle state in a
        single operation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributeBulkLifecycleRequest'
        required: true
      responses:
        '200':
          description: Attributes transitioned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AttributeResponse'
              examples:
                bulk-published:
                  summary: Multiple attributes published
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      name: Brand
                      description: Product manufacturer or brand name
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      name: Color
                      description: Product color or finish
                bulk-removed:
                  summary: Multiple attributes removed
                  value:
                    - uuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      removedAt: '2025-11-20T13:00:00.000000Z'
                      status: removed
                      name: Brand
                      description: Product manufacturer or brand name
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Invalid transition.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ATTRIBUTE_INVALID_STAGE
                    message: Cannot transition from Published via Publish
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/attributes/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/attributes/{attributeUuid}/terms:
    get:
      tags:
        - Attribute Terms
      summary: List attribute terms
      description: >-
        Retrieves a paginated list of terms for an attribute with optional
        filtering.
      parameters:
        - name: attributeUuid
          in: path
          description: Unique identifier of the attribute.
          required: true
          schema:
            type: string
            format: uuid
        - name: name[eq]
          in: query
          description: Filter by exact name match.
          schema:
            type: string
        - name: name[contains]
          in: query
          description: Filter by partial name match.
          schema:
            type: string
        - name: name[starts]
          in: query
          description: Filter by name prefix.
          schema:
            type: string
        - name: name[ends]
          in: query
          description: Filter by name suffix.
          schema:
            type: string
        - name: name[order]
          in: query
          description: 'Sort order for name field. Values: asc, desc.'
          schema:
            type: string
        - name: createdAt[eq]
          in: query
          description: Filter by exact creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[min]
          in: query
          description: Filter by minimum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[max]
          in: query
          description: Filter by maximum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[order]
          in: query
          description: 'Sort order for creation timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: updatedAt[eq]
          in: query
          description: Filter by exact update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[min]
          in: query
          description: Filter by minimum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[max]
          in: query
          description: Filter by maximum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[order]
          in: query
          description: 'Sort order for update timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: page
          in: query
          description: Page number for pagination. Default is 1.
          schema:
            type: integer
            format: int32
        - name: size
          in: query
          description: Page size for pagination. Default is 20.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Successfully retrieved terms.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfTermResponse'
              examples:
                brand-terms:
                  summary: Brand attribute terms
                  description: List of allowed brand values
                  value:
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      name: Apple
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      name: Samsung
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      name: Sony
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      name: LG
                color-terms:
                  summary: Color attribute terms
                  description: List of available colors
                  value:
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      name: Black
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      name: White
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      name: Silver
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      name: Blue
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes/{attributeUuid}/terms
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes/{attributeUuid}/terms
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    post:
      tags:
        - Attribute Terms
      summary: Create term
      description: Creates a new term for an attribute.
      parameters:
        - name: attributeUuid
          in: path
          description: Unique identifier of the attribute.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TermCreateRequest'
        required: true
      responses:
        '201':
          description: Term created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TermResponse'
              examples:
                brand-term:
                  summary: Brand term created
                  description: New allowed brand value
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    name: Apple
                color-term:
                  summary: Color term created
                  description: New available color
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    name: Midnight Blue
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes/{attributeUuid}/terms
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Term already exists.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/attributes/{attributeUuid}/terms
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ATTRIBUTE_TERM_NAME_TOO_LONG
                    message: Attribute term must not exceed 100 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/attributes/{attributeUuid}/terms
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes/{attributeUuid}/terms
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/attributes/{attributeUuid}/terms/{termUuid}:
    get:
      tags:
        - Attribute Terms
      summary: Get term
      description: Retrieves a single term.
      parameters:
        - name: attributeUuid
          in: path
          description: Unique identifier of the attribute.
          required: true
          schema:
            type: string
            format: uuid
        - name: termUuid
          in: path
          description: Unique identifier of the term.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved term.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TermResponse'
              examples:
                brand-term:
                  summary: Brand term
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    name: Apple
                color-term:
                  summary: Color term
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    name: Midnight Blue
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes/{attributeUuid}/terms/{termUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Term not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/attributes/{attributeUuid}/terms/{termUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes/{attributeUuid}/terms/{termUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Attribute Terms
      summary: Update term
      description: Updates an existing term. Only provided fields are updated.
      parameters:
        - name: attributeUuid
          in: path
          description: Unique identifier of the attribute.
          required: true
          schema:
            type: string
            format: uuid
        - name: termUuid
          in: path
          description: Unique identifier of the term.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TermUpdateRequest'
        required: true
      responses:
        '200':
          description: Term updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TermResponse'
              examples:
                updated-term:
                  summary: Updated term
                  description: Term with modified name
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    attributeUuid: 123e4567-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    name: Space Gray
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes/{attributeUuid}/terms/{termUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Term not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/attributes/{attributeUuid}/terms/{termUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/attributes/{attributeUuid}/terms/{termUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ATTRIBUTE_TERM_NAME_TOO_LONG
                    message: Attribute term must not exceed 100 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/attributes/{attributeUuid}/terms/{termUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes/{attributeUuid}/terms/{termUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Attribute Terms
      summary: Delete term
      description: Permanently deletes a term.
      parameters:
        - name: attributeUuid
          in: path
          description: Unique identifier of the attribute.
          required: true
          schema:
            type: string
            format: uuid
        - name: termUuid
          in: path
          description: Unique identifier of the term.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Term deleted successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/attributes/{attributeUuid}/terms/{termUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Term not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/attributes/{attributeUuid}/terms/{termUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/attributes/{attributeUuid}/terms/{termUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets:
    get:
      tags:
        - Assets
      summary: List assets
      description: >-
        Retrieves a paginated list of assets with optional filtering using
        bracket notation.
      parameters:
        - name: status[eq]
          in: query
          description: Filter by exact status match.
          schema:
            enum:
              - draft
              - published
              - unpublished
              - archived
              - removed
            type: string
        - name: status[order]
          in: query
          description: 'Sort order for status field. Values: asc, desc.'
          schema:
            type: string
        - name: category[eq]
          in: query
          description: Filter by exact category match.
          schema:
            enum:
              - image
              - video
              - audio
              - document
              - design
              - archive
              - data
            type: string
        - name: category[order]
          in: query
          description: 'Sort order for category field. Values: asc, desc.'
          schema:
            type: string
        - name: storageLocation[eq]
          in: query
          description: Filter by exact storage location match.
          schema:
            enum:
              - s3
            type: string
        - name: name[eq]
          in: query
          description: Filter by exact name match.
          schema:
            type: string
        - name: name[contains]
          in: query
          description: Filter by partial name match.
          schema:
            type: string
        - name: name[starts]
          in: query
          description: Filter by name prefix.
          schema:
            type: string
        - name: name[ends]
          in: query
          description: Filter by name suffix.
          schema:
            type: string
        - name: name[order]
          in: query
          description: 'Sort order for name field. Values: asc, desc.'
          schema:
            type: string
        - name: createdAt[eq]
          in: query
          description: Filter by exact creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[min]
          in: query
          description: Filter by minimum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[max]
          in: query
          description: Filter by maximum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[order]
          in: query
          description: 'Sort order for creation timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: updatedAt[eq]
          in: query
          description: Filter by exact update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[min]
          in: query
          description: Filter by minimum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[max]
          in: query
          description: Filter by maximum update timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: updatedAt[order]
          in: query
          description: 'Sort order for update timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: isArchived[eq]
          in: query
          description: 'Filter by archived status. Values: true, false.'
          schema:
            type: boolean
        - name: isRemoved[eq]
          in: query
          description: 'Filter by removed status. Values: true, false.'
          schema:
            type: boolean
        - name: page
          in: query
          description: Page number for pagination. Default is 1.
          schema:
            type: integer
            format: int32
        - name: size
          in: query
          description: Page size for pagination. Default is 20.
          schema:
            type: integer
            format: int32
        - name: include[metadata]
          in: query
          description: 'Include metadata. Values: true, false.'
          schema:
            type: boolean
        - name: include[files]
          in: query
          description: 'Include files. Values: true, false.'
          schema:
            type: boolean
      responses:
        '200':
          description: Successfully retrieved paginated list of assets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfAssetHydratedResponse'
              examples:
                base-response:
                  summary: Base response without includes
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    category: image
                    storageLocation: s3
                    name: product-lifestyle-shot.jpg
                    description: Lifestyle photography showing jacket in outdoor setting
                    altText: Person wearing blue winter jacket hiking in mountains
                with-files:
                  summary: With files included
                  description: Response when using include[files]=true
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    category: image
                    storageLocation: s3
                    name: product-lifestyle-shot.jpg
                    description: Lifestyle photography showing jacket in outdoor setting
                    altText: Person wearing blue winter jacket hiking in mountains
                    files:
                      - uuid: bbb22222-e89b-12d3-a456-426614174001
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        status: uploaded
                        variationType: original
                        storageLocation: s3
                        mimeType: image/jpeg
                        extension: .jpg
                        storageKey: assets/234e5678/original.jpg
                        storageSize: 4582912
                        checksum: >-
                          sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                        isAutogenerated: false
                        presignedUrl: >-
                          https://bucket.s3.amazonaws.com/assets/234e5678/original.jpg?X-Amz-Signature=...
                      - uuid: bbb22222-e89b-12d3-a456-426614174002
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        status: uploaded
                        variationType: thumbnail
                        storageLocation: s3
                        mimeType: image/jpeg
                        extension: .jpg
                        storageKey: assets/234e5678/thumbnail.jpg
                        storageSize: 45280
                        checksum: >-
                          sha256:a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
                        isAutogenerated: true
                        presignedUrl: >-
                          https://bucket.s3.amazonaws.com/assets/234e5678/thumbnail.jpg?X-Amz-Signature=...
                with-metadata:
                  summary: With metadata included
                  description: Response when using include[metadata]=true
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    category: image
                    storageLocation: s3
                    name: product-lifestyle-shot.jpg
                    description: Lifestyle photography showing jacket in outdoor setting
                    altText: Person wearing blue winter jacket hiking in mountains
                    metadata:
                      - uuid: aaa11111-e89b-12d3-a456-426614174001
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        updatedAt: '2025-11-20T08:15:00.000000Z'
                        key: photographer
                        value: John Smith
                      - uuid: aaa11111-e89b-12d3-a456-426614174002
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        updatedAt: '2025-11-20T08:15:00.000000Z'
                        key: location
                        value: Swiss Alps
                      - uuid: aaa11111-e89b-12d3-a456-426614174003
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        updatedAt: '2025-11-20T08:15:00.000000Z'
                        key: copyright
                        value: © 2025 Outdoor Gear Co.
                fully-hydrated:
                  summary: Fully hydrated
                  description: >-
                    Response when using
                    include[files]=true&include[metadata]=true
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    category: image
                    storageLocation: s3
                    name: product-lifestyle-shot.jpg
                    description: Lifestyle photography showing jacket in outdoor setting
                    altText: Person wearing blue winter jacket hiking in mountains
                    metadata:
                      - uuid: aaa11111-e89b-12d3-a456-426614174001
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        updatedAt: '2025-11-20T08:15:00.000000Z'
                        key: photographer
                        value: John Smith
                      - uuid: aaa11111-e89b-12d3-a456-426614174002
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        updatedAt: '2025-11-20T08:15:00.000000Z'
                        key: location
                        value: Swiss Alps
                      - uuid: aaa11111-e89b-12d3-a456-426614174003
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        updatedAt: '2025-11-20T08:15:00.000000Z'
                        key: copyright
                        value: © 2025 Outdoor Gear Co.
                    files:
                      - uuid: bbb22222-e89b-12d3-a456-426614174001
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        status: uploaded
                        variationType: original
                        storageLocation: s3
                        mimeType: image/jpeg
                        extension: .jpg
                        storageKey: assets/234e5678/original.jpg
                        storageSize: 4582912
                        checksum: >-
                          sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                        isAutogenerated: false
                        presignedUrl: >-
                          https://bucket.s3.amazonaws.com/assets/234e5678/original.jpg?X-Amz-Signature=...
                      - uuid: bbb22222-e89b-12d3-a456-426614174002
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        status: uploaded
                        variationType: thumbnail
                        storageLocation: s3
                        mimeType: image/jpeg
                        extension: .jpg
                        storageKey: assets/234e5678/thumbnail.jpg
                        storageSize: 45280
                        checksum: >-
                          sha256:a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
                        isAutogenerated: true
                        presignedUrl: >-
                          https://bucket.s3.amazonaws.com/assets/234e5678/thumbnail.jpg?X-Amz-Signature=...
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    post:
      tags:
        - Assets
      summary: Create asset
      description: >-
        Creates a new asset entity. Files must be uploaded separately after
        creation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetCreateRequest'
        required: true
      responses:
        '201':
          description: Asset created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetResponse'
              examples:
                image-asset:
                  summary: Created image asset
                  description: Newly created asset starts in draft status
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    category: image
                    storageLocation: s3
                    name: winter-jacket-hero.jpg
                    description: Main hero image for product page
                    altText: Blue winter jacket on white background
                video-asset:
                  summary: Created video asset
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    category: video
                    storageLocation: s3
                    name: product-demo.mp4
                    description: Product demonstration video
                    altText: Video showing product features
                minimal-asset:
                  summary: Minimal asset with only required fields
                  description: Asset created with null optional fields
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: draft
                    category: image
                    storageLocation: s3
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Conflict occurred.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/assets
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ASSET_NAME_TOO_LONG
                    message: Asset name must not exceed 255 characters.
                  - code: ASSET_DESCRIPTION_TOO_LONG
                    message: Asset description must not exceed 1000 characters.
                  - code: ASSET_ALT_TEXT_TOO_LONG
                    message: Asset alt text must not exceed 500 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/assets
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets/{assetUuid}:
    get:
      tags:
        - Assets
      summary: Get asset
      description: Retrieves complete details for a single asset.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
        - name: include[metadata]
          in: query
          schema:
            type: boolean
        - name: include[files]
          in: query
          schema:
            type: boolean
      responses:
        '200':
          description: Successfully retrieved asset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetHydratedResponse'
              examples:
                base-response:
                  summary: Base response without includes
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    category: image
                    storageLocation: s3
                    name: product-lifestyle-shot.jpg
                    description: Lifestyle photography showing jacket in outdoor setting
                    altText: Person wearing blue winter jacket hiking in mountains
                with-files:
                  summary: With files included
                  description: Response when using include[files]=true
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    category: image
                    storageLocation: s3
                    name: product-lifestyle-shot.jpg
                    description: Lifestyle photography showing jacket in outdoor setting
                    altText: Person wearing blue winter jacket hiking in mountains
                    files:
                      - uuid: bbb22222-e89b-12d3-a456-426614174001
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        status: uploaded
                        variationType: original
                        storageLocation: s3
                        mimeType: image/jpeg
                        extension: .jpg
                        storageKey: assets/234e5678/original.jpg
                        storageSize: 4582912
                        checksum: >-
                          sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                        isAutogenerated: false
                        presignedUrl: >-
                          https://bucket.s3.amazonaws.com/assets/234e5678/original.jpg?X-Amz-Signature=...
                      - uuid: bbb22222-e89b-12d3-a456-426614174002
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        status: uploaded
                        variationType: thumbnail
                        storageLocation: s3
                        mimeType: image/jpeg
                        extension: .jpg
                        storageKey: assets/234e5678/thumbnail.jpg
                        storageSize: 45280
                        checksum: >-
                          sha256:a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
                        isAutogenerated: true
                        presignedUrl: >-
                          https://bucket.s3.amazonaws.com/assets/234e5678/thumbnail.jpg?X-Amz-Signature=...
                with-metadata:
                  summary: With metadata included
                  description: Response when using include[metadata]=true
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    category: image
                    storageLocation: s3
                    name: product-lifestyle-shot.jpg
                    description: Lifestyle photography showing jacket in outdoor setting
                    altText: Person wearing blue winter jacket hiking in mountains
                    metadata:
                      - uuid: aaa11111-e89b-12d3-a456-426614174001
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        updatedAt: '2025-11-20T08:15:00.000000Z'
                        key: photographer
                        value: John Smith
                      - uuid: aaa11111-e89b-12d3-a456-426614174002
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        updatedAt: '2025-11-20T08:15:00.000000Z'
                        key: location
                        value: Swiss Alps
                      - uuid: aaa11111-e89b-12d3-a456-426614174003
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        updatedAt: '2025-11-20T08:15:00.000000Z'
                        key: copyright
                        value: © 2025 Outdoor Gear Co.
                fully-hydrated:
                  summary: Fully hydrated
                  description: >-
                    Response when using
                    include[files]=true&include[metadata]=true
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    category: image
                    storageLocation: s3
                    name: product-lifestyle-shot.jpg
                    description: Lifestyle photography showing jacket in outdoor setting
                    altText: Person wearing blue winter jacket hiking in mountains
                    metadata:
                      - uuid: aaa11111-e89b-12d3-a456-426614174001
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        updatedAt: '2025-11-20T08:15:00.000000Z'
                        key: photographer
                        value: John Smith
                      - uuid: aaa11111-e89b-12d3-a456-426614174002
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        updatedAt: '2025-11-20T08:15:00.000000Z'
                        key: location
                        value: Swiss Alps
                      - uuid: aaa11111-e89b-12d3-a456-426614174003
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        updatedAt: '2025-11-20T08:15:00.000000Z'
                        key: copyright
                        value: © 2025 Outdoor Gear Co.
                    files:
                      - uuid: bbb22222-e89b-12d3-a456-426614174001
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        status: uploaded
                        variationType: original
                        storageLocation: s3
                        mimeType: image/jpeg
                        extension: .jpg
                        storageKey: assets/234e5678/original.jpg
                        storageSize: 4582912
                        checksum: >-
                          sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                        isAutogenerated: false
                        presignedUrl: >-
                          https://bucket.s3.amazonaws.com/assets/234e5678/original.jpg?X-Amz-Signature=...
                      - uuid: bbb22222-e89b-12d3-a456-426614174002
                        createdAt: '2025-11-20T08:15:00.000000Z'
                        status: uploaded
                        variationType: thumbnail
                        storageLocation: s3
                        mimeType: image/jpeg
                        extension: .jpg
                        storageKey: assets/234e5678/thumbnail.jpg
                        storageSize: 45280
                        checksum: >-
                          sha256:a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
                        isAutogenerated: true
                        presignedUrl: >-
                          https://bucket.s3.amazonaws.com/assets/234e5678/thumbnail.jpg?X-Amz-Signature=...
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Asset not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/assets/{assetUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Assets
      summary: Update asset
      description: Updates an existing asset. Only provided fields are updated.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetUpdateRequest'
        required: true
      responses:
        '200':
          description: Asset updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetResponse'
              examples:
                updated-image:
                  summary: Updated image asset
                  description: Asset with modified metadata
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    category: image
                    storageLocation: s3
                    name: winter-jacket-hero.jpg
                    description: Main hero image for product page
                    altText: Blue winter jacket on white background
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Asset not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/assets/{assetUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/assets/{assetUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ASSET_NAME_TOO_LONG
                    message: Asset name must not exceed 255 characters.
                  - code: ASSET_DESCRIPTION_TOO_LONG
                    message: Asset description must not exceed 1000 characters.
                  - code: ASSET_ALT_TEXT_TOO_LONG
                    message: Asset alt text must not exceed 500 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/assets
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Assets
      summary: Delete asset
      description: Permanently deletes an asset and all associated files. Cannot be undone.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Asset deleted successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Asset not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/assets/{assetUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets/bulk:
    post:
      tags:
        - Assets
      summary: Bulk create assets
      description: Creates multiple assets in a single atomic operation.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AssetBulkCreateRequest'
        required: true
      responses:
        '201':
          description: Assets created successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssetResponse'
              examples:
                multiple-assets:
                  summary: Multiple assets created
                  description: Batch creation of different asset types
                  value:
                    - uuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      category: image
                      storageLocation: s3
                      name: winter-jacket-hero.jpg
                      description: Main hero image for product page
                      altText: Blue winter jacket on white background
                    - uuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      category: video
                      storageLocation: s3
                      name: product-demo.mp4
                      description: Product demonstration video
                      altText: Video showing product features
                    - uuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: draft
                      category: document
                      storageLocation: s3
                      name: care-instructions.pdf
                      description: Care and maintenance instructions
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Conflict occurred.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/assets/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ASSET_NAME_TOO_LONG
                    message: Asset name must not exceed 255 characters.
                  - code: ASSET_DESCRIPTION_TOO_LONG
                    message: Asset description must not exceed 1000 characters.
                  - code: ASSET_ALT_TEXT_TOO_LONG
                    message: Asset alt text must not exceed 500 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/assets
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Assets
      summary: Bulk update assets
      description: Updates multiple assets in a single operation.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AssetBulkUpdateRequest'
        required: true
      responses:
        '200':
          description: Assets updated successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssetResponse'
              examples:
                bulk-updated:
                  summary: Multiple assets updated
                  value:
                    - uuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      category: image
                      storageLocation: s3
                      name: winter-jacket-hero.jpg
                      description: Main hero image for product page
                      altText: Blue winter jacket on white background
                    - uuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      category: video
                      storageLocation: s3
                      name: product-demo.mp4
                      description: Product demonstration video
                      altText: Video showing product features
                    - uuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      category: document
                      storageLocation: s3
                      name: care-instructions.pdf
                      description: Care and maintenance instructions
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/assets/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ASSET_NAME_TOO_LONG
                    message: Asset name must not exceed 255 characters.
                  - code: ASSET_DESCRIPTION_TOO_LONG
                    message: Asset description must not exceed 1000 characters.
                  - code: ASSET_ALT_TEXT_TOO_LONG
                    message: Asset alt text must not exceed 500 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/assets
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/bulk
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets/{assetUuid}/actions/lifecycle:
    patch:
      tags:
        - Assets
      summary: Transition asset lifecycle
      description: >-
        Transitions an asset to a different lifecycle state. Valid transitions
        depend on current status.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetLifecycleRequest'
        required: true
      responses:
        '200':
          description: Asset transitioned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetResponse'
              examples:
                published:
                  summary: Transitioned to published
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: published
                    category: image
                    storageLocation: s3
                    name: winter-jacket-hero.jpg
                    description: Main hero image for product page
                    altText: Blue winter jacket on white background
                unpublished:
                  summary: Transitioned to unpublished
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    status: unpublished
                    category: image
                    storageLocation: s3
                    name: winter-jacket-hero.jpg
                    description: Main hero image for product page
                    altText: Blue winter jacket on white background
                archived:
                  summary: Transitioned to archived
                  value:
                    uuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    archivedAt: '2025-11-20T13:00:00.000000Z'
                    status: archived
                    category: image
                    storageLocation: s3
                    name: winter-jacket-hero.jpg
                    description: Main hero image for product page
                    altText: Blue winter jacket on white background
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Asset not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/assets/{assetUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Invalid transition for current status.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ASSET_INVALID_STAGE
                    message: Cannot transition from Unpublished via Unpublish
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/assets/{assetUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets/bulk/actions/lifecycle:
    patch:
      tags:
        - Assets
      summary: Bulk transition asset lifecycle
      description: >-
        Transitions multiple assets to a different lifecycle state in a single
        operation.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetBulkLifecycleRequest'
        required: true
      responses:
        '200':
          description: Assets transitioned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AssetResponse'
              examples:
                bulk-published:
                  summary: Multiple assets published
                  value:
                    - uuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      category: image
                      storageLocation: s3
                      name: winter-jacket-hero.jpg
                      description: Main hero image for product page
                      altText: Blue winter jacket on white background
                    - uuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      category: video
                      storageLocation: s3
                      name: product-demo.mp4
                      description: Product demonstration video
                      altText: Video showing product features
                    - uuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      status: published
                      category: document
                      storageLocation: s3
                      name: care-instructions.pdf
                      description: Care and maintenance instructions
                bulk-archived:
                  summary: Multiple assets archived
                  value:
                    - uuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-23T15:45:00.000000Z'
                      archivedAt: '2025-11-20T13:00:00.000000Z'
                      status: archived
                      category: image
                      storageLocation: s3
                      name: winter-jacket-hero.jpg
                      description: Main hero image for product page
                      altText: Blue winter jacket on white background
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Invalid transition.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: ASSET_INVALID_STAGE
                    message: Cannot transition from Unpublished via Unpublish
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/assets/{assetUuid}/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/bulk/actions/lifecycle
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets/files/bulk/actions/initiate-upload:
    post:
      tags:
        - Asset Files
      summary: Bulk initiate file uploads
      description: >-
        Initiates multiple file uploads in a single operation and returns
        pre-signed URLs.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FileBulkInitiateUploadRequest'
        required: true
      responses:
        '201':
          description: Uploads initiated successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileResponse'
              examples:
                multiple-image-uploads:
                  summary: Multiple image uploads initiated
                  description: >-
                    Batch upload initiation for product images across multiple
                    assets
                  value:
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: awaitingUpload
                      variationType: original
                      storageLocation: s3
                      mimeType: image/jpeg
                      extension: .jpg
                      checksum: ''
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.jpg?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174002
                      assetUuid: 234e5678-e89b-12d3-a456-426614174002
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: awaitingUpload
                      variationType: original
                      storageLocation: s3
                      mimeType: image/jpeg
                      extension: .jpg
                      checksum: ''
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174002/original.jpg?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174003
                      assetUuid: 234e5678-e89b-12d3-a456-426614174003
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: awaitingUpload
                      variationType: original
                      storageLocation: s3
                      mimeType: image/png
                      extension: .png
                      checksum: ''
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174003/original.png?X-Amz-Signature=...
                mixed-media-uploads:
                  summary: Mixed media uploads initiated
                  description: Batch upload initiation for different file types
                  value:
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: awaitingUpload
                      variationType: original
                      storageLocation: s3
                      mimeType: image/jpeg
                      extension: .jpg
                      checksum: ''
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.jpg?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174002
                      assetUuid: 234e5678-e89b-12d3-a456-426614174002
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: awaitingUpload
                      variationType: original
                      storageLocation: s3
                      mimeType: video/mp4
                      extension: .mp4
                      checksum: ''
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174002/original.mp4?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174003
                      assetUuid: 234e5678-e89b-12d3-a456-426614174003
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: awaitingUpload
                      variationType: original
                      storageLocation: s3
                      mimeType: application/pdf
                      extension: .pdf
                      checksum: ''
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174003/original.pdf?X-Amz-Signature=...
                variation-uploads:
                  summary: Multiple variations for single asset
                  description: >-
                    Batch upload initiation for different file variations of the
                    same asset
                  value:
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: awaitingUpload
                      variationType: original
                      storageLocation: s3
                      mimeType: image/jpeg
                      extension: .jpg
                      checksum: ''
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.jpg?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174002
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: awaitingUpload
                      variationType: webOptimized
                      storageLocation: s3
                      mimeType: image/webp
                      extension: .webp
                      checksum: ''
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/weboptimized.webp?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174003
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: awaitingUpload
                      variationType: printReady
                      storageLocation: s3
                      mimeType: image/tiff
                      extension: .tiff
                      checksum: ''
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/printready.tiff?X-Amz-Signature=...
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/files/bulk/actions/initiate-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: BULK_LIMIT_EXCEEDED
                    message: >-
                      The number of items exceeds the maximum allowed for bulk
                      operations.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/assets/files/bulk/actions/initiate-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/files/bulk/actions/initiate-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets/files/bulk/actions/complete-upload:
    patch:
      tags:
        - Asset Files
      summary: Bulk complete file uploads
      description: >-
        Completes multiple file uploads after files have been transferred to
        storage.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FileBulkCompleteUploadRequest'
        required: true
      responses:
        '200':
          description: Uploads completed successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FileResponse'
              examples:
                completed-image-uploads:
                  summary: Multiple image uploads completed
                  description: >-
                    Batch completion with verified checksums and calculated
                    sizes
                  value:
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: original
                      storageLocation: s3
                      mimeType: image/jpeg
                      extension: .jpg
                      storageSize: 4582912
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.jpg?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174002
                      assetUuid: 234e5678-e89b-12d3-a456-426614174002
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: original
                      storageLocation: s3
                      mimeType: image/jpeg
                      extension: .jpg
                      storageSize: 3145728
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174002/original.jpg?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174003
                      assetUuid: 234e5678-e89b-12d3-a456-426614174003
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: original
                      storageLocation: s3
                      mimeType: image/png
                      extension: .png
                      storageSize: 2097152
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174003/original.png?X-Amz-Signature=...
                completed-mixed-media:
                  summary: Mixed media uploads completed
                  description: Batch completion for different file types with varying sizes
                  value:
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: original
                      storageLocation: s3
                      mimeType: image/jpeg
                      extension: .jpg
                      storageSize: 4582912
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.jpg?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174002
                      assetUuid: 234e5678-e89b-12d3-a456-426614174002
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: original
                      storageLocation: s3
                      mimeType: video/mp4
                      extension: .mp4
                      storageSize: 52428800
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174002/original.mp4?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174003
                      assetUuid: 234e5678-e89b-12d3-a456-426614174003
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: original
                      storageLocation: s3
                      mimeType: application/pdf
                      extension: .pdf
                      storageSize: 1048576
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174003/original.pdf?X-Amz-Signature=...
                completed-variations:
                  summary: Multiple variations completed
                  description: >-
                    Batch completion for different file variations of the same
                    asset
                  value:
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: original
                      storageLocation: s3
                      mimeType: image/jpeg
                      extension: .jpg
                      storageSize: 4582912
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.jpg?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174002
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: webOptimized
                      storageLocation: s3
                      mimeType: image/webp
                      extension: .webp
                      storageSize: 285440
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/weboptimized.webp?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174003
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: printReady
                      storageLocation: s3
                      mimeType: image/tiff
                      extension: .tiff
                      storageSize: 15728640
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/printready.tiff?X-Amz-Signature=...
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/files/bulk/actions/complete-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: BULK_LIMIT_EXCEEDED
                    message: >-
                      The number of items exceeds the maximum allowed for bulk
                      operations.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/assets/files/bulk/actions/complete-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/files/bulk/actions/complete-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets/{assetUuid}/files:
    get:
      tags:
        - Asset Files
      summary: List files
      description: >-
        Retrieves a paginated list of files for an asset with optional
        filtering.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
        - name: status[eq]
          in: query
          description: Filter by exact status match.
          schema:
            enum:
              - draft
              - published
              - unpublished
              - archived
              - removed
            type: string
        - name: status[order]
          in: query
          description: 'Sort order for status field. Values: asc, desc.'
          schema:
            type: string
        - name: variationType[eq]
          in: query
          description: Filter by exact variation type match.
          schema:
            enum:
              - original
              - thumbnail
              - webOptimized
              - mobileOptimized
              - productDetail
              - printReady
              - socialMedia
              - videoPoster
              - videoPreview
              - videoStreamLow
              - videoStreamMedium
              - videoStreamHigh
            type: string
        - name: variationType[order]
          in: query
          description: 'Sort order for variation type. Values: asc, desc.'
          schema:
            type: string
        - name: mimeType[eq]
          in: query
          description: Filter by exact MIME type match.
          schema:
            type: string
        - name: extension[eq]
          in: query
          description: Filter by exact extension match.
          schema:
            type: string
        - name: extension[contains]
          in: query
          description: Filter by partial extension match.
          schema:
            type: string
        - name: extension[starts]
          in: query
          description: Filter by extension prefix.
          schema:
            type: string
        - name: extension[ends]
          in: query
          description: Filter by extension suffix.
          schema:
            type: string
        - name: isAutogenerated[eq]
          in: query
          description: 'Filter by autogenerated status. Values: true, false.'
          schema:
            type: boolean
        - name: createdAt[eq]
          in: query
          description: Filter by exact creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[min]
          in: query
          description: Filter by minimum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[max]
          in: query
          description: Filter by maximum creation timestamp.
          schema:
            type: string
            format: date-time
            example: '2025-11-23T14:15:22.123456Z'
        - name: createdAt[order]
          in: query
          description: 'Sort order for creation timestamp. Values: asc, desc.'
          schema:
            type: string
        - name: storageSize[order]
          in: query
          description: 'Sort order for storage size. Values: asc, desc.'
          schema:
            type: string
        - name: page
          in: query
          description: Page number for pagination. Default is 1.
          schema:
            type: integer
            format: int32
        - name: size
          in: query
          description: Page size for pagination. Default is 20.
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Successfully retrieved files.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfFileResponse'
              examples:
                image-files:
                  summary: Image asset files
                  description: Original and generated variations for an image asset
                  value:
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: original
                      storageLocation: s3
                      mimeType: image/jpeg
                      extension: .jpg
                      storageSize: 4582912
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.jpg?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: thumbnail
                      storageLocation: s3
                      mimeType: image/jpeg
                      extension: .jpg
                      storageSize: 45280
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: true
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/thumbnail.jpg?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: webOptimized
                      storageLocation: s3
                      mimeType: image/webp
                      extension: .webp
                      storageSize: 285440
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: true
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/weboptimized.webp?X-Amz-Signature=...
                video-files:
                  summary: Video asset files
                  description: Original video with streaming variations
                  value:
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: original
                      storageLocation: s3
                      mimeType: video/mp4
                      extension: .mp4
                      storageSize: 52428800
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: false
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.mp4?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: videoPoster
                      storageLocation: s3
                      mimeType: image/jpeg
                      extension: .jpg
                      storageSize: 125000
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: true
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/videoposter.jpg?X-Amz-Signature=...
                    - uuid: bbb22222-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      status: uploaded
                      variationType: videoStreamHigh
                      storageLocation: s3
                      mimeType: video/mp4
                      extension: .mp4
                      storageSize: 31457280
                      checksum: >-
                        sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                      isAutogenerated: true
                      presignedUrl: >-
                        https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/videostreamhigh.mp4?X-Amz-Signature=...
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}/files
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}/files
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets/{assetUuid}/files/{fileUuid}:
    get:
      tags:
        - Asset Files
      summary: Get file
      description: Retrieves complete details for a single file including download URL.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
        - name: fileUuid
          in: path
          description: Unique identifier of the file.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponse'
              examples:
                original-image:
                  summary: Original image file
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    status: uploaded
                    variationType: original
                    storageLocation: s3
                    mimeType: image/jpeg
                    extension: .jpg
                    storageSize: 4582912
                    checksum: >-
                      sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                    isAutogenerated: false
                    presignedUrl: >-
                      https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.jpg?X-Amz-Signature=...
                thumbnail:
                  summary: Auto-generated thumbnail
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    status: uploaded
                    variationType: thumbnail
                    storageLocation: s3
                    mimeType: image/jpeg
                    extension: .jpg
                    storageSize: 45280
                    checksum: >-
                      sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                    isAutogenerated: true
                    presignedUrl: >-
                      https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/thumbnail.jpg?X-Amz-Signature=...
                video-file:
                  summary: Original video file
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    status: uploaded
                    variationType: original
                    storageLocation: s3
                    mimeType: video/mp4
                    extension: .mp4
                    storageSize: 52428800
                    checksum: >-
                      sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                    isAutogenerated: false
                    presignedUrl: >-
                      https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.mp4?X-Amz-Signature=...
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}/files/{fileUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: File not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/assets/{assetUuid}/files/{fileUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}/files/{fileUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Asset Files
      summary: Delete file
      description: Permanently deletes a file. Cannot be undone.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
        - name: fileUuid
          in: path
          description: Unique identifier of the file.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: File deleted successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}/files/{fileUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: File not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/assets/{assetUuid}/files/{fileUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}/files/{fileUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets/{assetUuid}/files/actions/initiate-upload:
    post:
      tags:
        - Asset Files
      summary: Initiate file upload
      description: Initiates a file upload and returns a pre-signed URL for uploading.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileInitiateUploadRequest'
        required: true
      responses:
        '201':
          description: Upload initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponse'
              examples:
                image-upload:
                  summary: Image upload initiated
                  description: File awaiting upload with pre-signed URL
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    status: awaitingUpload
                    variationType: original
                    storageLocation: s3
                    mimeType: image/jpeg
                    extension: .jpg
                    checksum: ''
                    isAutogenerated: false
                    presignedUrl: >-
                      https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.jpg?X-Amz-Signature=...
                video-upload:
                  summary: Video upload initiated
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    status: awaitingUpload
                    variationType: original
                    storageLocation: s3
                    mimeType: video/mp4
                    extension: .mp4
                    checksum: ''
                    isAutogenerated: false
                    presignedUrl: >-
                      https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.mp4?X-Amz-Signature=...
                document-upload:
                  summary: Document upload initiated
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    status: awaitingUpload
                    variationType: original
                    storageLocation: s3
                    mimeType: application/pdf
                    extension: .pdf
                    checksum: ''
                    isAutogenerated: false
                    presignedUrl: >-
                      https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.pdf?X-Amz-Signature=...
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}/files/actions/initiate-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: FILE_EXTENSION_EMPTY
                    message: File extension cannot be empty.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/assets/{assetUuid}/files/actions/initiate-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}/files/actions/initiate-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets/{assetUuid}/files/{fileUuid}/actions/complete-upload:
    patch:
      tags:
        - Asset Files
      summary: Complete file upload
      description: Completes a file upload after the file has been transferred to storage.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
        - name: fileUuid
          in: path
          description: Unique identifier of the file.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileCompleteUploadRequest'
        required: true
      responses:
        '200':
          description: Upload completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileResponse'
              examples:
                completed-image:
                  summary: Completed image upload
                  description: File with verified checksum and calculated size
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    status: uploaded
                    variationType: original
                    storageLocation: s3
                    mimeType: image/jpeg
                    extension: .jpg
                    storageSize: 4582912
                    checksum: >-
                      sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                    isAutogenerated: false
                    presignedUrl: >-
                      https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.jpg?X-Amz-Signature=...
                completed-video:
                  summary: Completed video upload
                  value:
                    uuid: bbb22222-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    status: uploaded
                    variationType: original
                    storageLocation: s3
                    mimeType: video/mp4
                    extension: .mp4
                    storageSize: 52428800
                    checksum: >-
                      sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                    isAutogenerated: false
                    presignedUrl: >-
                      https://bucket.s3.amazonaws.com/assets/234e5678e89b12d3a456426614174001/original.mp4?X-Amz-Signature=...
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: >-
                  /v1/assets/{assetUuid}/files/{fileUuid}/actions/complete-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: File not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: >-
                  /v1/assets/{assetUuid}/files/{fileUuid}/actions/complete-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: FILE_CHECKSUM_INVALID_LENGTH
                    message: Checksum must be exactly 64 characters (SHA256).
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: >-
                  /v1/assets/{assetUuid}/files/{fileUuid}/actions/complete-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: >-
                  /v1/assets/{assetUuid}/files/{fileUuid}/actions/complete-upload
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets/{assetUuid}/metadata:
    get:
      tags:
        - Asset Metadata
      summary: List metadata
      description: Retrieves a paginated list of metadata entries for an asset.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          schema:
            type: integer
            format: int32
            default: 1
        - name: size
          in: query
          schema:
            type: integer
            format: int32
            default: 20
      responses:
        '200':
          description: Successfully retrieved metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResultOfMetadataResponse'
              examples:
                metadata-list:
                  summary: Metadata entries for an asset
                  description: List of custom key-value metadata pairs
                  value:
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      key: photographer
                      value: John Smith
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      key: location
                      value: Swiss Alps
                    - uuid: aaa11111-e89b-12d3-a456-426614174001
                      assetUuid: 234e5678-e89b-12d3-a456-426614174001
                      createdAt: '2025-11-20T08:15:00.000000Z'
                      updatedAt: '2025-11-20T08:15:00.000000Z'
                      key: copyright
                      value: © 2025 Outdoor Gear Co.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}/metadata
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}/metadata
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    post:
      tags:
        - Asset Metadata
      summary: Create metadata
      description: Creates a new metadata entry for an asset.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataCreateRequest'
        required: true
      responses:
        '201':
          description: Metadata created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataResponse'
              examples:
                photographer-metadata:
                  summary: Photographer metadata
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    key: photographer
                    value: John Smith
                location-metadata:
                  summary: Location metadata
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    key: location
                    value: Swiss Alps
                custom-metadata:
                  summary: Custom metadata
                  description: Any custom key-value pair
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    key: campaign_id
                    value: summer-2025
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}/metadata
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Conflict occurred.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/assets/{assetUuid}/metadata
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: METADATA_KEY_TOO_LONG
                    message: Metadata key must not exceed 255 characters.
                  - code: METADATA_VALUE_TOO_LONG
                    message: Metadata value must not exceed 1000 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/assets/{assetUuid}/metadata
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}/metadata
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
  /v1/assets/{assetUuid}/metadata/{metadataUuid}:
    get:
      tags:
        - Asset Metadata
      summary: Get metadata
      description: Retrieves a single metadata entry.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
        - name: metadataUuid
          in: path
          description: Unique identifier of the metadata entry.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successfully retrieved metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataResponse'
              examples:
                photographer-metadata:
                  summary: Photographer metadata
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    key: photographer
                    value: John Smith
                location-metadata:
                  summary: Location metadata
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-20T08:15:00.000000Z'
                    key: location
                    value: Swiss Alps
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}/metadata/{metadataUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Metadata not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/assets/{assetUuid}/metadata/{metadataUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}/metadata/{metadataUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    patch:
      tags:
        - Asset Metadata
      summary: Update metadata
      description: Updates an existing metadata entry. Only provided fields are updated.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
        - name: metadataUuid
          in: path
          description: Unique identifier of the metadata entry.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataUpdateRequest'
        required: true
      responses:
        '200':
          description: Metadata updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataResponse'
              examples:
                updated-metadata:
                  summary: Updated metadata entry
                  description: Metadata with modified value
                  value:
                    uuid: aaa11111-e89b-12d3-a456-426614174001
                    assetUuid: 234e5678-e89b-12d3-a456-426614174001
                    createdAt: '2025-11-20T08:15:00.000000Z'
                    updatedAt: '2025-11-23T15:45:00.000000Z'
                    key: photographer
                    value: Jane Doe
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}/metadata/{metadataUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Metadata not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/assets/{assetUuid}/metadata/{metadataUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '409':
          description: Update conflict.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
                instance: /v1/assets/{assetUuid}/metadata/{metadataUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '422':
          description: Validation failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors:
                  - code: METADATA_KEY_TOO_LONG
                    message: Metadata key must not exceed 255 characters.
                  - code: METADATA_VALUE_TOO_LONG
                    message: Metadata value must not exceed 1000 characters.
                type: https://docs.apiera.io/problems/unprocessable-entity
                title: Unprocessable Entity
                status: 422
                detail: The request was well-formed but contains semantic errors.
                instance: /v1/assets/{assetUuid}/metadata/{metadataUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}/metadata/{metadataUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
    delete:
      tags:
        - Asset Metadata
      summary: Delete metadata
      description: Permanently deletes a metadata entry.
      parameters:
        - name: assetUuid
          in: path
          description: Unique identifier of the asset.
          required: true
          schema:
            type: string
            format: uuid
        - name: metadataUuid
          in: path
          description: Unique identifier of the metadata entry.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Metadata deleted successfully.
        '401':
          description: Authentication required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Insufficient permissions.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
                instance: /v1/assets/{assetUuid}/metadata/{metadataUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '404':
          description: Metadata not found.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/not-found
                title: Not Found
                status: 404
                detail: The requested resource could not be found.
                instance: /v1/assets/{assetUuid}/metadata/{metadataUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails2'
              example:
                type: https://docs.apiera.io/problems/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred while processing the request.
                instance: /v1/assets/{assetUuid}/metadata/{metadataUuid}
                correlationId: 019ab5a1-ec20-7319-a898-76a0986f9762
      security:
        - Bearer: []
components:
  schemas:
    AssetBulkCreateRequest:
      required:
        - category
        - storageLocation
      type: object
      properties:
        category:
          enum:
            - image
            - video
            - audio
            - document
            - design
            - archive
            - data
          type: string
          description: Category classification for the new assets.
        storageLocation:
          enum:
            - s3
          type: string
          description: Storage backend where associated files will be stored.
        name:
          maxLength: 255
          minLength: 1
          type: string
          description: Display name template for the new assets.
          nullable: true
        description:
          maxLength: 1000
          type: string
          description: Optional detailed description for the new assets.
          nullable: true
        altText:
          maxLength: 500
          type: string
          description: Optional alternative text for the new assets.
          nullable: true
      description: Request to create multiple assets with the same configuration.
    AssetBulkLifecycleRequest:
      required:
        - transition
        - uuids
      type: object
      properties:
        transition:
          enum:
            - remove
            - restore
            - publish
            - unpublish
            - archive
            - unarchive
          type: string
          description: Lifecycle transition to apply to all specified assets.
        uuids:
          type: array
          items:
            type: string
            format: uuid
          description: List of asset identifiers to transition.
      description: Request to transition multiple assets to a different lifecycle state.
    AssetBulkUpdateRequest:
      required:
        - assetUuid
      type: object
      properties:
        assetUuid:
          type: string
          description: Identifier of the asset to update.
          format: uuid
        name:
          maxLength: 255
          minLength: 1
          type: string
          description: Updated display name for the asset.
          nullable: true
        description:
          maxLength: 1000
          type: string
          description: Updated detailed description for the asset.
          nullable: true
        altText:
          maxLength: 500
          type: string
          description: Updated alternative text for the asset.
          nullable: true
      description: Request to update multiple assets in a single operation.
    AssetCreateRequest:
      required:
        - category
        - storageLocation
      type: object
      properties:
        category:
          enum:
            - image
            - video
            - audio
            - document
            - design
            - archive
            - data
          type: string
          description: Category classification for the new asset.
        storageLocation:
          enum:
            - s3
          type: string
          description: Storage backend where associated files will be stored.
        name:
          maxLength: 255
          minLength: 1
          type: string
          description: Display name for the new asset.
          nullable: true
        description:
          maxLength: 1000
          type: string
          description: Optional detailed description for the new asset.
          nullable: true
        altText:
          maxLength: 500
          type: string
          description: Optional alternative text for accessibility and SEO purposes.
          nullable: true
      description: Request to create a new asset.
    AssetHydratedResponse:
      required:
        - uuid
        - createdAt
        - updatedAt
        - status
        - category
        - storageLocation
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this asset.
          format: uuid
        createdAt:
          type: string
          description: Timestamp when this asset was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          description: Timestamp when this asset was last modified.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        removedAt:
          type: string
          description: Timestamp when this asset was removed. Null if not removed.
          format: date-time
          nullable: true
          example: '2025-11-23T14:15:22.123456Z'
        archivedAt:
          type: string
          description: Timestamp when this asset was archived. Null if not archived.
          format: date-time
          nullable: true
          example: '2025-11-23T14:15:22.123456Z'
        status:
          enum:
            - draft
            - published
            - unpublished
            - archived
            - removed
          type: string
          description: Current lifecycle status of this asset.
        category:
          enum:
            - image
            - video
            - audio
            - document
            - design
            - archive
            - data
          type: string
          description: Category classification for this asset.
        storageLocation:
          enum:
            - s3
          type: string
          description: Storage backend where associated files reside.
        name:
          type: string
          description: Display name for this asset.
          nullable: true
        description:
          type: string
          description: Optional detailed description for this asset.
          nullable: true
        altText:
          type: string
          description: Alternative text for accessibility and SEO purposes.
          nullable: true
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/MetadataItem'
          description: >-
            Collection of custom metadata key-value pairs associated with this
            asset.
          nullable: true
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileItem'
          description: Collection of files associated with this asset.
          nullable: true
      description: Digital asset response with embedded metadata and file collections.
    AssetLifecycleRequest:
      required:
        - transition
      type: object
      properties:
        transition:
          enum:
            - remove
            - restore
            - publish
            - unpublish
            - archive
            - unarchive
          type: string
          description: Lifecycle transition to apply to the asset.
      description: Request to transition an asset to a different lifecycle state.
    AssetResponse:
      required:
        - uuid
        - createdAt
        - updatedAt
        - status
        - category
        - storageLocation
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this asset.
          format: uuid
        createdAt:
          type: string
          description: Timestamp when this asset was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          description: Timestamp when this asset was last modified.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        removedAt:
          type: string
          description: Timestamp when this asset was removed. Null if not removed.
          format: date-time
          nullable: true
          example: '2025-11-23T14:15:22.123456Z'
        archivedAt:
          type: string
          description: Timestamp when this asset was archived. Null if not archived.
          format: date-time
          nullable: true
          example: '2025-11-23T14:15:22.123456Z'
        status:
          enum:
            - draft
            - published
            - unpublished
            - archived
            - removed
          type: string
          description: Current lifecycle status of this asset.
        category:
          enum:
            - image
            - video
            - audio
            - document
            - design
            - archive
            - data
          type: string
          description: Category classification for this asset.
        storageLocation:
          enum:
            - s3
          type: string
          description: Storage backend where associated files reside.
        name:
          type: string
          description: Display name for this asset.
          nullable: true
        description:
          type: string
          description: Optional detailed description for this asset.
          nullable: true
        altText:
          type: string
          description: Alternative text for accessibility and SEO purposes.
          nullable: true
      description: Digital asset response containing metadata and lifecycle information.
    AssetUpdateRequest:
      type: object
      properties:
        name:
          maxLength: 255
          minLength: 1
          type: string
          description: Updated display name for the asset.
          nullable: true
        description:
          maxLength: 1000
          type: string
          description: Updated detailed description for the asset.
          nullable: true
        altText:
          maxLength: 500
          type: string
          description: Updated alternative text for the asset.
          nullable: true
      description: Request to update an existing asset. All fields are optional.
    AttributeBulkCreateRequest:
      required:
        - name
      type: object
      properties:
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Display name for the attribute.
        description:
          maxLength: 500
          type: string
          description: Optional explanation of what this attribute represents.
          nullable: true
      description: Request to create multiple attributes in a single operation.
    AttributeBulkLifecycleRequest:
      required:
        - transition
        - uuids
      type: object
      properties:
        transition:
          enum:
            - publish
            - unpublish
            - remove
            - restore
          type: string
          description: Lifecycle transition to apply to all specified attributes.
        uuids:
          type: array
          items:
            type: string
            format: uuid
          description: List of attribute identifiers to transition.
      description: >-
        Request to transition multiple attributes to a different lifecycle
        state.
    AttributeBulkUpdateRequest:
      required:
        - uuid
      type: object
      properties:
        uuid:
          type: string
          description: Identifier of the attribute to update.
          format: uuid
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Updated display name for the attribute.
          nullable: true
        description:
          maxLength: 500
          type: string
          description: Updated explanation of the attribute.
          nullable: true
      description: Request to update multiple attributes in a single operation.
    AttributeCreateRequest:
      required:
        - name
      type: object
      properties:
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Display name for the attribute.
        description:
          maxLength: 500
          type: string
          description: >-
            Optional explanation of what this attribute represents and when to
            use it.
          nullable: true
      description: Request to create a new attribute.
    AttributeLifecycleRequest:
      required:
        - transition
      type: object
      properties:
        transition:
          enum:
            - publish
            - unpublish
            - remove
            - restore
          type: string
          description: >-
            Lifecycle transition to apply. Valid transitions depend on current
            status.
      description: Request to transition an attribute to a different lifecycle state.
    AttributeResponse:
      required:
        - uuid
        - createdAt
        - updatedAt
        - status
        - name
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this attribute.
          format: uuid
        createdAt:
          type: string
          description: Timestamp when this attribute was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          description: Timestamp when this attribute was last modified.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        removedAt:
          type: string
          description: Timestamp when this attribute was removed. Null if not removed.
          format: date-time
          nullable: true
          example: '2025-11-23T14:15:22.123456Z'
        status:
          enum:
            - draft
            - published
            - unpublished
            - removed
          type: string
          description: Current lifecycle status of this attribute.
        name:
          type: string
          description: Display name for this attribute.
        description:
          type: string
          description: Explanation of what this attribute represents and when to use it.
          nullable: true
      description: Attribute defining a data point that can be associated with products.
    AttributeUpdateRequest:
      type: object
      properties:
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Updated display name for the attribute.
          nullable: true
        description:
          maxLength: 500
          type: string
          description: Updated explanation of the attribute.
          nullable: true
      description: Request to update an existing attribute.
    CategoryBulkCreateRequest:
      required:
        - name
      type: object
      properties:
        parentUuid:
          type: string
          description: Optional parent category UUID for hierarchical organization.
          format: uuid
          nullable: true
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Display name for the category.
        description:
          maxLength: 500
          type: string
          description: Optional detailed description of the category's purpose and scope.
          nullable: true
      description: Request to create multiple categories in a single operation.
    CategoryBulkLifecycleRequest:
      required:
        - transition
        - uuids
      type: object
      properties:
        transition:
          enum:
            - remove
            - restore
            - publish
            - unpublish
          type: string
          description: Lifecycle transition to apply to all specified categories.
        uuids:
          type: array
          items:
            type: string
            format: uuid
          description: List of category identifiers to transition.
      description: >-
        Request to transition multiple categories to a different lifecycle
        state.
    CategoryBulkUpdateRequest:
      required:
        - uuid
      type: object
      properties:
        uuid:
          type: string
          description: Identifier of the category to update.
          format: uuid
        parentUuid:
          type: string
          description: Updated parent category UUID.
          format: uuid
          nullable: true
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Updated display name for the category.
          nullable: true
        description:
          maxLength: 500
          type: string
          description: Updated description for the category.
          nullable: true
      description: Request to update multiple categories in a single operation.
    CategoryCreateRequest:
      required:
        - name
      type: object
      properties:
        parentUuid:
          type: string
          description: Optional parent category UUID for hierarchical organization.
          format: uuid
          nullable: true
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Display name for the category.
        description:
          maxLength: 500
          type: string
          description: Optional detailed description of the category's purpose and scope.
          nullable: true
      description: Request to create a new category.
    CategoryLifecycleRequest:
      required:
        - transition
      type: object
      properties:
        transition:
          enum:
            - remove
            - restore
            - publish
            - unpublish
          type: string
          description: >-
            Lifecycle transition to apply. Valid transitions depend on current
            status.
      description: Request to transition a category to a different lifecycle state.
    CategoryResponse:
      required:
        - uuid
        - createdAt
        - updatedAt
        - status
        - name
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this category.
          format: uuid
        parentUuid:
          type: string
          description: >-
            Identifier of the parent category for hierarchical organization.
            Null if this is a root category.
          format: uuid
          nullable: true
        createdAt:
          type: string
          description: Timestamp when this category was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          description: Timestamp when this category was last modified.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        removedAt:
          type: string
          description: Timestamp when this category was removed. Null if not removed.
          format: date-time
          nullable: true
          example: '2025-11-23T14:15:22.123456Z'
        status:
          enum:
            - draft
            - published
            - unpublished
            - removed
          type: string
          description: Current lifecycle status of this category.
        name:
          type: string
          description: Display name for this category.
        description:
          type: string
          description: >-
            Detailed description of the category's purpose and which products it
            applies to.
          nullable: true
      description: Category for hierarchical product classification.
    CategoryUpdateRequest:
      type: object
      properties:
        parentUuid:
          type: string
          description: >-
            Updated parent category UUID. Set to null to remove parent
            relationship.
          format: uuid
          nullable: true
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Updated display name for the category.
          nullable: true
        description:
          maxLength: 500
          type: string
          description: Updated description for the category.
          nullable: true
      description: Request to update an existing category.
    DimensionCreateRequest:
      required:
        - length
        - width
        - height
      type: object
      properties:
        length:
          type: number
          description: >-
            Length measurement in the organization's base dimension unit.
            Maximum: 99999999999999.9999.
          format: double
        width:
          type: number
          description: >-
            Width measurement in the organization's base dimension unit.
            Maximum: 99999999999999.9999.
          format: double
        height:
          type: number
          description: >-
            Height measurement in the organization's base dimension unit.
            Maximum: 99999999999999.9999.
          format: double
      description: Request to set dimensions for a SKU.
    DimensionResponse:
      required:
        - skuUuid
        - unit
        - length
        - width
        - height
        - conversions
      type: object
      properties:
        skuUuid:
          type: string
          description: Identifier of the SKU these dimensions belong to.
          format: uuid
        unit:
          enum:
            - millimeter
            - centimeter
            - meter
            - inch
            - foot
          type: string
          description: Base unit of measurement for the dimension values.
        length:
          type: number
          description: Length measurement in the base unit.
          format: double
        width:
          type: number
          description: Width measurement in the base unit.
          format: double
        height:
          type: number
          description: Height measurement in the base unit.
          format: double
        conversions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DimensionValues'
          description: >-
            System-calculated conversions to other configured dimension units.
            Keys are unit identifiers, values contain converted measurements.
      description: Physical dimensions for a SKU.
    DimensionUpdateRequest:
      type: object
      properties:
        length:
          type: number
          description: 'Updated length measurement. Maximum: 99999999999999.9999.'
          format: double
          nullable: true
        width:
          type: number
          description: 'Updated width measurement. Maximum: 99999999999999.9999.'
          format: double
          nullable: true
        height:
          type: number
          description: 'Updated height measurement. Maximum: 99999999999999.9999.'
          format: double
          nullable: true
      description: Request to update dimensions for a SKU. All fields are optional.
    DimensionValues:
      required:
        - length
        - width
        - height
      type: object
      properties:
        length:
          type: number
          description: Converted length measurement.
          format: double
        width:
          type: number
          description: Converted width measurement.
          format: double
        height:
          type: number
          description: Converted height measurement.
          format: double
      description: Dimension measurements converted to a specific unit.
    FamilyAttributeBulkCreateRequest:
      required:
        - attributeUuid
        - requirementLevel
        - isAutoPopulated
      type: object
      properties:
        attributeUuid:
          type: string
          description: Identifier of the attribute to associate with this family.
          format: uuid
        requirementLevel:
          enum:
            - may
            - must
            - mustNot
            - should
          type: string
          description: >-
            Defines the requirement level for this attribute on products in this
            family.
        isAutoPopulated:
          type: boolean
          description: Whether this attribute is automatically added to new products.
      description: >-
        Request to associate multiple attributes with a family in a single
        operation.
    FamilyAttributeBulkUpdateRequest:
      required:
        - uuid
      type: object
      properties:
        uuid:
          type: string
          description: Identifier of the family-attribute association to update.
          format: uuid
        requirementLevel:
          $ref: '#/components/schemas/NullableOfRequirementLevel'
        isAutoPopulated:
          type: boolean
          description: Updated auto-population setting for this attribute.
          nullable: true
      description: >-
        Request to update multiple family-attribute associations in a single
        operation.
    FamilyAttributeCreateRequest:
      required:
        - attributeUuid
        - requirementLevel
        - isAutoPopulated
      type: object
      properties:
        attributeUuid:
          type: string
          description: Identifier of the attribute to associate with this family.
          format: uuid
        requirementLevel:
          enum:
            - may
            - must
            - mustNot
            - should
          type: string
          description: >-
            Defines the requirement level for this attribute on products in this
            family.
        isAutoPopulated:
          type: boolean
          description: >-
            Whether this attribute is automatically added to new products in
            this family.
      description: Request to associate an attribute with a family.
    FamilyAttributeResponse:
      required:
        - uuid
        - familyUuid
        - attributeUuid
        - createdAt
        - updatedAt
        - requirementLevel
        - isAutoPopulated
        - attributeName
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this family-attribute association.
          format: uuid
        familyUuid:
          type: string
          description: Identifier of the family this attribute is associated with.
          format: uuid
        attributeUuid:
          type: string
          description: Identifier of the attribute associated with this family.
          format: uuid
        createdAt:
          type: string
          description: Timestamp when this association was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          description: Timestamp when this association was last modified.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        requirementLevel:
          enum:
            - may
            - must
            - mustNot
            - should
          type: string
          description: >-
            Defines the requirement level for this attribute on products in this
            family.
        isAutoPopulated:
          type: boolean
          description: >-
            Whether products created in this family automatically receive this
            attribute with a default value.
        attributeName:
          type: string
          description: Display name of the associated attribute for convenience.
      description: >-
        Association between a family and an attribute, defining data
        requirements for products.
    FamilyAttributeUpdateRequest:
      type: object
      properties:
        requirementLevel:
          $ref: '#/components/schemas/NullableOfRequirementLevel'
        isAutoPopulated:
          type: boolean
          description: Updated auto-population setting for this attribute.
          nullable: true
      description: >-
        Request to update a family-attribute association. All fields are
        optional.
    FamilyBulkCreateRequest:
      required:
        - name
      type: object
      properties:
        parentUuid:
          type: string
          description: Optional parent family UUID for hierarchical organization.
          format: uuid
          nullable: true
        name:
          maxLength: 100
          minLength: 3
          type: string
          description: Display name for the family.
        description:
          maxLength: 1000
          type: string
          description: Optional detailed description of the family's purpose and scope.
          nullable: true
      description: Request to create multiple families in a single operation.
    FamilyBulkLifecycleRequest:
      required:
        - transition
        - uuids
      type: object
      properties:
        transition:
          enum:
            - activate
            - deactivate
            - remove
            - restore
          type: string
          description: Lifecycle transition to apply to all specified families.
        uuids:
          type: array
          items:
            type: string
            format: uuid
          description: List of family identifiers to transition.
      description: Request to transition multiple families to a different lifecycle state.
    FamilyBulkUpdateRequest:
      required:
        - uuid
      type: object
      properties:
        uuid:
          type: string
          description: Identifier of the family to update.
          format: uuid
        parentUuid:
          type: string
          description: Updated parent family UUID.
          format: uuid
          nullable: true
        name:
          maxLength: 100
          minLength: 3
          type: string
          description: Updated display name for the family.
          nullable: true
        description:
          maxLength: 1000
          type: string
          description: Updated description for the family.
          nullable: true
      description: Request to update multiple families in a single operation.
    FamilyCategoryBulkCreateRequest:
      required:
        - categoryUuid
        - requirementLevel
        - isAutoPopulated
      type: object
      properties:
        categoryUuid:
          type: string
          description: Identifier of the category to associate with this family.
          format: uuid
        requirementLevel:
          enum:
            - may
            - must
            - mustNot
            - should
          type: string
          description: >-
            Defines the requirement level for this category on products in this
            family.
        isAutoPopulated:
          type: boolean
          description: >-
            Whether this category assignment is automatically applied to new
            products.
      description: >-
        Request to associate multiple categories with a family in a single
        operation.
    FamilyCategoryBulkUpdateRequest:
      required:
        - uuid
      type: object
      properties:
        uuid:
          type: string
          description: Identifier of the family-category association to update.
          format: uuid
        requirementLevel:
          $ref: '#/components/schemas/NullableOfRequirementLevel2'
        isAutoPopulated:
          type: boolean
          description: Updated auto-population setting for this category.
          nullable: true
      description: >-
        Request to update multiple family-category associations in a single
        operation.
    FamilyCategoryCreateRequest:
      required:
        - categoryUuid
        - requirementLevel
        - isAutoPopulated
      type: object
      properties:
        categoryUuid:
          type: string
          description: Identifier of the category to associate with this family.
          format: uuid
        requirementLevel:
          enum:
            - may
            - must
            - mustNot
            - should
          type: string
          description: >-
            Defines the requirement level for this category on products in this
            family.
        isAutoPopulated:
          type: boolean
          description: >-
            Whether this category assignment is automatically applied to new
            products in this family.
      description: Request to associate a category with a family.
    FamilyCategoryResponse:
      required:
        - uuid
        - familyUuid
        - categoryUuid
        - createdAt
        - updatedAt
        - requirementLevel
        - isAutoPopulated
        - categoryName
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this family-category association.
          format: uuid
        familyUuid:
          type: string
          description: Identifier of the family this category is associated with.
          format: uuid
        categoryUuid:
          type: string
          description: Identifier of the category associated with this family.
          format: uuid
        createdAt:
          type: string
          description: Timestamp when this association was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          description: Timestamp when this association was last modified.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        requirementLevel:
          enum:
            - may
            - must
            - mustNot
            - should
          type: string
          description: >-
            Defines the requirement level for this category on products in this
            family.
        isAutoPopulated:
          type: boolean
          description: >-
            Whether products created in this family automatically receive this
            category assignment.
        categoryName:
          type: string
          description: Display name of the associated category for convenience.
      description: >-
        Association between a family and a category, defining categorization
        requirements.
    FamilyCategoryUpdateRequest:
      type: object
      properties:
        requirementLevel:
          $ref: '#/components/schemas/NullableOfRequirementLevel2'
        isAutoPopulated:
          type: boolean
          description: Updated auto-population setting for this category.
          nullable: true
      description: >-
        Request to update a family-category association. All fields are
        optional.
    FamilyCreateRequest:
      required:
        - name
      type: object
      properties:
        parentUuid:
          type: string
          description: Optional parent family UUID for hierarchical organization.
          format: uuid
          nullable: true
        name:
          maxLength: 100
          minLength: 3
          type: string
          description: Display name for the family.
        description:
          maxLength: 1000
          type: string
          description: Optional detailed description of the family's purpose and scope.
          nullable: true
      description: Request to create a new product family.
    FamilyLifecycleRequest:
      required:
        - transition
      type: object
      properties:
        transition:
          enum:
            - activate
            - deactivate
            - remove
            - restore
          type: string
          description: >-
            Lifecycle transition to apply. Valid transitions depend on current
            status.
      description: Request to transition a family to a different lifecycle state.
    FamilyResponse:
      required:
        - uuid
        - createdAt
        - updatedAt
        - status
        - name
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this family.
          format: uuid
        parentUuid:
          type: string
          description: >-
            Identifier of the parent family for hierarchical organization. Null
            if this is a root family.
          format: uuid
          nullable: true
        createdAt:
          type: string
          description: Timestamp when this family was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          description: Timestamp when this family was last modified.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        removedAt:
          type: string
          description: Timestamp when this family was removed. Null if not removed.
          format: date-time
          nullable: true
          example: '2025-11-23T14:15:22.123456Z'
        status:
          enum:
            - draft
            - active
            - inactive
            - removed
          type: string
          description: Current lifecycle status of this family.
        name:
          type: string
          description: Display name for this family.
        description:
          type: string
          description: >-
            Detailed description of the family's purpose and which products it
            applies to.
          nullable: true
      description: Product family defining structure and requirements for a product type.
    FamilyUpdateRequest:
      type: object
      properties:
        parentUuid:
          type: string
          description: >-
            Updated parent family UUID. Set to null to remove parent
            relationship.
          format: uuid
          nullable: true
        name:
          maxLength: 100
          minLength: 3
          type: string
          description: Updated display name for the family.
          nullable: true
        description:
          maxLength: 1000
          type: string
          description: Updated description for the family.
          nullable: true
      description: Request to update an existing family. All fields are optional.
    FileBulkCompleteUploadRequest:
      required:
        - assetUuid
        - fileUuid
        - checksum
      type: object
      properties:
        assetUuid:
          type: string
          description: Identifier of the asset associated with the file.
          format: uuid
        fileUuid:
          type: string
          description: Identifier of the file to complete.
          format: uuid
        checksum:
          maxLength: 64
          minLength: 64
          type: string
          description: SHA-256 checksum of the uploaded file for integrity verification.
      description: Request to complete multiple file uploads after transfer is finished.
    FileBulkInitiateUploadRequest:
      required:
        - assetUuid
        - variationType
        - storageLocation
        - mimeType
        - extension
      type: object
      properties:
        assetUuid:
          type: string
          description: Identifier of the asset to associate files with.
          format: uuid
        variationType:
          enum:
            - original
            - thumbnail
            - webOptimized
            - mobileOptimized
            - productDetail
            - printReady
            - socialMedia
            - videoPoster
            - videoPreview
            - videoStreamLow
            - videoStreamMedium
            - videoStreamHigh
          type: string
          description: Type of file variation being uploaded.
        storageLocation:
          enum:
            - s3
          type: string
          description: Storage backend where the file will be stored.
        mimeType:
          maxLength: 255
          type: string
          description: MIME type of the file being uploaded.
        extension:
          maxLength: 10
          type: string
          description: File extension of the file being uploaded.
      description: Request to initiate multiple file uploads in a single operation.
    FileCompleteUploadRequest:
      required:
        - checksum
      type: object
      properties:
        checksum:
          maxLength: 64
          minLength: 64
          type: string
          description: SHA-256 checksum of the uploaded file for integrity verification.
      description: Request to complete a file upload after transfer is finished.
    FileInitiateUploadRequest:
      required:
        - variationType
        - storageLocation
        - mimeType
        - extension
      type: object
      properties:
        variationType:
          enum:
            - original
            - thumbnail
            - webOptimized
            - mobileOptimized
            - productDetail
            - printReady
            - socialMedia
            - videoPoster
            - videoPreview
            - videoStreamLow
            - videoStreamMedium
            - videoStreamHigh
          type: string
          description: Type of file variation being uploaded.
        storageLocation:
          enum:
            - s3
          type: string
          description: Storage backend where the file will be stored.
        mimeType:
          maxLength: 255
          type: string
          description: MIME type of the file being uploaded.
        extension:
          maxLength: 10
          type: string
          description: File extension of the file being uploaded.
      description: Request to initiate a file upload for an asset.
    FileItem:
      required:
        - uuid
        - createdAt
        - status
        - variationType
        - storageLocation
        - mimeType
        - extension
        - storageKey
        - checksum
        - isAutogenerated
        - presignedUrl
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this file.
          format: uuid
        createdAt:
          type: string
          description: Timestamp when this file was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        status:
          enum:
            - awaitingUpload
            - uploaded
          type: string
          description: Current lifecycle status of this file.
        variationType:
          enum:
            - original
            - thumbnail
            - webOptimized
            - mobileOptimized
            - productDetail
            - printReady
            - socialMedia
            - videoPoster
            - videoPreview
            - videoStreamLow
            - videoStreamMedium
            - videoStreamHigh
          type: string
          description: Type of file variation.
        storageLocation:
          enum:
            - s3
          type: string
          description: Storage backend where this file is stored.
        mimeType:
          type: string
          description: MIME type of this file.
        extension:
          type: string
          description: File extension of this file.
        storageKey:
          type: string
          description: Storage backend key path for this file.
        storageSize:
          type: integer
          description: File size in bytes. Null if not yet calculated.
          format: int64
          nullable: true
        checksum:
          type: string
          description: SHA-256 checksum for file integrity verification.
        isAutogenerated:
          type: boolean
          description: Whether this file was automatically generated by the system.
        presignedUrl:
          type: string
          description: Temporary pre-signed URL for downloading this file.
      description: File entity embedded within an asset response.
    FileResponse:
      required:
        - uuid
        - assetUuid
        - createdAt
        - status
        - variationType
        - storageLocation
        - mimeType
        - extension
        - checksum
        - isAutogenerated
        - presignedUrl
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this file.
          format: uuid
        assetUuid:
          type: string
          description: Identifier of the parent asset this file belongs to.
          format: uuid
        createdAt:
          type: string
          description: Timestamp when this file was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        status:
          enum:
            - awaitingUpload
            - uploaded
          type: string
          description: Current lifecycle status of this file.
        variationType:
          enum:
            - original
            - thumbnail
            - webOptimized
            - mobileOptimized
            - productDetail
            - printReady
            - socialMedia
            - videoPoster
            - videoPreview
            - videoStreamLow
            - videoStreamMedium
            - videoStreamHigh
          type: string
          description: Type of file variation.
        storageLocation:
          enum:
            - s3
          type: string
          description: Storage backend where this file is stored.
        mimeType:
          type: string
          description: MIME type of this file.
        extension:
          type: string
          description: File extension of this file.
        storageSize:
          type: integer
          description: File size in bytes. Null if not yet calculated.
          format: int64
          nullable: true
        checksum:
          type: string
          description: SHA-256 checksum for file integrity verification.
        isAutogenerated:
          type: boolean
          description: Whether this file was automatically generated by the system.
        presignedUrl:
          type: string
          description: Temporary pre-signed URL for downloading this file.
      description: >-
        File entity associated with an asset, including storage details and
        download URL.
    MemberChangeRoleRequest:
      required:
        - organizationRoleUuid
      type: object
      properties:
        organizationRoleUuid:
          type: string
          format: uuid
    MemberCreateRequest:
      required:
        - accountUuid
        - roleUuid
      type: object
      properties:
        accountUuid:
          type: string
          format: uuid
        roleUuid:
          type: string
          format: uuid
    MemberLifecycleRequest:
      required:
        - transition
      type: object
      properties:
        transition:
          enum:
            - activate
            - deactivate
            - restore
          type: string
    MemberResponse:
      required:
        - organizationUuid
        - accountUuid
        - roleUuid
        - createdAt
        - updatedAt
        - removedAt
        - status
        - isOwner
      type: object
      properties:
        organizationUuid:
          type: string
          format: uuid
        accountUuid:
          type: string
          format: uuid
        roleUuid:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        removedAt:
          type: string
          format: date-time
          nullable: true
          example: '2025-11-23T14:15:22.123456Z'
        status:
          enum:
            - active
            - inactive
            - removed
          type: string
        isOwner:
          type: boolean
    MetadataCreateRequest:
      required:
        - key
        - value
      type: object
      properties:
        key:
          maxLength: 255
          minLength: 1
          type: string
          description: Metadata key name.
        value:
          maxLength: 1000
          minLength: 1
          type: string
          description: Metadata value content.
      description: Request to create a new metadata entry for an asset.
    MetadataItem:
      required:
        - uuid
        - createdAt
        - updatedAt
        - key
        - value
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this metadata entry.
          format: uuid
        createdAt:
          type: string
          description: Timestamp when this metadata entry was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          description: Timestamp when this metadata entry was last modified.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        key:
          type: string
          description: Metadata key name.
        value:
          type: string
          description: Metadata value content.
      description: Metadata key-value pair embedded within an asset response.
    MetadataResponse:
      required:
        - uuid
        - assetUuid
        - createdAt
        - updatedAt
        - key
        - value
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this metadata entry.
          format: uuid
        assetUuid:
          type: string
          description: Identifier of the asset this metadata belongs to.
          format: uuid
        createdAt:
          type: string
          description: Timestamp when this metadata entry was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          description: Timestamp when this metadata entry was last modified.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        key:
          type: string
          description: Metadata key name.
        value:
          type: string
          description: Metadata value content.
      description: Custom metadata key-value pair associated with an asset.
    MetadataUpdateRequest:
      type: object
      properties:
        key:
          maxLength: 255
          minLength: 1
          type: string
          description: Updated metadata key name.
          nullable: true
        value:
          maxLength: 1000
          minLength: 1
          type: string
          description: Updated metadata value content.
          nullable: true
      description: Request to update an existing metadata entry. All fields are optional.
    NullableOfRequirementLevel:
      type: integer
      description: Updated requirement level for this attribute.
      nullable: true
    NullableOfRequirementLevel2:
      type: integer
      description: Updated requirement level for this category.
      nullable: true
    OrganizationResponse:
      required:
        - uuid
        - createdAt
        - updatedAt
        - name
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        name:
          type: string
    OrganizationUpdateRequest:
      required:
        - name
      type: object
      properties:
        name:
          type: string
          nullable: true
    PagedResultOfAssetHydratedResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AssetHydratedResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PagedResultOfAttributeResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AttributeResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PagedResultOfCategoryResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CategoryResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PagedResultOfFamilyAttributeResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FamilyAttributeResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PagedResultOfFamilyCategoryResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FamilyCategoryResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PagedResultOfFamilyResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FamilyResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PagedResultOfFileResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FileResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PagedResultOfMemberResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MemberResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PagedResultOfMetadataResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MetadataResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PagedResultOfRoleResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/RoleResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PagedResultOfSkuResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SkuResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PagedResultOfTagResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TagResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PagedResultOfTermResponse:
      required:
        - items
        - pagination
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TermResponse'
        pagination:
          $ref: '#/components/schemas/PaginationResult'
    PaginationResult:
      required:
        - page
        - size
        - totalItems
        - totalPages
      type: object
      properties:
        page:
          type: integer
          format: int32
        size:
          type: integer
          format: int32
        totalItems:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
    ProblemDetails2:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
        correlationId:
          type: string
          nullable: true
    RoleCreateRequest:
      required:
        - name
        - description
      type: object
      properties:
        name:
          type: string
        description:
          type: string
          nullable: true
    RoleResponse:
      required:
        - uuid
        - organizationUuid
        - createdAt
        - updatedAt
        - name
        - description
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        organizationUuid:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        name:
          type: string
        description:
          type: string
          nullable: true
    RoleUpdateRequest:
      required:
        - name
        - description
      type: object
      properties:
        name:
          type: string
        description:
          type: string
          nullable: true
    SkuBulkCreateRequest:
      required:
        - code
      type: object
      properties:
        code:
          maxLength: 55
          type: string
          description: Unique code identifying the SKU.
      description: Request to create multiple SKUs in a single operation.
    SkuBulkLifecycleRequest:
      required:
        - transition
        - uuids
      type: object
      properties:
        transition:
          enum:
            - remove
            - restore
            - publish
            - unpublish
          type: string
          description: Lifecycle transition to apply to all specified SKUs.
        uuids:
          type: array
          items:
            type: string
            format: uuid
          description: List of SKU identifiers to transition.
      description: Request to transition multiple SKUs to a different lifecycle state.
    SkuBulkUpdateRequest:
      required:
        - uuid
      type: object
      properties:
        uuid:
          type: string
          description: Identifier of the SKU to update.
          format: uuid
        code:
          maxLength: 55
          type: string
          description: Updated code for the SKU.
          nullable: true
      description: Request to update multiple SKUs in a single operation.
    SkuCreateRequest:
      required:
        - code
      type: object
      properties:
        code:
          maxLength: 55
          type: string
          description: Unique code identifying the SKU.
      description: Request to create a new SKU.
    SkuLifecycleRequest:
      required:
        - transition
      type: object
      properties:
        transition:
          enum:
            - remove
            - restore
            - publish
            - unpublish
          type: string
          description: >-
            Lifecycle transition to apply. Valid transitions depend on current
            status.
      description: Request to transition a SKU to a different lifecycle state.
    SkuResponse:
      required:
        - uuid
        - createdAt
        - updatedAt
        - status
        - code
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this SKU.
          format: uuid
        createdAt:
          type: string
          description: Timestamp when this SKU was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          description: Timestamp when this SKU was last modified.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        removedAt:
          type: string
          description: Timestamp when this SKU was removed. Null if not removed.
          format: date-time
          nullable: true
          example: '2025-11-23T14:15:22.123456Z'
        status:
          enum:
            - draft
            - published
            - unpublished
            - removed
          type: string
          description: Current lifecycle status of this SKU.
        code:
          type: string
          description: Unique code identifying this SKU.
      description: Stock keeping unit representing a sellable item variant.
    SkuUpdateRequest:
      type: object
      properties:
        code:
          maxLength: 55
          type: string
          description: Updated code for the SKU.
          nullable: true
      description: Request to update an existing SKU.
    TagBulkCreateRequest:
      required:
        - name
      type: object
      properties:
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Display name for the tag.
        description:
          maxLength: 500
          type: string
          description: Optional explanation of what this tag represents.
          nullable: true
      description: Request to create multiple tags in a single operation.
    TagBulkLifecycleRequest:
      required:
        - transition
        - uuids
      type: object
      properties:
        transition:
          enum:
            - remove
            - restore
            - publish
            - unpublish
          type: string
          description: Lifecycle transition to apply to all specified tags.
        uuids:
          type: array
          items:
            type: string
            format: uuid
          description: List of tag identifiers to transition.
      description: Request to transition multiple tags to a different lifecycle state.
    TagBulkUpdateRequest:
      required:
        - uuid
      type: object
      properties:
        uuid:
          type: string
          description: Identifier of the tag to update.
          format: uuid
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Updated display name for the tag.
          nullable: true
        description:
          maxLength: 500
          type: string
          description: Updated explanation of the tag.
          nullable: true
      description: Request to update multiple tags in a single operation.
    TagCreateRequest:
      required:
        - name
      type: object
      properties:
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Display name for the tag.
        description:
          maxLength: 500
          type: string
          description: >-
            Optional explanation of what this tag represents and when to apply
            it.
          nullable: true
      description: Request to create a new tag.
    TagLifecycleRequest:
      required:
        - transition
      type: object
      properties:
        transition:
          enum:
            - remove
            - restore
            - publish
            - unpublish
          type: string
          description: >-
            Lifecycle transition to apply. Valid transitions depend on current
            status.
      description: Request to transition a tag to a different lifecycle state.
    TagResponse:
      required:
        - uuid
        - createdAt
        - updatedAt
        - status
        - name
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this tag.
          format: uuid
        createdAt:
          type: string
          description: Timestamp when this tag was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          description: Timestamp when this tag was last modified.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        removedAt:
          type: string
          description: Timestamp when this tag was removed. Null if not removed.
          format: date-time
          nullable: true
          example: '2025-11-23T14:15:22.123456Z'
        status:
          enum:
            - draft
            - published
            - unpublished
            - removed
          type: string
          description: Current lifecycle status of this tag.
        name:
          type: string
          description: Display name for this tag.
        description:
          type: string
          description: Explanation of what this tag represents and when to apply it.
          nullable: true
      description: Tag for flexible product classification and filtering.
    TagUpdateRequest:
      type: object
      properties:
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Updated display name for the tag.
          nullable: true
        description:
          maxLength: 500
          type: string
          description: Updated explanation of the tag.
          nullable: true
      description: Request to update an existing tag.
    TermCreateRequest:
      required:
        - name
      type: object
      properties:
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Term value that can be assigned to products.
      description: Request to create a new term for an attribute.
    TermResponse:
      required:
        - uuid
        - attributeUuid
        - createdAt
        - updatedAt
        - name
      type: object
      properties:
        uuid:
          type: string
          description: Unique identifier for this term.
          format: uuid
        attributeUuid:
          type: string
          description: Identifier of the attribute this term belongs to.
          format: uuid
        createdAt:
          type: string
          description: Timestamp when this term was created.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        updatedAt:
          type: string
          description: Timestamp when this term was last modified.
          format: date-time
          example: '2025-11-23T14:15:22.123456Z'
        name:
          type: string
          description: Term value that can be assigned to products.
      description: Term representing an allowed value for an attribute.
    TermUpdateRequest:
      type: object
      properties:
        name:
          maxLength: 100
          minLength: 1
          type: string
          description: Updated term value.
          nullable: true
      description: Request to update an existing term.
    ValidationError:
      required:
        - code
        - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    ValidationProblemDetails:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
        correlationId:
          type: string
          nullable: true
    WeightCreateRequest:
      required:
        - weight
      type: object
      properties:
        weight:
          type: number
          description: >-
            Weight measurement in the organization's base weight unit. Maximum:
            99999999999999.9999.
          format: double
      description: Request to set weight for a SKU.
    WeightResponse:
      required:
        - skuUuid
        - unit
        - weight
        - conversions
      type: object
      properties:
        skuUuid:
          type: string
          description: Identifier of the SKU this weight belongs to.
          format: uuid
        unit:
          enum:
            - gram
            - kilogram
            - pound
            - ounce
          type: string
          description: Base unit of measurement for the weight value.
        weight:
          type: number
          description: Weight measurement in the base unit.
          format: double
        conversions:
          type: object
          additionalProperties:
            type: number
            format: double
          description: >-
            System-calculated conversions to other configured weight units. Keys
            are unit identifiers, values are converted weights.
      description: Weight information for a SKU.
    WeightUpdateRequest:
      type: object
      properties:
        weight:
          type: number
          description: 'Updated weight measurement. Maximum: 99999999999999.9999.'
          format: double
          nullable: true
      description: Request to update weight for a SKU.
  securitySchemes:
    Bearer:
      type: http
      description: Enter your JWT token
      scheme: bearer
      bearerFormat: JWT
tags:
  - name: Tags
  - name: Skus
  - name: Sku Dimensions
  - name: Sku Weights
  - name: Family Attributes
  - name: Family Categories
  - name: Families
  - name: Organization Members
  - name: Organizations
  - name: Organization Roles
  - name: Categories
  - name: Attributes
  - name: Attribute Terms
  - name: Assets
  - name: Asset Files
  - name: Asset Metadata
