openapi: 3.2.0
info:
  title: Kubex Subscriptions Suppressions API
  version: 1.0.0
  description: 'Catalog of suppression entries (attribute tags or recommendation properties)

    that can be referenced by subscriptions via `suppressionReferences`. Each

    platform (`cloud` or `containers`) has its own catalog; the alias without

    platform behaves like the cloud catalog. Bulk adds/updates are all-or-nothing,

    while bulk deletes process entries independently.'
servers:
- url: https://{host}
  variables:
    host:
      default: api.example.com
tags:
- name: Subscriptions Suppressions
paths:
  /subscriptions/{platformType}/suppressions:
    get:
      tags:
      - Subscriptions Suppressions
      operationId: listSuppressions
      summary: List suppressions for a platform
      description: 'Returns global/private suppression entries; use `type` and (admin only)

        `owner` to filter.'
      parameters:
      - $ref: '#/components/parameters/platformType'
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/owner'
      responses:
        '200':
          description: Suppression list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Suppression'
    post:
      tags:
      - Subscriptions Suppressions
      operationId: createSuppressions
      summary: Add suppressions (bulk; all-or-nothing)
      description: 'Adds one or more entries. A suppression is either an **attribute** suppression

        (`attributeName`, optionally with `key` + `technology` for Resource Tags /

        Container Labels) **or** a **property** suppression (`propertyName`). Uniqueness

        and owner rules apply; non-admins can only add private entries.'
      parameters:
      - $ref: '#/components/parameters/platformType'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/SuppressionCreate'
      responses:
        '200':
          description: Created entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Suppression'
        '400':
          description: Validation/logic error; entire batch rolled back.
    put:
      tags:
      - Subscriptions Suppressions
      operationId: replaceSuppressions
      summary: Replace suppressions (bulk PUT; all-or-nothing)
      description: 'Deletes and replaces parameters for existing entries. Supply **all**

        parameters required by each entry. Admins can promote private→global by

        setting `owner: ""`.'
      parameters:
      - $ref: '#/components/parameters/platformType'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/SuppressionUpdate'
      responses:
        '200':
          description: Updated entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Suppression'
        '400':
          description: Validation/logic error; entire batch rolled back.
    delete:
      tags:
      - Subscriptions Suppressions
      operationId: deleteSuppressions
      summary: Delete suppressions (bulk; independent per entry)
      description: 'Deletes a collection of entries by `suppressionRef`. If **all** succeed,

        returns 204. If any fail, returns an array with per-entry status/messages

        for failures; successful deletes may omit a message. Suppressions referenced

        by subscriptions cannot be deleted.'
      parameters:
      - $ref: '#/components/parameters/platformType'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                type: object
                properties:
                  suppressionRef:
                    type: string
                required:
                - suppressionRef
      responses:
        '204':
          description: No Content (all deletes succeeded).
        '200':
          description: Per-entry delete results (partial failures and/or mixed outcomes)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeleteResult'
        '404':
          description: Not found (when deleting a single entry via /suppressionRef).
  /subscriptions/{platformType}/suppressions/{suppressionRef}:
    get:
      tags:
      - Subscriptions Suppressions
      operationId: getSuppression
      summary: Get a suppression by ID
      parameters:
      - $ref: '#/components/parameters/platformType'
      - $ref: '#/components/parameters/suppressionRef'
      responses:
        '200':
          description: Suppression
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suppression'
        '404':
          description: Not found / not visible.
    put:
      tags:
      - Subscriptions Suppressions
      operationId: replaceSuppression
      summary: Replace a suppression by ID (full PUT)
      description: 'Supply **all** required parameters; previous values are replaced. Admin

        can promote private→global by setting `owner: ""`.'
      parameters:
      - $ref: '#/components/parameters/platformType'
      - $ref: '#/components/parameters/suppressionRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuppressionPut'
      responses:
        '200':
          description: Updated suppression
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suppression'
        '400':
          description: Validation/logic error.
        '404':
          description: Not found / not visible.
    delete:
      tags:
      - Subscriptions Suppressions
      operationId: deleteSuppression
      summary: Delete a suppression by ID
      description: 'Returns 204 on success; 404 if not found; if referenced by subscriptions

        (or other errors), returns an object with `suppressionRef`/`suppressionName`

        and `message`.'
      parameters:
      - $ref: '#/components/parameters/platformType'
      - $ref: '#/components/parameters/suppressionRef'
      responses:
        '204':
          description: No Content.
        '404':
          description: Not found.
        '200':
          description: In-use error payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResult'
  /subscriptions/suppressions:
    get:
      tags:
      - Subscriptions Suppressions
      operationId: listSuppressionsDefaultPlatform
      summary: List suppressions (alias of cloud)
      responses:
        '200':
          description: Suppression list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Suppression'
components:
  parameters:
    suppressionRef:
      name: suppressionRef
      in: path
      required: true
      description: Unique suppression identifier.
      schema:
        type: string
    owner:
      name: owner
      in: query
      required: false
      description: Username used with `type=owner` (admins can query any user; non-admins only themselves; others → 400 “Current login user cannot query for owner”).
      schema:
        type: string
    type:
      name: type
      in: query
      required: false
      description: 'Which suppressions to return: `all` (default), `global`, or `owner`. Non-admins

        only see their own private entries with `owner`.

        '
      schema:
        type: string
        enum:
        - all
        - global
        - owner
    platformType:
      name: platformType
      in: path
      required: true
      description: Platform catalog to target (`cloud` or `containers`).
      schema:
        type: string
        enum:
        - cloud
        - containers
  schemas:
    SuppressionCreate:
      type: object
      properties:
        suppressionName:
          type: string
        aliasName:
          type: string
        attributeName:
          type: string
        key:
          type: string
        technology:
          type: string
          enum:
          - AWS
          - CONTAINER
        propertyName:
          type: string
        owner:
          type: string
          description: Omit or "" for global (admin only); otherwise username for private.
      required:
      - suppressionName
    SuppressionPut:
      type: object
      properties:
        suppressionName:
          type: string
        aliasName:
          type: string
        attributeName:
          type: string
        key:
          type: string
        technology:
          type: string
          enum:
          - AWS
          - CONTAINER
        propertyName:
          type: string
        owner:
          type: string
      required:
      - suppressionName
    Suppression:
      type: object
      properties:
        suppressionRef:
          type: string
          description: Unique reference ID.
        suppressionName:
          type: string
          description: Suppression name.
        aliasName:
          type: string
          description: Alias for display.
        attributeName:
          type: string
          description: 'Attribute name (e.g., “Business Applications”, “Resource Tags”, “Container Labels”). For “Resource Tags”/“Container Labels”, supply `key` and `technology`. Must exist in Kubex standard attributes.

            '
        key:
          type: string
          description: Resource tag/label key (with technology).
        technology:
          type: string
          description: 'Technology for resource attribute (supported: AWS, CONTAINER).'
          enum:
          - AWS
          - CONTAINER
        propertyName:
          type: string
          description: 'Recommendation element name (must exist in Recommendations schema for the platform).

            '
        owner:
          type: string
          description: 'Empty = global; otherwise username for private entry. Admins can set empty (global); non-admins limited to self.

            '
        message:
          type: string
          description: Error/status message (on error).
        status:
          type: integer
          description: HTTP-like status code (200, 204, 400, 401, 404, 415, 500).
    SuppressionUpdate:
      type: object
      properties:
        suppressionRef:
          type: string
        suppressionName:
          type: string
        aliasName:
          type: string
        attributeName:
          type: string
        key:
          type: string
        technology:
          type: string
          enum:
          - AWS
          - CONTAINER
        propertyName:
          type: string
        owner:
          type: string
      required:
      - suppressionRef
      - suppressionName
    DeleteResult:
      type: object
      properties:
        suppressionRef:
          type: string
        suppressionName:
          type: string
        message:
          type: string
        status:
          type: integer
          description: HTTP-like code (e.g., 200, 204, 404).