---
title: "Create an attribute definition"
method: POST
path: "/attributes"
---

# Create an attribute definition

`POST /attributes`

## Request

- Base URL: `https://www.merchkit.com/api/v1`
- URL: `https://www.merchkit.com/api/v1/attributes`
- Auth: HTTP bearer

Create an attribute, including full AI-generation config (snake_case body). For an AI-generated attribute set `ai_generated: true` + `custom_instructions` (reference other attributes with `{{key}}`), and pick `selected_tools`: `includeWebSearch` (live web research), `includeDataSources` (scraped sites/CSVs), `includeImages` (vision), `includeProductAttributes`. Image/video generation models are supported. `inheritance_mode` shares a value across a variant family (products only).

Scope: `write:attributes`.

## Request body

- AttributeDefinitionCreate: Create body (snake_case, like every write body). `single_select_list`/`multi_select_list` require `acceptable_values`.
  - `name` string, required
  - `entity_type` string, required
  - `data_type` 'single_line_text_field' | 'multi_line_text_field' | 'rich_text_field' | 'number' | 'boolean' | 'date' | 'url' | 'json' | 'single_select_list' | 'multi_select_list' | 'image' | 'video' | 'formula' | 'web_preview' | 'status' | 'progress' | 'rank', required
  - `ai_generated` boolean, required
  - `custom_instructions` string: Generation prompt; reference other attributes with {{key}}.
  - `formula_expression` string: Template of a computed column: a formula expression, or an HTML template with `data_type: web_preview`. Makes the attribute computed (not AI-generated).
  - `acceptable_values` string: Comma-separated allowed values for select attributes.
  - `default_value` string
  - `is_primary` boolean
  - `selected_tools` string[]: AI text-generation tools. includeWebSearch = live web research; includeDataSources = scraped sites/CSVs; includeImages = vision.
  - `source_attribute_keys` string[]
  - `required_dependencies` string[]
  - `image_model` 'gpt-image-1' | 'nano-banana'
  - `image_source_attribute_key` string[]
  - `aspect_ratio` '1:1' | '4:3' | '3:4' | '16:9' | '9:16': Image generation aspect ratio. Legacy values (`Square`→`1:1`, `Landscape`→`16:9`, `Portrait`→`9:16`) are still accepted for backward compatibility but are deprecated.
  - `video_model` 'veo3.1'
  - `video_source_attribute_key` string[]
  - `vision_image_source_attribute_key` string[]
  - `inheritance_mode` 'off' | 'inherit_from_parent' | 'rollup_from_children': Parent/child variant inheritance (products only; ignored for image/video attributes). `inherit_from_parent` = variants display the parent's value; `rollup_from_children` = the parent displays its variants' combined values; `off` removes inheritance. Virtualized at read time.
  - `rollup_aggregation` 'unique' | 'all': Only with `rollup_from_children`. `unique` = distinct values joined; `all` = one entry per variant. Default `unique`.

## Response `201`

The created attribute definition (full config).

- object
  - `data` AttributeDefinitionDetail: The full attribute-definition config returned by create/update — a superset of the discovery projection (raw `acceptable_values` string, generation `tool`, `constraints`).
    - `id` string, uuid
    - `name` string
    - `key` string
    - `data_type` string
    - `tool` string: Generation tool, e.g. `manual`, `prompt`, `image-generation`, `formula`.
    - `entity_type` string
    - `channel` string, nullable
    - `is_primary` boolean
    - `custom_instructions` string, nullable
    - `acceptable_values` string, nullable: The raw comma-separated string as stored.
    - `default_value` string, nullable
    - `constraints` object: Generation/inheritance config (model, tools, source keys).
    - `source_attributes` object[], nullable
      - `id` string
      - `key` string
      - `name` string

## Other responses

- `400`: Validation failed.

---

[API](https://skmtc.dev/merchkit/apis/merchkit-api.md) - [All operations](https://skmtc.dev/merchkit/apis/merchkit-api/llms.txt) - [OpenAPI document](https://skmtc.dev/merchkit/apis/merchkit-api/revisions/3062ca814757?raw)