openapi: 3.2.0
info:
  title: CoreStack External Savings Plans API
  version: 1.0.0
  termsOfService: http://corestack.io/
  license:
    name: CoreStack Inc License
    url: http://corestack.io/licenses/LICENSE-2.0.html
  description: Savings plans purchased and utilization
servers:
- url: /
tags:
- name: Savings Plans
  description: Savings plans purchased and utilization
paths:
  /v2/savings_plans/recommendations:
    post:
      responses:
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '200':
          description: Fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavingsPlanRecommendationsData'
      summary: List savings plan purchase recommendations
      description: List savings plan purchase recommendations across one or more tenants in a single call.
      operationId: ListSavingsPlanRecommendations
      security:
      - auth_token: []
      tags:
      - Savings Plans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavingsPlanRecommendationsRequest'
        required: true
  /v2/savings_plans/{tenant_id}/purchased/details:
    post:
      responses:
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '200':
          description: Fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavingsPlanDetailsData'
      summary: List purchased savings plan details
      description: List purchased savings plan details for one or more service accounts, excluding utilization time-series.
      operationId: ListSavingsPlanDetails
      parameters:
      - name: tenant_id
        in: path
        required: true
        description: Specify the tenant ID. This is a unique ID and can be retrieved using the List Tenants API.
        schema:
          type: string
      security:
      - auth_token: []
      tags:
      - Savings Plans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavingsPlanDetailsRequest'
        required: true
  /v2/savings_plans/{tenant_id}/purchased/utilization:
    post:
      responses:
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelError'
        '200':
          description: Fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavingsPlanUtilizationData'
      summary: Get savings plan utilization metrics
      description: Fetch paginated utilization time-series for a single purchased savings plan. plan_id is required.
      operationId: GetSavingsPlanUtilization
      parameters:
      - name: tenant_id
        in: path
        required: true
        description: Specify the tenant ID. This is a unique ID and can be retrieved using the List Tenants API.
        schema:
          type: string
      security:
      - auth_token: []
      tags:
      - Savings Plans
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavingsPlanUtilizationRequest'
        required: true
components:
  schemas:
    SavingsPlanRecommendationsRequest:
      required:
      - tenant_ids
      properties:
        tenant_ids:
          type: array
          description: One or more tenant IDs to fetch savings plan recommendations across.
          items:
            type: string
            x-cs-type: ObjectId
      type: object
    ListContext:
      properties:
        batch_size:
          type: integer
          description: Max number of ids in the response
        batch_offset:
          type: integer
          description: Offset of batches into the results. First batch is 0
        total:
          type: integer
          description: Total number of results
      type: object
    SavingsPlanRecommendationsData:
      required:
      - recommendations
      properties:
        recommendations:
          type: array
          description: Savings plan purchase recommendations.
          items:
            $ref: '#/components/schemas/SavingsPlanRecommendation'
      type: object
    SavingsPlanDetailsData:
      properties:
        results:
          type: array
          description: List of result identifiers
          items:
            $ref: '#/components/schemas/SavingsPlanItem'
        next_list_context:
          description: List context
          $ref: '#/components/schemas/ListContext'
      type: object
    SavingsPlanUtilizationFilters:
      required:
      - plan_id
      properties:
        plan_id:
          type: string
          description: Plan ID of the purchased savings plan
        service_account_ids:
          type: array
          description: Service account IDs to filter
          items:
            type: string
            x-cs-type: ObjectId
        start_date:
          type: string
          format: date-time
          description: Filter metrics on or after this date
        end_date:
          type: string
          format: date-time
          description: Filter metrics on or before this date
      type: object
    SavingsPlanItem:
      allOf:
      - $ref: '#/components/schemas/SavingsPlanBase'
      - properties:
          plan_scope:
            type: string
            description: Scope of the savings plan
          start_date:
            type: string
            format: date-time
            description: Plan start date
          end_date:
            type: string
            format: date-time
            description: Plan end date
          term:
            type: string
            description: Plan term
          payment_option:
            type: string
            description: Payment option
          commitment_amount:
            type: number
            description: Committed spend per hour
          upfront_cost:
            type: number
            description: Upfront cost of the plan
          currency:
            type: string
            description: Currency of monetary values
          instance_family:
            type: string
            description: Instance family (AWS compute plans)
          provisioning_state:
            type: string
            description: Current provisioning/status of the plan
        type: object
    SavingsPlanRecommendation:
      properties:
        recommendation_id:
          type: string
          description: Recommendation ID
        service_account_id:
          type: string
          description: Associated service account ID
          x-cs-type: ObjectId
        plan_type:
          type: string
          description: Type of savings plan
        payment_option:
          type: string
          description: Payment option
        recommendation_scope:
          type: string
          description: Scope of the recommendation
        lookback_period:
          type: string
          description: Historical usage window used for the recommendation
        usage_hours:
          type: number
          description: Usage hours considered
        term:
          type: string
          description: Plan term
        commitment_granularity:
          type: string
          description: Commitment granularity
        commitment_amount:
          type: number
          description: Recommended committed spend per hour
        savings_percentage:
          type: number
          description: Estimated savings percentage
        savings_amount:
          type: number
          description: Estimated savings amount
        utilization_percentage:
          type: number
          description: Projected utilization percentage
        cost_without_recommendation:
          type: number
          description: On-demand cost without the recommendation
        cost_with_recommendation:
          type: number
          description: Projected cost with the recommendation applied
        currency:
          type: string
          description: Currency of monetary values
        number_of_plans:
          type: integer
          description: Number of plans recommended
        instance_family:
          type: string
          description: Instance family (AWS compute plans)
      type: object
    SavingsPlanUtilizationRequest:
      properties:
        list_context:
          description: Optional list context
          $ref: '#/components/schemas/ListContext'
        filters:
          description: Filters for the request
          $ref: '#/components/schemas/SavingsPlanUtilizationFilters'
      type: object
    ModelError:
      required:
      - message
      properties:
        message:
          type: string
          description: Error response message.
      type: object
    SavingsPlanDetailsFilters:
      properties:
        service_account_ids:
          type: array
          description: Service account IDs to filter
          items:
            type: string
            x-cs-type: ObjectId
      type: object
    SavingsPlanUtilizationData:
      allOf:
      - $ref: '#/components/schemas/SavingsPlanBase'
      - properties:
          utilization_metrics:
            description: Paginated utilization time-series
            $ref: '#/components/schemas/SavingsPlanUtilizationMetricsData'
        type: object
    SavingsPlanBase:
      properties:
        plan_id:
          type: string
          description: Savings plan ID
        plan_name:
          type: string
          description: Savings plan name
        plan_type:
          type: string
          description: Type of savings plan
        service_account_id:
          type: string
          description: Associated service account ID
          x-cs-type: ObjectId
        utilization_percentage:
          type: number
          description: Overall utilization percentage
      type: object
    SavingsPlanDetailsRequest:
      properties:
        list_context:
          description: Optional list context
          $ref: '#/components/schemas/ListContext'
        filters:
          description: Filters for the request
          $ref: '#/components/schemas/SavingsPlanDetailsFilters'
      type: object
    SavingsPlanUtilizationMetricsData:
      properties:
        results:
          type: array
          description: List of result identifiers
          items:
            $ref: '#/components/schemas/SavingsPlanUtilizationMetric'
        next_list_context:
          description: List context
          $ref: '#/components/schemas/ListContext'
      type: object
    SavingsPlanUtilizationMetric:
      properties:
        usage_date:
          type: string
          format: date-time
          description: Date of the utilization record
        avg_utilization_percentage:
          type: number
          description: Average utilization percentage for the period
        max_utilization_percentage:
          type: number
          description: Maximum utilization percentage for the period
        min_utilization_percentage:
          type: number
          description: Minimum utilization percentage for the period
      type: object
  securitySchemes:
    auth_token:
      type: apiKey
      in: header
      name: X-Auth-Token