> ## Documentation Index > Fetch the complete documentation index at: https://docs.merchkit.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an attribute definition > 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). ## OpenAPI ````yaml https://www.merchkit.com/api/v1/openapi post /attributes openapi: 3.1.0 info: title: Merchkit API version: 1.0.0 description: >- Operate your Merchkit PIM programmatically. Products, images, vendors, categories, and data sources are all "entities" in one uniform shape: system fields (`id`, `type`, `label`, `parent_id`, timestamps) at the top level and every customer-defined key — scalars AND references — in a sparse `attributes` map. References read as labeled stubs `{id, type, label}` and write as bare UUIDs or `{id}` objects ("write what you read"). UUIDs are the only path identifiers; find by your own key with a filter (`GET /products?filter[sku]=ARIA-DT-72`) or write by it with `POST /{resource}/upsert` and `/batch` (products, images, vendors, and categories only — sources have neither route; they are created by the async `POST /sources` job pipeline). Start every integration with `GET /attributes?type=product` to learn your keys. Completeness is per-channel. All errors share one envelope (see the `Error` schema). Authenticate with a workspace-scoped API key: `Authorization: Bearer mk_live_...`. See /llms.txt for an agent guide. servers: - url: https://www.merchkit.com/api/v1 description: Merchkit API v1 security: - ApiKeyAuth: [] paths: /attributes: post: summary: Create an attribute definition description: >- 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). operationId: createAttribute requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AttributeDefinitionCreate' example: name: Material entity_type: product data_type: single_select_list ai_generated: false acceptable_values: White Oak,Smoked Oak,Walnut responses: '201': description: The created attribute definition (full config). content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AttributeDefinitionDetail' example: data: id: a3d81c22-5f6e-4b09-8d17-c40a92e5b613 name: Material key: material data_type: single_select_list tool: manual entity_type: product channel: null is_primary: false custom_instructions: null acceptable_values: White Oak,Smoked Oak,Walnut default_value: null constraints: {} source_attributes: null '400': description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyAuth: [] components: schemas: AttributeDefinitionCreate: type: object description: >- Create body (snake_case, like every write body). `single_select_list`/`multi_select_list` require `acceptable_values`. required: - name - entity_type - data_type - ai_generated additionalProperties: false properties: name: type: string entity_type: type: string data_type: type: string enum: - 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 - status - progress - rank ai_generated: type: boolean custom_instructions: type: string description: Generation prompt; reference other attributes with {{key}}. acceptable_values: type: string description: Comma-separated allowed values for select attributes. default_value: type: string is_primary: type: boolean selected_tools: type: array items: type: string enum: - includeDataSources - includeImages - includeWebSearch - includeProductAttributes description: >- AI text-generation tools. includeWebSearch = live web research; includeDataSources = scraped sites/CSVs; includeImages = vision. source_attribute_keys: type: array items: type: string required_dependencies: type: array items: type: string image_model: type: string enum: - gpt-image-1 - nano-banana image_source_attribute_key: type: array items: type: string aspect_ratio: type: string enum: - Square - Landscape - Portrait video_model: type: string enum: - veo3.1 video_source_attribute_key: type: array items: type: string vision_image_source_attribute_key: type: array items: type: string inheritance_mode: type: string enum: - 'off' - inherit_from_parent - rollup_from_children description: >- 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: type: string enum: - unique - all description: >- Only with `rollup_from_children`. `unique` = distinct values joined; `all` = one entry per variant. Default `unique`. AttributeDefinitionDetail: type: object description: >- The full attribute-definition config returned by create/update — a superset of the discovery projection (raw `acceptable_values` string, generation `tool`, `constraints`). properties: id: type: string format: uuid name: type: string key: type: string data_type: type: string tool: type: string description: >- Generation tool, e.g. `manual`, `prompt`, `image-generation`, `formula`. entity_type: type: string channel: type: - string - 'null' is_primary: type: boolean custom_instructions: type: - string - 'null' acceptable_values: type: - string - 'null' description: The raw comma-separated string as stored. default_value: type: - string - 'null' constraints: type: object description: Generation/inheritance config (model, tools, source keys). source_attributes: type: - array - 'null' items: type: object properties: id: type: string key: type: string name: type: string example: id: a3d81c22-5f6e-4b09-8d17-c40a92e5b613 name: Material key: material data_type: single_select_list tool: manual entity_type: product channel: null is_primary: false custom_instructions: null acceptable_values: White Oak,Smoked Oak,Walnut default_value: null constraints: {} source_attributes: null Error: type: object description: >- The one error envelope every non-2xx response uses. `documentation_url` links to the code's section of the error docs. required: - error properties: error: type: object required: - code - message - is_retriable properties: code: type: string enum: - unauthorized - insufficient_scope - forbidden - not_found - validation_failed - rate_limited - conflict - internal_error message: type: string documentation_url: type: string format: uri description: https://docs.merchkit.com/developers/errors# is_retriable: type: boolean description: >- Only `rate_limited` and `internal_error` are retriable. Deterministic client errors (validation, not-found, conflict) return a 4xx and are never retriable. retry_after_seconds: type: - integer - 'null' alternative_action: type: string description: What to do instead, when there is a better call. request_id: type: string field_errors: type: array items: $ref: '#/components/schemas/FieldError' example: error: code: validation_failed message: 'Unknown attribute key(s): colour.' documentation_url: https://docs.merchkit.com/developers/errors#validation_failed is_retriable: false retry_after_seconds: null alternative_action: List valid attribute keys via GET /v1/attributes?type=product. request_id: req_01j9x2k8 field_errors: - field: colour issue: not_a_defined_attribute FieldError: type: object required: - field - issue properties: field: type: string issue: type: string description: Machine-readable issue code, e.g. `not_a_defined_attribute`. acceptable_values: type: array items: type: string description: 'For select-value violations: the allowed values.' securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- Workspace-scoped API key. Available scopes: - `read:products`: List and read products, including variants, references, and completeness. - `write:products`: Create, update, and upsert products and their attribute values. - `delete:products`: Delete products. - `read:images`: List and read images. - `write:images`: Create, update, and upsert images and their attribute values. - `delete:images`: Delete images. - `read:vendors`: List and read vendors. - `write:vendors`: Create, update, and upsert vendors and their attribute values. - `delete:vendors`: Delete vendors. - `read:categories`: List and read categories. - `write:categories`: Create, update, and upsert categories and their attribute values. - `delete:categories`: Delete categories. - `read:sources`: List and read data sources, including scraped content. - `write:sources`: Create data sources (triggers processing) and update their attribute values. - `delete:sources`: Delete data sources. - `read:attributes`: List and read attribute definitions. - `write:attributes`: Create and update attribute definitions. - `read:views`: List and read saved grid views (MCP surface). - `write:views`: Create and update grid views (MCP surface). - `read:channels`: Read the enabled channel catalog. - `read:events`: Read the workspace change feed and per-entity events. - `read:jobs`: List and poll asynchronous job status. ````