---
title: "Create a suggestion"
method: POST
path: "/action_item/{id}/suggestions"
tags: ["Suggestion"]
---

# Create a suggestion

`POST /action_item/{id}/suggestions`

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.

## Path parameters

- `id` string, required

## Request body

- object
  - `owner` string, required — The agent or system that will execute the fix when approved.
  - `confidence` number — Confidence score between 0 and 1.
  - `description` string — A description of the proposed fix. Supports Markdown.
  - `metadata` object — Machine-to-machine metadata for the executor.
  - `user_metadata` object — Human-editable parameters that can be adjusted before approval.
  - `user_metadata_config` object — JSON Schema defining the structure and UI rendering of `user_metadata`.
  - `expires_at` string, date — Expiration date. The suggestion expires if not acted upon by this date.

## Response `201`

The created suggestion.

- Suggestion
  - `id` string — The unique suggestion ID.
  - `slug` string — Auto-generated URL-friendly slug.
  - `action_item_id` string — The parent action item ID.
  - `status` 'pending' | 'approved' | 'applied' | 'failed' | 'rejected' | 'expired' — The current status.
  - `created_by` string — The agent that created the suggestion.
  - `owner` string — The agent or system that will execute the fix.
  - `confidence` number — Confidence score between 0 and 1.
  - `description` string — A description of the proposed fix. Supports Markdown.
  - `metadata` object — Machine-to-machine metadata for the executor.
  - `user_metadata` object — Human-editable parameters.
  - `user_metadata_config` object — JSON Schema for rendering `user_metadata` in the UI.
  - `execution_result` ExecutionResult — Result of a suggestion execution.
    - `success` boolean — Whether the execution succeeded.
    - `message` string — A summary message.
    - `details` object — Additional details, such as a link to the resulting PR.
  - `executed_at` string, date — Date when the suggestion was executed.
  - `expires_at` string, date — Expiration date.
  - `created_at` string, date-time — Creation timestamp.
  - `updated_at` string, date-time — Last update timestamp.

## Other responses

- `4XX` — Client error responses due to invalid input, missing parameters, or unauthorized access. Request validation errors use a different shape: ```json { "type": "ValidationError", "errors": [{ "message": "body must have required property 'defer_until'" }] } ```
- `5XX` — Server error responses indicating an issue on the API side.

---

[API](https://skmtc.dev/nullplatform/apis/nullplatform-api.md) · [All operations](https://skmtc.dev/nullplatform/apis/nullplatform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nullplatform/nullplatform-api/revisions/1c4ea154b159/schema)