create-insights

dci create-insights [body]

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.

Pass the request body as name: value arguments or pipe JSON on stdin — see Command structure.

Examples

# Create or update several insights, each with its resource results inline, from a file.
dci create-insights < insights.json

# insights.json
{"results": [{
  "key": "idle-ec2-instances", "title": "Idle EC2 instances",
  "shortDescription": "Instances under 5% CPU for the last 14 days",
  "cloudProvider": "aws", "categories": ["FinOps"],
  "resourceResults": [{
    "account": "123456789012", "cloudProvider": "aws",
    "resourceId": "i-0abc123def4567890", "resourceType": "instance", "location": "eu-west-2",
    "resultType": "potential_daily_savings_with_recommendation",
    "result": {"value": 12.5, "current": "m5.2xlarge", "recommendation": "m5.large"}
  }]
}]}

# The same batch, printing the API response as JSON for a pipeline log.
dci create-insights --output json < insights.json

Request

Content-Type: application/json

Field	Type	Required	Description
`results`	array of object	yes	List of insights to create or update.
`results[].key`	string	yes	A unique key for this insight within the source.
`results[].title`	string	yes	The display title of the insight.
`results[].shortDescription`	string	yes	A brief summary of the insight.
`results[].detailedDescriptionMdx`	string		A detailed description of the insight in MDX format.
`results[].cloudProvider`	string	yes	The cloud provider associated with the resource.
`results[].categories`	array of string	yes	One or more categories this insight belongs to.
`results[].reportUrl`	string		URL to an external report related to this insight.
`results[].cloudFlowTemplateId`	string		ID of a CloudFlow template that can automate the remediation of this insight.
`results[].easyWinDescription`	string		A description of why this insight is considered an easy win.
`results[].resourceResults`	array of object	yes	A list of resource-level results for creating or updating an insight.
`results[].resourceResults[].resourceId`	string	yes	The cloud resource identifier.
`results[].resourceResults[].resourceType`	string		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.
`results[].resourceResults[].cloudProvider`	string	yes	Immutable after creation — updates to this field are silently ignored.
`results[].resourceResults[].account`	string	yes	The cloud account or project ID containing this resource. Immutable after creation — updates to this field are silently ignored.
`results[].resourceResults[].location`	string		Represents the region/zone of the resource in AWS, or equivalent for other providers. Immutable after creation — updates to this field are silently ignored.
`results[].resourceResults[].externalId`	string		the external ID of the resource in the provider's system for the resource
`results[].resourceResults[].externalUrl`	string		the URL to the resource-level issue in the provider's system
`results[].resourceResults[].metadata`	object		contains any additional information for the resource results
`results[].resourceResults[].resultType`	string	yes	The discriminator property that determines which fields are populated in the 'result' object. One of: `"security_risk"`, `"potential_daily_savings"`, `"potential_daily_savings_with_recommendation"`, `"potential_daily_savings_with_cluster_agent"`.
`results[].resourceResults[].result`	object		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.
`results[].resourceResults[].result.value`	number (double)		the daily saving amount for this result
`results[].resourceResults[].result.critical`	integer		number of critical security risks
`results[].resourceResults[].result.high`	integer		number of high security risks
`results[].resourceResults[].result.medium`	integer		number of medium security risks
`results[].resourceResults[].result.low`	integer		number of low security risks
`results[].resourceResults[].result.current`	string		the current state (i.e. current instance type)
`results[].resourceResults[].result.recommendation`	string		the recommended state (i.e. recommended instance type)
`results[].resourceResults[].result.agentInstalled`	boolean		true if the agent is installed

Raw JSON schema

{
  "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": {
        "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": {
            "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."
          },
          "resourceResults": {
            "type": "array",
            "description": "A list of resource-level results for creating or updating an insight.",
            "items": {
              "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.\n",
              "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.\n",
                  "type": "string",
                  "example": "instance, disk, cache"
                },
                "cloudProvider": {
                  "description": "Immutable after creation — updates to this field are silently ignored.",
                  "allOf": [
                    {
                      "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. 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.\n",
                  "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.\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"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Output

Successful operation

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

Field	Type	Description
`[].insightKey`	string	The key of the insight that failed.
`[].error`	string	The error message.
`[].code`	integer	The HTTP status code associated with the error.

Raw JSON schema

{
  "type": "array",
  "items": {
    "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."
      }
    }
  }
}

Errors

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping

HTTP status	Exit code	Error code	Meaning
400	30	`VALIDATION_ERROR`	The arguments or request body were rejected. Review the command's flags and payload.
401	10	`AUTHENTICATION_FAILED`	Not signed in, or the API token is invalid. Run `dci login` or check `DCI_API_KEY`.
403	11	`PERMISSION_DENIED`	The DoiT user or the active customer context does not have access.
404	20	`RESOURCE_NOT_FOUND`	The requested resource does not exist. Check the identifier argument.
500	40	`API_SERVER_ERROR`	The API failed to process the request. Retryable; contact DoiT support if it persists.

create-insight — Create or update an insight
replace-insight-resource-results — Replace resource results for an insight
list-insights — List insights
delete-insights — Delete insights (batch)
API reference: POST /insights/v1/results

Aliases: post-insight-results

Examples​

Request​

Output​

Errors​

Related​

Examples

Request

Output

Errors

Related