Densify Subscriptions API

openapi: 3.2.0
info:
  title: Densify Subscriptions API
  version: 1.0.0
  description: 'Operations tagged Subscriptions across 3 of this provider''s published API definitions: densify-public-cloud-subscriptions-openapi.yaml, densify-public-cloud-subscriptions-results-openapi.yaml, densify-public-cloud-subscriptions-status-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{host}
  variables:
    host:
      default: api.example.com
tags:
- name: Subscriptions
paths:
  /subscriptions:
    get:
      tags:
      - Subscriptions
      operationId: listSubscriptionsDefaultPlatform
      summary: List subscriptions (alias of /subscriptions/cloud)
      description: Behaves the same as `GET /subscriptions/cloud`. Backward compatibility alias.
      parameters:
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/subscriptionRefQuery'
      responses:
        '200':
          $ref: '#/components/responses/SubscriptionList'
    servers:
    - url: https://{host}
      variables:
        host:
          default: api.example.com
  /subscriptions/{platformType}:
    get:
      tags:
      - Subscriptions
      operationId: listSubscriptions
      summary: List subscriptions for a platform
      description: 'Returns a list of existing platform-specific subscriptions. Filters:

        - `type` → all | global | owner

        - `owner` (admin only) → list another user''s private subs with `type=owner`

        - `subscriptionRef` → return a single subscription by ID.'
      parameters:
      - $ref: '#/components/parameters/platformType'
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/subscriptionRefQuery'
      responses:
        '200':
          $ref: '#/components/responses/SubscriptionList'
        '400':
          description: Bad Request (e.g. querying owner you don't own and you're not admin).
        '401':
          description: Authentication failed.
        '500':
          description: Server error.
    post:
      tags:
      - Subscriptions
      operationId: createSubscriptions
      summary: Create subscriptions (bulk)
      description: 'Creates a **collection** of platform-specific subscriptions in one request. The operation

        is committed as a whole: any creation failure rolls back the entire batch. Non-admin users

        are auto-assigned as `owner`; admins may create global (owner="") or assign any owner.'
      parameters:
      - $ref: '#/components/parameters/platformType'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              items:
                $ref: '#/components/schemas/SubscriptionUpsert'
            examples:
              createOne:
                value:
                - subscriptionName: My Weekly Cloud Feed
                  description: Finance BU, prod apps; weekly
                  owner: ''
                  active: 'true'
                  webhook:
                    uri: https://hooks.example/teams
                    authType: basic
                    authValue: user:pass
                  tagReferences:
                  - tagID: business_unit
                    operator: equals
                    values:
                    - Finance
                  propertyReferences:
                  - propertyID: serviceType
                    operator: equals
                    values:
                    - Virtual Machine
                  suppressionReferences:
                  - suppressionID: no-m3
                    operator: like
                    values:
                    - m3*
                    revokeBy: '1735689600000'
                  returnStructure:
                    showAliases: true
                    fields:
                    - name
                    - region
                    - currentType
                    - recommendedType
                    - savingsEstimate
                    - rptHref
                  schedule:
                    frequency: WEEKLY
                    at: 08:30
      responses:
        '200':
          description: Created (batch result)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Subscription'
        '400':
          description: Validation/logic error; entire batch rolled back.
        '401':
          description: Authentication failed.
        '500':
          description: Server error.
    delete:
      tags:
      - Subscriptions
      operationId: deleteSubscriptions
      summary: Delete subscriptions (bulk)
      description: 'Deletes a **collection** of subscriptions by ID. Each delete is independent; an error on one

        does not affect others. Success returns **204 No Content**; **404 Not Found** if a sub doesn''t

        exist or you lack privilege (non-owner, non-admin). Admins may delete any global/private subs.'
      parameters:
      - $ref: '#/components/parameters/platformType'
      responses:
        '204':
          description: No Content (all attempted deletes processed).
        '404':
          description: Not Found / No privilege.
        '401':
          description: Authentication failed.
        '500':
          description: Server error.
    servers:
    - url: https://{host}
      variables:
        host:
          default: api.example.com
  /subscriptions/{platformType}/{subscriptionRef}:
    put:
      tags:
      - Subscriptions
      operationId: replaceSubscription
      summary: Replace an existing subscription (full PUT)
      description: 'Replaces **all** parameters of an existing subscription. You must supply all body parameters

        required by the existing subscription. Non-admin users can only modify their own private subs;

        admins can also promote private→global by setting `owner: ""`.'
      parameters:
      - $ref: '#/components/parameters/platformType'
      - $ref: '#/components/parameters/subscriptionRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionUpsert'
      responses:
        '200':
          description: Updated subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          description: Validation/logic error.
        '401':
          description: Authentication failed.
        '404':
          description: Subscription not found / no privilege.
        '500':
          description: Server error.
    delete:
      tags:
      - Subscriptions
      operationId: deleteSubscription
      summary: Delete a single subscription
      parameters:
      - $ref: '#/components/parameters/platformType'
      - $ref: '#/components/parameters/subscriptionRef'
      responses:
        '204':
          description: No Content (deleted).
        '404':
          description: Not Found / No privilege.
        '401':
          description: Authentication failed.
    get:
      tags:
      - Subscriptions
      operationId: getSubscriptionResults
      summary: Get subscription results (on-demand)
      description: 'Returns the current results for the specified subscription.

        Notes for on-demand calls: `active`, `webhook`, and `schedule` are ignored (results are always returned).

        Optional `divider` controls whether a divider string is included between properties and tags.

        `limit` controls the maximum number of returned systems (default 3000; range 1–30000).'
      parameters:
      - $ref: '#/components/parameters/platformType_2'
      - $ref: '#/components/parameters/subscriptionRef'
      - $ref: '#/components/parameters/divider'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Subscription results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResults'
              examples:
                sample:
                  value:
                    subscription:
                      name: Sample Subscription
                      description: A subscription for testing
                      created: Mon Jan 19 13:52:31 EST 2020
                      createdBy: saas
                      updated: Mon Jan 20 14:32:38 EST 2020
                      updatedBy: SaaSadmin
                      lastRefreshed: Mon Jan 20 01:32:59 EST 2020
                      owner: saas
                    count: 452
                    results:
                    - currentType: standard_d2
                      name: st01-prepro-edge-307
                      recommendationType: Modernize - Optimal Family
                      savingsEstimate: '43.850475'
                      serviceType: Virtual Machine
                      divider: '------------------------'
                      Availability Zone: eastus+group
        '204':
          description: No content.
        '400':
          description: Bad Request (e.g., result count exceeded default 3000 without raising `limit`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusMessage'
              examples:
                tooMany:
                  value:
                    message: On-Demand Failure. The return count of 3891 has exceeded object return limit of 3000. Update your call with a new limit value. Wed Jul 29 09:05:15 EDT 2020
                    status: 400
        '401':
          description: Authentication failed.
        '404':
          description: Not found / no privileges.
        '415':
          description: Unsupported media type.
        '500':
          description: Server error.
    servers:
    - url: https://{host}
      variables:
        host:
          default: api.example.com
  /subscriptions/{subscriptionRef}:
    get:
      tags:
      - Subscriptions
      operationId: getSubscriptionResultsDefaultPlatform
      summary: Get subscription results (alias of cloud)
      parameters:
      - $ref: '#/components/parameters/subscriptionRef'
      - $ref: '#/components/parameters/divider'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: Subscription results (same shape as above)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResults'
    servers:
    - url: https://{host}
      variables:
        host:
          default: api.example.com
  /subscriptions/{platformType}/{subscriptionRef}/status:
    get:
      tags:
      - Subscriptions
      operationId: getSubscriptionStatus
      summary: Get subscription status (results + webhook)
      description: 'Returns `lastTriggered` (On-Demand/Scheduled Success/Failure with timestamp)

        and `webHookStatus` (Success/Failure with timestamp) for the specified

        subscription.'
      parameters:
      - name: platformType
        in: path
        required: true
        description: Technology platform (`cloud` or `containers`).
        schema:
          type: string
          enum:
          - cloud
          - containers
      - name: subscriptionRef
        in: path
        required: true
        description: Unique subscription identifier.
        schema:
          type: string
      responses:
        '200':
          description: Status payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatus'
              examples:
                sample:
                  value:
                    lastTriggered: On-Demand Success. Thu Jan 02 16:41:52 EST 2020
                    webHookStatus: Failure. … Connection refused … Thu Jan 02 16:41:53 EST 2020
        '204':
          description: Success, no content.
        '400':
          description: Bad request (invalid parameters / logic).
        '401':
          description: Authentication failed.
        '404':
          description: Not found / no privileges.
        '415':
          description: Unsupported media type.
        '500':
          description: Internal server error.
    servers:
    - url: https://{host}
      variables:
        host:
          default: api.example.com
  /subscriptions/{subscriptionRef}/status:
    get:
      tags:
      - Subscriptions
      operationId: getSubscriptionStatusDefaultPlatform
      summary: Get subscription status (alias of cloud)
      parameters:
      - name: subscriptionRef
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Status payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatus'
    servers:
    - url: https://{host}
      variables:
        host:
          default: api.example.com
components:
  schemas:
    SuppressionCondition:
      type: object
      properties:
        suppressionID:
          type: string
        operator:
          type: string
        values:
          type: array
          items:
            type: string
        revokeBy:
          type: string
          description: Unix time (ms) when suppression expires; omit for no expiry.
      required:
      - suppressionID
      - operator
      - values
      description: Exclude systems/recommendations from the output.
    SubscriptionUpsert:
      type: object
      properties:
        subscriptionName:
          type: string
          description: Unique per platform if global; unique per owner if private.
        owner:
          type: string
          description: '"" for global (admin only) or username for private; non-admins default to their username.'
        description:
          type: string
        outputType:
          type: string
          enum:
          - application/json
          default: application/json
          description: Only supported output type.
        active:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
          description: true=active; false=dormant (no scheduled posts; on-demand still available).
        webhook:
          $ref: '#/components/schemas/WebHook'
        propertyReferences:
          type: array
          items:
            $ref: '#/components/schemas/PropertyCondition'
        tagReferences:
          type: array
          items:
            $ref: '#/components/schemas/TagCondition'
        suppressionReferences:
          type: array
          items:
            $ref: '#/components/schemas/SuppressionCondition'
        returnStructure:
          $ref: '#/components/schemas/ReturnStructure'
        schedule:
          $ref: '#/components/schemas/Schedule'
      description: "Provide at least **one** of: `propertyReferences`, `tagReferences`, or `suppressionReferences`. \n"
    Subscription:
      type: object
      properties:
        subscriptionRef:
          type: string
          description: Unique ID assigned to the subscription.
        subscriptionName:
          type: string
        description:
          type: string
        owner:
          type: string
          description: Empty for global; username for private.
        outputType:
          type: string
        active:
          type: string
          enum:
          - 'true'
          - 'false'
        webhook:
          $ref: '#/components/schemas/WebHook'
        propertyReferences:
          type: array
          items:
            $ref: '#/components/schemas/PropertyCondition'
        tagReferences:
          type: array
          items:
            $ref: '#/components/schemas/TagCondition'
        suppressionReferences:
          type: array
          items:
            $ref: '#/components/schemas/SuppressionCondition'
        returnStructure:
          $ref: '#/components/schemas/ReturnStructure'
        schedule:
          $ref: '#/components/schemas/Schedule'
        webhookStatus:
          type: string
          description: Success | Failure of last push to webhook (with timestamp).
        lastTriggered:
          type: string
          description: On-Demand Success/Failure or Scheduled Success/Failure with timestamp.
        message:
          type: string
          description: Error/status message (on error).
        status:
          type: integer
          description: HTTP-like status code (200, 204, 400, 401, 404, 415, 500).
      required:
      - subscriptionRef
      - subscriptionName
    WebHook:
      type: object
      properties:
        uri:
          type: string
          format: uri
        authType:
          type: string
        authValue:
          type: string
      required:
      - uri
      description: Webhook destination for delivering subscription notifications.
    ReturnStructure:
      type: object
      properties:
        showAliases:
          type: boolean
          default: false
          description: Use field aliases as element keys when true.
        fields:
          type: array
          items:
            type: string
          description: Fields to include in returned dataset.
    Schedule:
      type: object
      properties:
        frequency:
          type: string
          description: Implementation-defined frequency (e.g., NIGHTLY, WEEKLY).
        at:
          type: string
          description: HH:mm (24h) time string for trigger.
      description: If omitted, notifications typically trigger nightly after analysis/reporting.
    PropertyCondition:
      type: object
      properties:
        propertyID:
          type: string
        operator:
          type: string
        values:
          type: array
          items:
            type: string
      required:
      - propertyID
      - operator
      - values
      description: Filter on recommendation fields. Requires at least one **core** property overall.
    TagCondition:
      type: object
      properties:
        tagID:
          type: string
        operator:
          type: string
        values:
          type: array
          items:
            type: string
      required:
      - tagID
      - operator
      - values
      description: Filter on system attributes (e.g., account, BU, app).
    SubscriptionResultItem:
      type: object
      description: "One system recommendation as shaped by the subscription `returnStructure`.  \nMay include `properties`, optional `divider`, and optional `tags`. \n"
      properties:
        divider:
          type: string
        tags:
          type: array
          items:
            type: string
      additionalProperties: true
    SubscriptionHeader:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        created:
          type: string
          description: Datetime string.
        createdBy:
          type: string
        updated:
          type: string
          description: Datetime string.
        updatedBy:
          type: string
        lastRefreshed:
          type: string
          description: Datetime string; last recommendation analysis.
        owner:
          type: string
          description: Empty = global subscription; otherwise username.
    SubscriptionResults:
      type: object
      properties:
        subscription:
          $ref: '#/components/schemas/SubscriptionHeader'
        count:
          type: integer
          description: Number of recommendations in `results`.
        results:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionResultItem'
      required:
      - subscription
      - count
      - results
    StatusMessage:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
          description: 200, 204, 400, 401, 404, 415, 500.
      required:
      - message
      - status
    SubscriptionStatus:
      type: object
      properties:
        lastTriggered:
          type: string
          description: "Status + timestamp of last request: On-Demand Success/Failure or Scheduled Success/Failure. \n"
        webHookStatus:
          type: string
          description: "Status + timestamp of last webhook post: Success or Failure. \n"
        message:
          type: string
          description: Message for the status response (on error).
        status:
          type: integer
          description: One of 200, 204, 400, 401, 404, 415, 500.
  parameters:
    type:
      name: type
      in: query
      required: false
      description: "Which subscriptions to list:\n- `all` (default): global + your private (admins see all)\n- `global`: all global\n- `owner`: user-specific; combine with `owner=` (admin can query any user) \n"
      schema:
        type: string
        enum:
        - all
        - global
        - owner
      example: owner
    subscriptionRefQuery:
      name: subscriptionRef
      in: query
      required: false
      description: Return details for a single subscription by ID.
      schema:
        type: string
    platformType:
      name: platformType
      in: path
      required: true
      description: Technology platform (`cloud` or `containers`).
      schema:
        type: string
        enum:
        - cloud
        - containers
    subscriptionRef:
      name: subscriptionRef
      in: path
      required: true
      description: Unique subscription identifier.
      schema:
        type: string
    owner:
      name: owner
      in: query
      required: false
      description: Kubex username to scope `type=owner` queries (admins only for others).
      schema:
        type: string
    limit:
      name: limit
      in: query
      required: false
      description: "Maximum number of results to return. Default 3000; valid range 1–30000.\nOnly applies to on-demand queries (no limit for scheduled webhook pushes). \n"
      schema:
        type: integer
        minimum: 1
        maximum: 30000
        default: 3000
    divider:
      name: divider
      in: query
      required: false
      description: "Display divider between properties and tags in each result:\n`\"true\"` (default) shows `\"divider\": \"------------------------\"`, `\"false\"` hides it. \n"
      schema:
        type: string
        enum:
        - 'true'
        - 'false'
        default: 'true'
    platformType_2:
      name: platformType
      in: path
      required: true
      description: Technology platform for the subscription results.
      schema:
        type: string
        enum:
        - cloud
        - containers
  responses:
    SubscriptionList:
      description: Array of subscriptions
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Subscription'
x-refined-from:
- densify-public-cloud-subscriptions-openapi.yaml
- densify-public-cloud-subscriptions-results-openapi.yaml
- densify-public-cloud-subscriptions-status-openapi.yaml