openapi: 3.1.0
info:
  title: Spot Billing Engine API
  description: >-
    The Spot Billing Engine API provides programmatic access to cloud billing
    management, cost allocation, and invoicing capabilities. Billing Engine
    streamlines multi-cloud invoicing with intelligent cost allocation,
    chargeback and showback reporting, and comprehensive billing analytics
    across AWS, Azure, and GCP accounts.
  version: 2.0.0
  contact:
    name: Spot by Flexera
    url: https://docs.spot.io/
  termsOfService: https://spot.io/terms-of-use/
servers:
- url: https://api.spotinst.io
  description: Spot Production API
security:
- bearerAuth: []
tags:
- name: Billing Accounts
  description: Manage registered billing accounts and their configurations.
- name: Billing Engine Setup
  description: Set up and configure Billing Engine for cloud accounts.
- name: Cost Analysis
  description: Retrieve cost analysis and spending data across cloud accounts.
- name: Cost Intelligence
  description: >-
    Access Cost Intelligence analytics for actionable cost insights
    and recommendations.
- name: Families
  description: Manage account families for grouping and cost allocation.
paths:
  /billingEngine/account:
    get:
      operationId: listBillingEngineAccounts
      summary: Spot List Billing Engine Accounts
      description: >-
        Get all accounts registered with Billing Engine, including their
        cloud provider type and configuration status.
      tags:
      - Billing Accounts
      parameters:
      - name: accountId
        in: query
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingAccountListResponse'
              examples:
                Listbillingengineaccounts200Example:
                  summary: Default listBillingEngineAccounts 200 response
                  x-microcks-default: true
                  value:
                    request: example_value
                    response:
                      items:
                      - {}
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /billingEngine/setup:
    post:
      operationId: setupBillingEngine
      summary: Spot Set up Billing Engine
      description: >-
        Set up Billing Engine on a Spot account by linking it to a cloud
        provider billing account for cost data ingestion.
      tags:
      - Billing Engine Setup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingEngineSetupRequest'
            examples:
              SetupbillingengineRequestExample:
                summary: Default setupBillingEngine request
                x-microcks-default: true
                value:
                  billingEngine:
                    cloudProvider: aws
                    billingAccountId: '500123'
                    bucketName: example_value
      responses:
        '200':
          description: Successful response
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /billingEngine/setup/validation:
    post:
      operationId: validateBillingEngineSetup
      summary: Spot Validate Billing Engine Setup
      description: >-
        Perform validation checks on a Billing Engine setup to ensure
        correct cloud provider credentials and billing access.
      tags:
      - Billing Engine Setup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingEngineValidationRequest'
            examples:
              ValidatebillingenginesetupRequestExample:
                summary: Default validateBillingEngineSetup request
                x-microcks-default: true
                value:
                  billingEngine:
                    cloudProvider: example_value
                    billingAccountId: '500123'
      responses:
        '200':
          description: Successful response
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /billingEngine/family:
    post:
      operationId: createAccountFamily
      summary: Spot Create Account Family
      description: >-
        Create an account family for grouping related cloud accounts
        and enabling consolidated cost allocation.
      tags:
      - Families
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountFamilyRequest'
            examples:
              CreateaccountfamilyRequestExample:
                summary: Default createAccountFamily request
                x-microcks-default: true
                value:
                  family:
                    name: Example Title
                    description: A sample description.
                    accountIds:
                    - example_value
      responses:
        '200':
          description: Successful response
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      operationId: listAccountFamilies
      summary: Spot List Account Families
      description: List all account families configured in Billing Engine.
      tags:
      - Families
      responses:
        '200':
          description: Successful response
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /billingEngine/family/{familyId}:
    get:
      operationId: getAccountFamily
      summary: Spot Get Account Family
      description: Get details of a specific account family.
      tags:
      - Families
      parameters:
      - name: familyId
        in: path
        required: true
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Successful response
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateAccountFamily
      summary: Spot Update Account Family
      description: Update an existing account family.
      tags:
      - Families
      parameters:
      - name: familyId
        in: path
        required: true
        schema:
          type: string
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountFamilyRequest'
            examples:
              UpdateaccountfamilyRequestExample:
                summary: Default updateAccountFamily request
                x-microcks-default: true
                value:
                  family:
                    name: Example Title
                    description: A sample description.
                    accountIds:
                    - example_value
      responses:
        '200':
          description: Successful response
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteAccountFamily
      summary: Spot Delete Account Family
      description: Delete an account family.
      tags:
      - Families
      parameters:
      - name: familyId
        in: path
        required: true
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Successful response
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /billingEngine/cost:
    get:
      operationId: getCostAnalysis
      summary: Spot Get Cost Analysis
      description: >-
        Retrieve cost analysis data across registered cloud accounts,
        including breakdowns by service, account, and time period.
      tags:
      - Cost Analysis
      parameters:
      - name: accountId
        in: query
        schema:
          type: string
        example: '500123'
      - name: fromDate
        in: query
        description: Start date for the cost analysis period.
        schema:
          type: string
          format: date
        example: '2026-01-15'
      - name: toDate
        in: query
        description: End date for the cost analysis period.
        schema:
          type: string
          format: date
        example: '2026-01-15'
      - name: groupBy
        in: query
        description: Dimension to group costs by.
        schema:
          type: string
          enum:
          - account
          - service
          - region
          - family
        example: account
      responses:
        '200':
          description: Successful response
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /costIntelligence/setup:
    post:
      operationId: setupCostIntelligence
      summary: Spot Set up Cost Intelligence
      description: >-
        Set up Cost Intelligence on a Spot account to enable granular
        cost analytics and actionable optimization recommendations.
      tags:
      - Cost Intelligence
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CostIntelligenceSetupRequest'
            examples:
              SetupcostintelligenceRequestExample:
                summary: Default setupCostIntelligence request
                x-microcks-default: true
                value:
                  costIntelligence:
                    cloudProvider: aws
                    billingAccountId: '500123'
      responses:
        '200':
          description: Successful response
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /costIntelligence/setup/validation:
    post:
      operationId: validateCostIntelligenceSetup
      summary: Spot Validate Cost Intelligence Setup
      description: >-
        Perform validation checks on a Cost Intelligence setup to ensure
        correct access and configuration.
      tags:
      - Cost Intelligence
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CostIntelligenceValidationRequest'
            examples:
              ValidatecostintelligencesetupRequestExample:
                summary: Default validateCostIntelligenceSetup request
                x-microcks-default: true
                value:
                  costIntelligence:
                    cloudProvider: example_value
                    billingAccountId: '500123'
      responses:
        '200':
          description: Successful response
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Spot API uses Bearer Token Authentication. Include your API token
        in the Authorization header.
  schemas:
    BillingAccountListResponse:
      type: object
      properties:
        request:
          type: object
          example: example_value
        response:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/BillingAccount'
          example: example_value
    BillingAccount:
      type: object
      properties:
        accountId:
          type: string
          description: The Spot account identifier.
          example: '500123'
        cloudProvider:
          type: string
          enum:
          - aws
          - azure
          - gcp
          description: The cloud provider type.
          example: aws
        status:
          type: string
          description: The setup status of the billing account.
          example: example_value
        billingAccountId:
          type: string
          description: The cloud provider billing account identifier.
          example: '500123'
    BillingEngineSetupRequest:
      type: object
      properties:
        billingEngine:
          type: object
          properties:
            cloudProvider:
              type: string
              enum:
              - aws
              - azure
              - gcp
            billingAccountId:
              type: string
              description: The cloud provider billing or payer account ID.
            bucketName:
              type: string
              description: The S3 bucket or storage container for cost and usage reports.
          example: example_value
    BillingEngineValidationRequest:
      type: object
      properties:
        billingEngine:
          type: object
          properties:
            cloudProvider:
              type: string
            billingAccountId:
              type: string
          example: example_value
    AccountFamilyRequest:
      type: object
      properties:
        family:
          type: object
          properties:
            name:
              type: string
              description: The name of the account family.
            description:
              type: string
              description: A description of the account family.
            accountIds:
              type: array
              items:
                type: string
              description: List of account IDs to include in the family.
          example: example_value
    CostIntelligenceSetupRequest:
      type: object
      properties:
        costIntelligence:
          type: object
          properties:
            cloudProvider:
              type: string
              enum:
              - aws
              - azure
              - gcp
            billingAccountId:
              type: string
          example: example_value
    CostIntelligenceValidationRequest:
      type: object
      properties:
        costIntelligence:
          type: object
          properties:
            cloudProvider:
              type: string
            billingAccountId:
              type: string
          example: example_value