---
id: suggestion-create
title: "Create a suggestion"
description: "Create a new suggestion for an action item. Suggestions are created in `pending` status."
sidebar_label: "Create a suggestion"
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "post api-method"
info_path: docs/api/action-items
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create a suggestion"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/action_item/{id}/suggestions"}
  context={"endpoint"}
>
  
</MethodEndpoint>



Create a new suggestion for an action item. Suggestions are created in `pending` status.

The suggestion creator is always set from the authenticated user's bearer token.


<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"in":"path","name":"id","schema":{"type":"string"},"required":true,"description":"The action item ID.","example":"xYz789AbCdEf"}]}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["owner"],"properties":{"owner":{"type":"string","description":"The agent or system that will execute the fix when approved.","example":"image-updater-agent"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence score between 0 and 1.","example":0.92},"description":{"type":"string","description":"A description of the proposed fix. Supports Markdown.","example":"Update the Dockerfile base image to resolve CVE-2026-1234."},"metadata":{"type":"object","description":"Machine-to-machine metadata for the executor.","example":{"repository":"org/my-api-service","branch":"fix/cve-2026-1234"}},"user_metadata":{"type":"object","description":"Human-editable parameters that can be adjusted before approval.","example":{"target_version":"20-alpine3.19"}},"user_metadata_config":{"type":"object","description":"JSON Schema defining the structure and UI rendering of `user_metadata`.","example":{"type":"object","properties":{"target_version":{"type":"string","title":"Target image version"}}}},"expires_at":{"type":"string","format":"date","description":"Expiration date. The suggestion expires if not acted upon by this date.","example":"2026-05-15"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"The created suggestion.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The unique suggestion ID.","example":"sUg123AbCdEf"},"slug":{"type":"string","description":"Auto-generated URL-friendly slug.","example":"update-dockerfile-base-image"},"action_item_id":{"type":"string","description":"The parent action item ID.","example":"xYz789AbCdEf"},"status":{"type":"string","enum":["pending","approved","applied","failed","rejected","expired"],"description":"The current status.","example":"pending"},"created_by":{"type":"string","description":"The agent that created the suggestion.","example":"security-scanner-agent"},"owner":{"type":"string","description":"The agent or system that will execute the fix.","example":"image-updater-agent"},"confidence":{"type":"number","description":"Confidence score between 0 and 1.","example":0.92},"description":{"type":"string","description":"A description of the proposed fix. Supports Markdown.","example":"Update the Dockerfile base image to resolve CVE-2026-1234."},"metadata":{"type":"object","description":"Machine-to-machine metadata for the executor.","example":{"repository":"org/my-api-service","branch":"fix/cve-2026-1234"}},"user_metadata":{"type":"object","description":"Human-editable parameters.","example":{"target_version":"20-alpine3.19"}},"user_metadata_config":{"type":"object","description":"JSON Schema for rendering `user_metadata` in the UI."},"execution_result":{"type":"object","description":"Result of a suggestion execution.","properties":{"success":{"type":"boolean","description":"Whether the execution succeeded.","example":true},"message":{"type":"string","description":"A summary message.","example":"Base image updated successfully."},"details":{"type":"object","description":"Additional details, such as a link to the resulting PR.","example":{"pull_request":"https://github.com/org/my-api-service/pull/42"}}},"title":"ExecutionResult"},"executed_at":{"type":"string","format":"date","description":"Date when the suggestion was executed.","example":null},"expires_at":{"type":"string","format":"date","description":"Expiration date.","example":"2026-05-15"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","example":"2026-04-06T12:30:00.000Z"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp.","example":"2026-04-06T12:30:00.000Z"}},"title":"Suggestion"}}}},"4XX":{"description":"Client error responses due to invalid input, missing parameters, or unauthorized access.\n\nRequest validation errors use a different shape:\n```json\n{\n  \"type\": \"ValidationError\",\n  \"errors\": [{ \"message\": \"body must have required property 'defer_until'\" }]\n}\n```\n","content":{"application/json":{"schema":{"oneOf":[{"type":"object","description":"Standard error response.","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code (e.g., 400, 401, 403, 404).","example":400},"code":{"type":"string","description":"Machine-readable error code.","example":"bad_request"},"error":{"type":"string","description":"Short description of the error type.","example":"Bad Request"},"message":{"type":"string","description":"Additional details about the error.","example":"The request was malformed or contained invalid parameters."}}},{"type":"object","description":"Request validation error response.","required":["type","errors"],"properties":{"type":{"type":"string","example":"ValidationError"},"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","example":"body must have required property 'until'"}}}}}}]}}}},"5XX":{"description":"Server error responses indicating an issue on the API side.","content":{"application/json":{"schema":{"type":"object","required":["statusCode","error","message"],"properties":{"statusCode":{"type":"integer","description":"HTTP status code representing the specific server error.","example":500},"code":{"type":"string","description":"A machine-readable error code that categorizes the server failure.","example":"internal_server_error"},"error":{"type":"string","description":"A brief, human-readable description of the error type.","example":"Internal Server Error"},"message":{"type":"string","description":"Additional details about the error.","example":"An unexpected error occurred on the server."}}}}}}}}
>
  
</StatusCodes>