# Create an attribute definition
> Create a new attribute definition.
{/* generated:versioned-pages - edit _pm-authored, not this file */}
`POST /api/attribute_definitions`
Creates a AttributeDefinition resource.
Creates an attribute definition. `code` and `type` (`string` or `list`) are required and cannot be changed afterwards, nor can `multiple`. Attach it to categories with `categories`, and send `Flowkiwi-Locale` to set the translatable `name` for a specific locale. The response is the full attribute definition.
> **Immutable fields**
>
> `multiple` defaults to `true` and only matters for `list` definitions: it is always normalized to `false` for `string` definitions, whatever you send.
## 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 |
| ------------ | ---------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `categories` | `string[]` | - | Requires the `categories:read` scope. Returned empty when the scope is missing. |
| `code` | `string \| null` | Yes | |
| `multiple` | `boolean` | - | Whether products may carry several values (one per option) for this definition. Only meaningful for `list` definitions; normalized to `false` for `string` definitions regardless of the value sent. Immutable once created. |
| `name` | `string \| null` | - | |
| `type` | `"string" \| "list" \| null` | Yes | |
## Response
**201** - AttributeDefinition resource created
| Property | Type | Required | Description |
| ------------- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@context` | `string \| object` | - | |
| `@id` | `string` | Yes | |
| `@type` | `string` | Yes | |
| `categories` | `string[]` | - | The categories this attribute definition is attached to. Requires the `categories:read` scope. Returned empty when the scope is missing. |
| `code` | `string \| null` | - | The stable, machine-readable identifier of the attribute definition (e.g. `color`, `care-instructions`). Immutable once created. |
| `createdAt` | `string` | - | Creation date of the resource (ISO 8601 format). |
| `id` | `string` | - | |
| `multiple` | `boolean` | - | Whether products may carry several values for this definition (one per option). Meaningful for `list` definitions only; always `false` for `string` definitions regardless of the requested value. Immutable once created. |
| `name` | `string \| null` | - | **This property supports translations.**
The human-readable name of the attribute definition. |
| `type` | `"string" \| "list" \| null` | - | The type of the attribute definition, determining whether its values are free text (`string`) or must come from a fixed set of options (`list`). Immutable once created. |
| `updatedAt` | `string` | - | Last modification date of the resource (ISO 8601 format). |
| `valuesCount` | `integer` | - | The count of the product attribute values that reference this definition. |
## Errors
**400** - Invalid input
| Property | Type | Required | Description |
| ------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `@context` | `string \| object` | - | |
| `@id` | `string` | Yes | |
| `@type` | `string` | Yes | |
| `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}`. |
**403** - Access denied. The caller is missing one or more permissions required for this operation.
| Property | Type | Required | Description |
| -------------------- | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `@context` | `string \| object` | - | |
| `@id` | `string` | Yes | |
| `@type` | `string` | Yes | |
| `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
| Property | Type | Required | Description |
| ------------- | ------------------ | -------- | ----------- |
| `@context` | `string \| object` | - | |
| `@id` | `string` | Yes | |
| `@type` | `string` | Yes | |
| `description` | `string` | - | |
| `detail` | `string` | - | |
| `instance` | `string \| null` | - | |
| `status` | `integer` | - | |
| `title` | `string \| null` | - | |
| `type` | `string` | - | |
| `violations` | `object[]` | - | |
## Examples
### Example request
```bash
curl -X POST 'https://.product-management.flowkiwi.net/api/attribute_definitions' \
-H 'Authorization: Bearer {access_token}' \
-H 'Flowkiwi-Api-Version: unstable' \
-H 'Accept: application/ld+json' \
-H 'Content-Type: application/ld+json' \
-d '{
"categories": [
"/api/categories/019afd02-2b3c-7d4e-9f50-1a2b3c4d5e6f"
],
"code": "color",
"multiple": true,
"name": "Color",
"type": "list"
}'
```
### Example response
```json
{
"@context": "/api/contexts/AttributeDefinition",
"@id": "/api/attribute_definitions/019afd10-3c4d-7e5f-8a60-2b3c4d5e6f70",
"@type": "AttributeDefinition",
"categories": [
"/api/categories/019afd02-2b3c-7d4e-9f50-1a2b3c4d5e6f"
],
"code": "color",
"createdAt": "2026-01-15T09:30:00+00:00",
"id": "019afd10-3c4d-7e5f-8a60-2b3c4d5e6f70",
"multiple": true,
"name": "Color",
"type": "list",
"updatedAt": "2026-02-03T14:45:12+00:00",
"valuesCount": 12
}
```