post-insight-result

dci post-insight-result sourceID insightKey

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.

Request

Content-Type: application/json

Schema

{
  "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": {
      "type": "string",
      "example": "aws",
      "description": "The cloud provider associated with the resource."
    },
    "categories": {
      "description": "One or more categories this insight belongs to.",
      "type": "array",
      "minItems": 1,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "description": "Allowed categories when creating insights via the public API.",
        "enum": [
          "FinOps",
          "Security"
        ]
      }
    },
    "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": {
      "type": "string",
      "enum": [
        "actionable",
        "acknowledged",
        "optimized",
        "dismissed",
        "in progress",
        "upgrade needed",
        "permissions needed"
      ],
      "description": "The display status of the insight."
    },
    "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."
        }
      }
    }
  }
}

Responses

200 (application/json)

Successful operation

{
  "type": "object",
  "description": "An insight result containing summary information and metadata.",
  "properties": {
    "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"
    },
    "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": {
      "type": "string",
      "enum": [
        "actionable",
        "acknowledged",
        "optimized",
        "dismissed",
        "in progress",
        "upgrade needed",
        "permissions needed"
      ],
      "description": "The display status of the insight."
    },
    "cloudProvider": {
      "type": "string",
      "example": "aws",
      "description": "The cloud provider associated with the resource."
    },
    "categories": {
      "description": "Categories this insight belongs to.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "The insight category.",
        "enum": [
          "FinOps",
          "Operational excellence",
          "Performance efficiency",
          "Reliability",
          "Security",
          "Sustainability"
        ]
      }
    },
    "summary": {
      "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."
        }
      }
    },
    "lastStatusChange": {
      "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.\n",
          "type": "string",
          "example": "/users/0Rkrkeq5P0XLe8QFHKq2"
        },
        "lastChangedAt": {
          "type": "string",
          "format": "date-time"
        }
      },
      "required": [
        "userId",
        "lastChangedAt"
      ]
    },
    "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": {
      "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."
        }
      }
    }
  }
}

400 (application/json)

Bad Request - The server cannot process the request, often due to a malformed request.

{
  "type": "object",
  "description": "Standard error response structure.",
  "properties": {
    "error": {
      "type": "string",
      "description": "Detailed error message."
    }
  }
}

401 (application/json)

Unauthorized - Invalid API key.

{
  "type": "object",
  "description": "Standard error response structure.",
  "properties": {
    "error": {
      "type": "string",
      "description": "Detailed error message."
    }
  }
}

403 (application/json)

Forbidden - The client is not authorized to perform the request.

{
  "type": "object",
  "description": "Standard error response structure.",
  "properties": {
    "error": {
      "type": "string",
      "description": "Detailed error message."
    }
  }
}

500 (application/json)

Internal Server Error - Something went wrong with the DoiT API server.

{
  "type": "object",
  "description": "Standard error response structure.",
  "properties": {
    "error": {
      "type": "string",
      "description": "Detailed error message."
    }
  }
}

Aliases: post-insight-result, postinsightresult