---
id: action-item-category-create
title: "Create a category"
description: "Create a new action item category. Categories classify action items and define governance rules."
sidebar_label: "Create a category"
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 category"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/action_item_category"}
  context={"endpoint"}
>
  
</MethodEndpoint>



Create a new action item category. Categories classify action items and define governance rules.

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

<ParamsDetails
  parameters={undefined}
>
  
</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nrn","name","description"],"properties":{"nrn":{"type":"string","description":"The NRN that owns this category.","example":"organization=1:account=2"},"name":{"type":"string","description":"The display name of the category. Must be unique per NRN.","example":"Security vulnerabilities"},"description":{"type":"string","description":"A description of what this category tracks.","example":"Tracks security issues found by automated scanners"},"parent_id":{"type":"string","description":"The ID of the parent category, for creating a subcategory. Max two levels of nesting.","example":"abc123def456"},"color":{"type":"string","description":"Hex color code for the category in the UI.","example":"#E53E3E"},"icon":{"type":"string","description":"Icon name for the category in the UI.","example":"shield"},"unit_name":{"type":"string","description":"Display name for the unit of value (e.g., Dollars, Hours).","example":"Dollars"},"unit_symbol":{"type":"string","description":"Display symbol for the unit of value.","example":"$"},"config":{"type":"object","description":"Deferral limits for a category. Approval gating for resolve, defer, and reject\nis no longer configured here. It is driven by approval actions in the approvals\nengine. See the `action_item` entity in the Approval API.\n","properties":{"max_deferral_days":{"type":"integer","description":"Maximum number of days an item can be deferred into the future.","example":90},"max_deferral_count":{"type":"integer","description":"Maximum number of times an item can be deferred.","example":3}},"title":"CategoryConfig"}}}}}}}
>
  
</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"201":{"description":"The created category.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The unique category ID.","example":"abc123def456"},"slug":{"type":"string","description":"Auto-generated URL-friendly slug.","example":"security-vulnerabilities"},"nrn":{"type":"string","description":"The NRN that owns this category.","example":"organization=1:account=2"},"parent_id":{"type":"string","description":"The parent category ID, if this is a subcategory.","example":null},"name":{"type":"string","description":"The display name.","example":"Security vulnerabilities"},"description":{"type":"string","description":"A description of the category.","example":"Tracks security issues found by automated scanners"},"color":{"type":"string","description":"Hex color code.","example":"#E53E3E"},"icon":{"type":"string","description":"Icon name.","example":"shield"},"unit_name":{"type":"string","description":"Display name for the unit of value.","example":"Dollars"},"unit_symbol":{"type":"string","description":"Display symbol for the unit of value.","example":"$"},"config":{"type":"object","description":"Deferral limits for a category. Approval gating for resolve, defer, and reject\nis no longer configured here. It is driven by approval actions in the approvals\nengine. See the `action_item` entity in the Approval API.\n","properties":{"max_deferral_days":{"type":"integer","description":"Maximum number of days an item can be deferred into the future.","example":90},"max_deferral_count":{"type":"integer","description":"Maximum number of times an item can be deferred.","example":3}},"title":"CategoryConfig"},"status":{"type":"string","enum":["active","inactive"],"description":"The category status.","example":"active"},"children":{"type":"array","description":"Subcategories of this category. Populated on read, empty array if none.","items":"circular(Category)"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","example":"2026-04-01T10:00:00.000Z"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp.","example":"2026-04-01T10:00:00.000Z"}},"title":"Category"}}}},"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>