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.
Requestβ
Content-Type: application/json
Schemaβ
{
"type": "object",
"description": "Request body for creating or updating an insight.",
"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": {
"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"
]
}
},
"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."
},
"resourceResults": {
"type": "array",
"description": "A list of resource-level results.",
"items": {
"type": "object",
"description": "A single resource-level result within an insight.",
"required": [
"resourceId",
"resultType",
"account",
"cloudProvider"
],
"properties": {
"resourceId": {
"description": "The cloud resource identifier."
},
"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": {
"type": "string",
"example": "aws",
"description": "The cloud provider associated with the resource."
},
"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."
},
"severity": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
],
"description": "The severity level of the finding."
},
"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"
},
"enhancement": {
"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."
}
}
},
"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.\n",
"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"
}
}
}
}
}
}
}
}
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."
}
}
}
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