Create a category

post /api/categories

Creates a Category resource.

Creates a category. Set its status, optionally a name, and optionally a parent to nest it under an existing category, plus the products to classify under it.

Headers

Name	Type	Required	Description
`Flowkiwi-Locale`	`string`	-	Specifies the locale for properties that support localization. If not provided, the default locale will be used.

Request body

Property	Type	Required	Description
`attributes`	`string[]`	-	A list of `AttributeDefinition` IRIs attached to this category. Requires the `categories:read` scope. Returned empty when the scope is missing.
`children`	`string[]`	-	A list of direct child `Category` IRIs nested under this category. Requires the `categories:read` scope. Returned empty when the scope is missing.
`name`	`string \| null`	-	The name of the category.
`parent`	`string \| null`	-	The parent `Category` to which this category belongs, if any. Requires the `categories:read` scope. Returned null when the scope is missing.
`products`	`string[]`	-	List of products associated with the category. Requires the `products:read` scope. Returned empty when the scope is missing.
`status`	`"/api/statuses/DRAFT" \| "/api/statuses/ACTIVE" \| "/api/statuses/ARCHIVED"`	required	The status of the category.

Response

201 - Category resource created

Format

Property	Type	Required	Description
`@context`	`string \| object`	-
`@id`	`string`	required
`@type`	`string`	required
`attributes`	`string[]`	-	The attribute definitions attached to this category. Requires the `categories:read` scope. Returned empty when the scope is missing.
`children`	`array`	-	A list of direct child `Category`, each one representing a category under this one. Serialized as IRI strings by default; pass `?expand=children` to embed direct children (one level only). Requires the `categories:read` scope. Returned empty when the scope is missing.
`createdAt`	`string`	-	Creation date of the resource (ISO 8601 format).
`id`	`string`	-	The resource's unique identifier (UUID).
`name`	`string \| null`	-	This property supports translations. The name of the category.
`parent`	`string \| Category \| null`	-	The parent `Category` to which this category belongs, if any. Serialized as IRI string by default; pass `?expand=parent` to embed the direct parent (one level only). Requires the `categories:read` scope. Returned null when the scope is missing.
`products`	`string[]`	-	List of products associated with the category. Requires the `products:read` scope. Returned empty when the scope is missing.
`status`	`"/api/statuses/DRAFT" \| "/api/statuses/ACTIVE" \| "/api/statuses/ARCHIVED"`	-	The status of the category.
`updatedAt`	`string`	-	Last modification date of the resource (ISO 8601 format).

Property	Type	Required	Description
`attributes`	`string[]`	-	The attribute definitions attached to this category. Requires the `categories:read` scope. Returned empty when the scope is missing.
`children`	`array`	-	A list of direct child `Category`, each one representing a category under this one. Serialized as IRI strings by default; pass `?expand=children` to embed direct children (one level only). Requires the `categories:read` scope. Returned empty when the scope is missing.
`createdAt`	`string`	-	Creation date of the resource (ISO 8601 format).
`id`	`string`	-	The resource's unique identifier (UUID).
`name`	`string \| null`	-	This property supports translations. The name of the category.
`parent`	`string \| Category \| null`	-	The parent `Category` to which this category belongs, if any. Serialized as IRI string by default; pass `?expand=parent` to embed the direct parent (one level only). Requires the `categories:read` scope. Returned null when the scope is missing.
`products`	`string[]`	-	List of products associated with the category. Requires the `products:read` scope. Returned empty when the scope is missing.
`status`	`"/api/statuses/DRAFT" \| "/api/statuses/ACTIVE" \| "/api/statuses/ARCHIVED"`	-	The status of the category.
`updatedAt`	`string`	-	Last modification date of the resource (ISO 8601 format).

Errors

400 - Invalid input

Format

Property	Type	Required	Description
`@context`	`string \| object`	-
`@id`	`string`	required
`@type`	`string`	required
`code`	`string`	-	Stable identifier of the error in the error code catalogue (see /api/error-codes). Present on catalogued errors only.
`description`	`string \| null`	-
`detail`	`string \| null`	-	A human-readable explanation specific to this occurrence of the problem.
`instance`	`string \| null`	-	A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
`message`	`string`	-	End-user message localized in the request locale, with this occurrence's values substituted. Present on catalogued errors only.
`slug`	`string`	-	Stable, readable key of the error in the error code catalogue. Present on catalogued errors only.
`status`	`integer \| null`	-
`title`	`string \| null`	-	A short, human-readable summary of the problem. For a catalogued error it repeats the `slug`.
`type`	`string`	-	A URI reference that identifies the problem type. For a catalogued error it is the error code resource, `/api/error-codes/{code}`.

Property	Type	Required	Description
`code`	`string`	-	Stable identifier of the error in the error code catalogue (see /api/error-codes). Present on catalogued errors only.
`detail`	`string \| null`	-	A human-readable explanation specific to this occurrence of the problem.
`instance`	`string \| null`	-	A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
`message`	`string`	-	End-user message localized in the request locale, with this occurrence's values substituted. Present on catalogued errors only.
`slug`	`string`	-	Stable, readable key of the error in the error code catalogue. Present on catalogued errors only.
`status`	`integer \| null`	-
`title`	`string \| null`	-	A short, human-readable summary of the problem. For a catalogued error it repeats the `slug`.
`type`	`string`	-	A URI reference that identifies the problem type. For a catalogued error it is the error code resource, `/api/error-codes/{code}`.

403 - Access denied. The caller is missing one or more permissions required for this operation.

Content-Type: application/problem+json

Property	Type	Required	Description
`@context`	`string \| object`	-
`@id`	`string`	required
`@type`	`string`	required
`detail`	`string`	-
`missingPermissions`	`string[]`	-	Permissions that the caller is missing for this operation. Present only when the 403 is caused by a denied permission.
`status`	`integer`	-
`title`	`string`	-
`type`	`string`	-

422 - An error occurred

Format

Property Type Required Description

@context string | object -

@id string required

@type string required

description string -

detail string -

instance string | null -

status integer -

title string | null -

type string -

violations object[] -

Show violations fields

Property	Type	Required	Description
`code`	`string`	-	The code of the violation
`hint`	`string`	-	An extra hint to understand the violation
`message`	`string`	required	The message associated with the violation
`parameters`	`object`	-	Dynamic placeholder values for the violation message template (substitute into the code catalogue message).
`payload`	`object`	-	The serialized payload of the violation
`propertyPath`	`string`	required	The property path of the violation
`slug`	`string`	-	Stable centralized error-code slug for this violation (see /api/error-codes).

Property Type Required Description

detail string -

instance string | null -

status integer -

title string | null -

type string -

violations object[] -

Show violations fields

Property	Type	Required	Description
`code`	`string`	-	The code of the violation
`hint`	`string`	-	An extra hint to understand the violation
`message`	`string`	required	The message associated with the violation
`parameters`	`object`	-	Dynamic placeholder values for the violation message template (substitute into the code catalogue message).
`payload`	`object`	-	The serialized payload of the violation
`propertyPath`	`string`	required	The property path of the violation
`slug`	`string`	-	Stable centralized error-code slug for this violation (see /api/error-codes).