DoiT Insights API

openapi: 3.2.0
info:
  title: DoiT Insights API
  description: Programmatic access to DoiT Platform
  version: v1
servers:
- url: https://api.doit.com
security:
- api_key: []
- tenantId: []
  api_key: []
tags:
- name: Insights
  description: Manage cloud insights representing recommendations and findings for cloud resources.
paths:
  /insights/v1/results:
    get:
      tags:
      - Insights
      summary: List insights
      description: 'Returns a paginated list of insights with their aggregate summaries (savings, risk counts).

        Use query parameters to filter by status, category, provider, or priority.

        Does not include individual resource-level results — use the resource-results endpoint for those.

        '
      operationId: getInsightResults
      parameters:
      - in: query
        name: searchTerm
        description: Free-text search term to filter insights by title or description.
        schema:
          type: string
        required: false
      - in: query
        name: displayStatus
        description: Filter by one or more display statuses.
        schema:
          type: array
          items:
            type: string
            enum:
            - actionable
            - acknowledged
            - in progress
            - optimized
            - dismissed
        required: false
      - in: query
        name: category
        description: Filter by insight category.
        schema:
          type: string
          enum:
          - FinOps
          - OperationalExcellence
          - PerformanceEfficiency
          - Reliability
          - Security
          - Sustainability
        required: false
      - in: query
        name: cloudProvider
        description: Filter by cloud provider (e.g. "aws", "gcp", "azure").
        schema:
          $ref: '#/components/schemas/CloudProvider'
        required: false
      - in: query
        name: source
        description: the source that generated insights
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Source'
        required: false
      - in: query
        name: priority
        description: Filter by one or more priority levels.
        schema:
          type: array
          items:
            type: string
            enum:
            - Low
            - Medium
            - High
        required: false
      - in: query
        name: tag
        description: Filter by one or more tags (e.g. security certification labels like "ISO").
        schema:
          type: array
          items:
            type: string
        required: false
      - in: query
        name: easyWin
        description: When true, return only insights flagged as easy wins.
        schema:
          type: boolean
        required: false
      - in: query
        name: cloudFlows
        description: When true, return only insights that have associated CloudFlow automations.
        schema:
          type: boolean
        required: false
      - in: query
        name: pageToken
        description: Token from a previous response to fetch the next page.
        schema:
          type: string
        required: false
      - in: query
        name: maxResults
        description: Maximum number of results per page (default 50, max 500).
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 50
        required: false
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsBody'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    post:
      tags:
      - Insights
      summary: Create insights (batch)
      description: 'Creates or updates multiple insights in a single batch request.

        Each insight in the batch includes its metadata and resource results inline.

        For granular control over insight metadata and resource results independently,

        use the single-insight and resource-results endpoints instead.

        '
      operationId: postInsightResults
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResultsBody'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ResultsError'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    delete:
      tags:
      - Insights
      summary: Delete insights (batch)
      description: 'Deletes all insights matching the specified key from the batch source.

        This removes the insight and all its associated resource results.

        For single-insight deletion, use `DELETE /source/{sourceID}/insight/{insightKey}` instead.

        '
      operationId: deleteInsightResults
      parameters:
      - in: query
        name: insightKey
        description: The unique key identifying the insight to delete.
        schema:
          type: string
        required: true
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
  /insights/v1/results/source/{sourceID}/insight/{insightKey}:
    get:
      tags:
      - Insights
      summary: Retrieve an insight
      description: 'Returns the metadata and aggregate summary for a single insight identified by source and key.

        Does not include individual resource-level results — use the resource-results endpoint for those.

        '
      operationId: getInsightResult
      parameters:
      - in: path
        name: sourceID
        description: The identifier of the source that generated the insight.
        required: true
        schema:
          type: string
      - in: path
        name: insightKey
        description: The unique key identifying the insight.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
    post:
      tags:
      - Insights
      summary: Create or update an insight
      description: 'Creates or updates a single insight for the given source and key.

        If an insight with the same key already exists for the source, it will be updated.

        Resource results are managed separately via the resource-results endpoint.

        '
      operationId: postInsightResult
      parameters:
      - in: path
        name: sourceID
        description: Only insights created via the public API can be managed. Currently only "public-api" is supported.
        required: true
        schema:
          type: string
          enum:
          - public-api
      - in: path
        name: insightKey
        description: The unique key identifying the insight.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightMetadataRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
    delete:
      tags:
      - Insights
      summary: Delete an insight
      description: 'Permanently deletes a single insight and all its associated resource results.

        Only insights created via the public API can be deleted.

        '
      operationId: deleteInsightResult
      parameters:
      - in: path
        name: sourceID
        description: Only insights created via the public API can be managed. Currently only "public-api" is supported.
        required: true
        schema:
          type: string
          enum:
          - public-api
      - in: path
        name: insightKey
        description: The unique key identifying the insight to delete.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No content
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
  /insights/v1/results/source/{sourceID}/insight/{insightKey}/status:
    put:
      tags:
      - Insights
      summary: Update Insight Status
      description: 'Updates the display status (e.g. actionable, acknowledged, dismissed) of a single insight.

        Only insights created via the public API can have their status changed.

        Deprecated: use the status field on the create/update insight endpoint instead.

        '
      deprecated: true
      operationId: updateInsightStatus
      parameters:
      - in: path
        name: sourceID
        description: Only insights created via the public API can be managed. Currently only "public-api" is supported.
        required: true
        schema:
          type: string
          enum:
          - public-api
      - in: path
        name: insightKey
        description: The unique key identifying the insight to update.
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStatusRequest'
      responses:
        '204':
          description: Status updated successfully
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
  /insights/v1/results/source/{sourceID}/insight/{insightKey}/resource-results:
    get:
      tags:
      - Insights
      summary: List resource results for an insight
      description: 'Returns a paginated list of individual resource-level results for a specific insight.

        Each resource result represents a single cloud resource (e.g. an EC2 instance, a GCS bucket)

        affected by the insight, along with its risk scores or potential savings.

        '
      operationId: getInsightResourceResults
      parameters:
      - in: path
        name: sourceID
        description: The identifier of the source that generated the insight.
        required: true
        schema:
          type: string
      - in: path
        name: insightKey
        description: The unique key identifying the insight.
        required: true
        schema:
          type: string
      - in: query
        name: pageToken
        description: Token from a previous response to fetch the next page.
        schema:
          type: string
        required: false
      - in: query
        name: maxResults
        description: Maximum number of results per page (default 1000, max 5000).
        schema:
          type: integer
          minimum: 1
          maximum: 5000
          default: 1000
        required: false
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResultsResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
    post:
      tags:
      - Insights
      summary: Replace resource results for an insight
      description: 'Replaces all resource results for the specified insight. Any existing unresolved resource results not present in the new set will be removed. The response includes server-computed fields (severity, resolved, enhancement) for each resource result. To delete all resource results, send an empty array.

        '
      operationId: postInsightResourceResults
      parameters:
      - in: path
        name: sourceID
        description: Only insights created via the public API can be managed. Currently only "public-api" is supported.
        required: true
        schema:
          type: string
          enum:
          - public-api
      - in: path
        name: insightKey
        description: The unique key identifying the insight.
        required: true
        schema:
          type: string
      - in: query
        name: maxResults
        description: Maximum number of results per page in the response (default 1000, max 5000).
        schema:
          type: integer
          minimum: 1
          maximum: 5000
          default: 1000
        required: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResourceResultsBody'
      responses:
        '200':
          description: Resource results created/replaced successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceResultsResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
components:
  responses:
    '400':
      description: Bad Request - The server cannot process the request, often due to a malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Internal Server Error - Something went wrong with the DoiT API server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: Unauthorized - Invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '404':
      description: Not Found - The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '403':
      description: Forbidden - The client is not authorized to perform the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    InsightSummary:
      type: object
      description: Aggregate summary of risks and savings across all resource results for an insight.
      properties:
        operationalRisks:
          type: number
          format: double
          description: Total number of operational risks.
        performanceRisks:
          type: number
          format: double
          description: Total number of performance risks.
        potentialDailySavings:
          type: number
          format: double
          description: Total potential daily savings in USD.
        reliabilityRisks:
          type: number
          format: double
          description: Total number of reliability risks.
        securityRisks:
          type: number
          format: double
          description: Total number of security risks.
        sustainabilityRisks:
          type: number
          format: double
          description: Total number of sustainability risks.
    CreateResourceResultsBody:
      type: object
      description: Request body for creating or replacing resource results for an insight.
      required:
      - resourceResults
      properties:
        resourceResults:
          $ref: '#/components/schemas/ResourceResults'
    ResultsBody:
      type: object
      description: Paginated list of insight results.
      properties:
        results:
          description: List of insight results.
          type: array
          items:
            $ref: '#/components/schemas/InsightResponse'
        pagination:
          $ref: '#/components/schemas/Pagination'
    DismissalDetails:
      type: object
      description: Details for why an insight was dismissed.
      properties:
        reason:
          type: string
          description: The reason for dismissal.
          enum:
          - not relevant
          - not enough information
          - not worth the effort
          - inaccurate optimization opportunities
        comment:
          type: string
          description: An optional free-text comment providing additional context.
    DisplayStatus:
      type: string
      enum:
      - actionable
      - acknowledged
      - optimized
      - dismissed
      - in progress
      - upgrade needed
      - permissions needed
      description: The display status of the insight.
    Category:
      type: string
      description: The insight category.
      enum:
      - FinOps
      - Operational excellence
      - Performance efficiency
      - Reliability
      - Security
      - Sustainability
    ResourceResultEnhancement:
      type: object
      description: DoiT-managed metadata associated with a resource result.
      properties:
        tags:
          type: array
          description: Tags assigned to this resource result.
          items:
            type: string
        priority:
          type: object
          description: Priority information for this resource result.
          properties:
            value:
              type: string
              description: The priority level (e.g. Low, Medium, High).
            priorityScore:
              type: number
              format: double
              description: Numeric priority score.
        lastUpdatedBy:
          type: string
          description: The user who last updated this enhancement.
        lastUpdatedAt:
          type: string
          format: date-time
          description: Timestamp of the last update.
    Source:
      type: string
      description: The source that generated the insight.
      example: aws-trusted-advisor, aws-cost-optimization-hub, aws-security-hub, azure-advisor, custom, gcp-recommender
    ResourceResultsResponse:
      type: object
      required:
      - resourceResults
      - rowCount
      properties:
        resourceResults:
          type: array
          items:
            $ref: '#/components/schemas/ResourceResult'
        pageToken:
          type: string
        rowCount:
          type: integer
    UpdateStatusRequest:
      type: object
      description: Request body for updating an insight's display status.
      required:
      - status
      properties:
        status:
          $ref: '#/components/schemas/DisplayStatus'
        dismissalDetails:
          $ref: '#/components/schemas/DismissalDetails'
    Error:
      type: object
      description: Standard error response structure.
      properties:
        error:
          type: string
          description: Detailed error message.
    CloudProvider:
      type: string
      example: aws
      description: The cloud provider associated with the resource.
    Pagination:
      type: object
      description: Cursor-based pagination metadata.
      required:
      - rowCount
      properties:
        pageToken:
          type: string
          description: Token to retrieve the next page. Absent when there are no more pages.
        rowCount:
          type: integer
          description: Number of items in this page.
    LastInsightStatusChange:
      description: If set, this object contains the last status change made by a user for this insight
      type: object
      properties:
        userId:
          description: 'the reference to the user who made the change (if it was made by a user) If the change was made by an automated system, this reference is empty.

            '
          type: string
          example: /users/0Rkrkeq5P0XLe8QFHKq2
        lastChangedAt:
          type: string
          format: date-time
      required:
      - userId
      - lastChangedAt
    InsightMetadataRequest:
      type: object
      description: Request body for creating or updating a single insight's metadata. Resource results are managed separately via the resource-results endpoint.
      required:
      - key
      - title
      - shortDescription
      - cloudProvider
      - categories
      properties:
        key:
          type: string
          description: A unique key for this insight within the source.
        title:
          type: string
          description: The display title of the insight.
        shortDescription:
          type: string
          description: A brief summary of the insight.
        detailedDescriptionMdx:
          type: string
          description: A detailed description of the insight in MDX format.
        cloudProvider:
          $ref: '#/components/schemas/CloudProvider'
        categories:
          description: One or more categories this insight belongs to.
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/CreateCategory'
        reportUrl:
          type: string
          description: URL to an external report related to this insight.
        cloudFlowTemplateId:
          type: string
          description: ID of a CloudFlow template that can automate the remediation of this insight.
        easyWinDescription:
          type: string
          description: A description of why this insight is considered an easy win.
        status:
          $ref: '#/components/schemas/DisplayStatus'
        dismissalDetails:
          $ref: '#/components/schemas/DismissalDetails'
    ResourceResultRequest:
      type: object
      description: 'A single resource-level result for creating or updating an insight. Server-computed fields (severity, resolved, enhancement) are not accepted here and will be ignored. Identity fields (resourceId, resultType, account, cloudProvider) form the composite key. The fields location and resource_type are set on creation only — any values provided for these fields during subsequent upserts are silently ignored.

        '
      required:
      - resourceId
      - resultType
      - account
      - cloudProvider
      properties:
        resourceId:
          type: string
          description: The cloud resource identifier.
        resourceType:
          description: 'What the resource actually is, e.g. for an EC2 resource ID, this field would be `instance`. Immutable after creation — updates to this field are silently ignored.

            '
          type: string
          example: instance, disk, cache
        cloudProvider:
          description: Immutable after creation — updates to this field are silently ignored.
          allOf:
          - $ref: '#/components/schemas/CloudProvider'
        account:
          type: string
          description: The cloud account or project ID containing this resource. Immutable after creation — updates to this field are silently ignored.
        location:
          type: string
          description: 'Represents the region/zone of the resource in AWS, or equivalent for other providers. Immutable after creation — updates to this field are silently ignored.

            '
          example: eu-west-2
        externalId:
          type: string
          description: the external ID of the resource in the provider's system for the resource
        externalUrl:
          type: string
          description: the URL to the resource-level issue in the provider's system
        metadata:
          type: object
          description: contains any additional information for the resource results
        resultType:
          type: string
          enum:
          - security_risk
          - potential_daily_savings
          - potential_daily_savings_with_recommendation
          - potential_daily_savings_with_cluster_agent
          description: The discriminator property that determines which fields are populated in the 'result' object.
        result:
          description: 'The result data for this resource. Which fields are populated depends on the resultType. For security_risk: critical, high, medium, low. For potential_daily_savings: value. For potential_daily_savings_with_recommendation: value, current, recommendation. For potential_daily_savings_with_cluster_agent: value, agentInstalled.

            '
          type: object
          properties:
            value:
              type: number
              format: double
              description: the daily saving amount for this result
            critical:
              type: integer
              description: number of critical security risks
            high:
              type: integer
              description: number of high security risks
            medium:
              type: integer
              description: number of medium security risks
            low:
              type: integer
              description: number of low security risks
            current:
              type: string
              description: the current state (i.e. current instance type)
            recommendation:
              type: string
              description: the recommended state (i.e. recommended instance type)
            agentInstalled:
              type: boolean
              description: true if the agent is installed
    ResourceResults:
      type: array
      description: A list of resource-level results for creating or updating an insight.
      items:
        $ref: '#/components/schemas/ResourceResultRequest'
    ResultsError:
      type: object
      description: Error details for a failed insight in a batch operation.
      properties:
        insightKey:
          type: string
          description: The key of the insight that failed.
        error:
          type: string
          description: The error message.
        code:
          type: integer
          description: The HTTP status code associated with the error.
    CreateCategory:
      type: string
      description: Allowed categories when creating insights via the public API.
      enum:
      - FinOps
      - Security
    InsightRequest:
      type: object
      description: Request body for creating or updating an insight via the batch endpoint. Includes resource results.
      required:
      - key
      - title
      - shortDescription
      - cloudProvider
      - categories
      - resourceResults
      properties:
        key:
          type: string
          description: A unique key for this insight within the source.
        title:
          type: string
          description: The display title of the insight.
        shortDescription:
          type: string
          description: A brief summary of the insight.
        detailedDescriptionMdx:
          type: string
          description: A detailed description of the insight in MDX format.
        cloudProvider:
          $ref: '#/components/schemas/CloudProvider'
        categories:
          description: One or more categories this insight belongs to.
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: '#/components/schemas/CreateCategory'
        reportUrl:
          type: string
          description: URL to an external report related to this insight.
        cloudFlowTemplateId:
          type: string
          description: ID of a CloudFlow template that can automate the remediation of this insight.
        easyWinDescription:
          type: string
          description: A description of why this insight is considered an easy win.
        resourceResults:
          $ref: '#/components/schemas/ResourceResults'
    InsightResponse:
      type: object
      description: An insight result containing summary information and metadata.
      properties:
        source:
          $ref: '#/components/schemas/Source'
        key:
          type: string
          description: The unique key identifying this insight.
        title:
          type: string
          description: The display title of the insight.
        shortDescription:
          type: string
          description: A brief summary of the insight.
        detailedDescriptionMdx:
          type: string
          description: A detailed description of the insight in MDX format.
        displayStatus:
          $ref: '#/components/schemas/DisplayStatus'
        cloudProvider:
          $ref: '#/components/schemas/CloudProvider'
        categories:
          description: Categories this insight belongs to.
          type: array
          items:
            $ref: '#/components/schemas/Category'
        summary:
          $ref: '#/components/schemas/InsightSummary'
        lastStatusChange:
          $ref: '#/components/schemas/LastInsightStatusChange'
        lastUpdated:
          type: string
          format: date-time
          description: Timestamp of the last update to this insight.
        tags:
          description: Tags for the insight, primarily used for security certification labels (e.g. ISO).
          type: array
          items:
            type: string
        reportUrl:
          type: string
          description: URL to an external report related to this insight.
        cloudFlowTemplateId:
          type: string
          description: ID of a CloudFlow template that can automate the remediation of this insight.
        easyWinDescription:
          type: string
          description: A description of why this insight is considered an easy win.
        dismissalDetails:
          $ref: '#/components/schemas/DismissalDetails'
    CreateResultsBody:
      type: object
      description: Request body for creating or updating multiple insights in a batch.
      required:
      - results
      properties:
        results:
          description: List of insights to create or update.
          type: array
          items:
            $ref: '#/components/schemas/InsightRequest'
    ResourceResult:
      type: object
      description: A single resource-level result within an insight, as returned in API responses.
      required:
      - resourceId
      - resultType
      - account
      - cloudProvider
      properties:
        resourceId:
          description: The cloud resource identifier.
          type: string
        resourceType:
          description: What the resource actually is, eg. for an EC2 resource ID, this field would be `instance`
          type: string
          example: instance, disk, cache
        cloudProvider:
          $ref: '#/components/schemas/CloudProvider'
        account:
          type: string
          description: The cloud account or project ID containing this resource.
        location:
          type: string
          description: represents the region/zone of the resource in AWS, or equivalent for other providers
          example: eu-west-2
        resolved:
          type: boolean
          description: Whether this resource-level issue has been resolved. Computed server-side.
        severity:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          description: The severity level of the finding. Computed server-side from the security risk counts.
        externalId:
          type: string
          descript

# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/doit/refs/heads/main/openapi/doit-insights-api-openapi.yml