fabric Attributes API

openapi: 3.2.0
info:
  title: Fabric Com Attributes API
  license:
    name: fabric API License
    url: https://fabric.inc/api-license
  x-refined-note:
  - x-audience differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Attributes across 2 of this provider''s published API definitions: fabric-pim-openapi.yml, fabric-product-agent-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://live.copilot.fabric.inc
  description: Production
- url: https://commerceos.aiagents.fabric.inc/api
  description: Production API
tags:
- name: Attributes
  description: Item attributes are the objective and factual descriptions of items that shoppers see when they browse through your site. Attributes may be technical specifications like size, weight, etc., design specifications like color, material, etc., or basic specifications like name, description, and ID. Ites attributes are crucial as they directly influence purchasing decisions. Complete and correct item information help shoppers narrow down their search and filter items with minimal cognitive load.
paths:
  /api-category/v1/category/attribute/bulk:
    post:
      tags:
      - Attributes
      summary: Create, Update and Delete Category Attributes
      description: 'Creates, updates and deletes category attributes. The primary purpose is to create and edit the attributes to be assigned to categories. <br /> **Note**: They are generic category attributes and not specific to a category.'
      operationId: postCategoryAttributeBulk
      security:
      - authorization: []
      - api_key: []
      parameters:
      - $ref: '#/components/parameters/xSiteContent'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkAttributeRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkAttributeResponse'
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
    servers:
    - url: https://live.copilot.fabric.inc
      description: Production
  /api-product/v1/product/attribute/bulk:
    post:
      tags:
      - Attributes
      summary: Create Update and Delete Item Attributes
      description: 'Item attributes allow you to define specific characteristics for items. Common examples of attributes include size, color, and material. Well-defined attributes are important because they enable item discovery and make catalog management easier. <br /> This endpoint creates and updates item attributes to be assigned later. <br /> **Note**: <br /> 1) You can add and manage unlimited attributes for your items. Once they are created, they appear as a selectable option on product pages. <br /> 2) In addition, you can assign attributes to items on an individual level or in bulk.'
      operationId: postProductAttributeBulk
      security:
      - authorization: []
      parameters:
      - $ref: '#/components/parameters/xSiteContent'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkProductAttributeRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkAttributeResponse'
        '400':
          description: Client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
    servers:
    - url: https://live.copilot.fabric.inc
      description: Production
  /api-product/v1/product/attribute-group:
    post:
      tags:
      - Attributes
      summary: Create, Update and Delete Attribute Groups
      description: 'Using attribute groups, you can group various attributes together to make it easier to manage large volume of item information. <br /> Use this endpoint to create, update, or delete attribute groups. <br /> **Note**: In the context of Product Catalog, attribute group is optional. When created, it must have at least one attribute.'
      operationId: modifyAttributeGroups
      security:
      - authorization: []
      parameters:
      - $ref: '#/components/parameters/xSiteContent'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributeGroupRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeGroupResponse'
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
    servers:
    - url: https://live.copilot.fabric.inc
      description: Production
  /api-product/v1/product/attribute-group/search:
    post:
      tags:
      - Attributes
      summary: Find Attribute Groups
      description: Find attribute groups based on the given search criteria. You will get a paginated response, which you can narrow down using filter criteria such as `page` and `size`.
      operationId: searchAttributeGroups
      security:
      - authorization: []
      parameters:
      - $ref: '#/components/parameters/xSiteContent'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributeGroupSearchRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeGroupSearchResponse'
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
    servers:
    - url: https://live.copilot.fabric.inc
      description: Production
  /api-product/v1/product/attribute/mapping/search:
    post:
      tags:
      - Attributes
      summary: Find Attribute Mapping
      description: Searches for attribute mapping based on the given search criteria. You will get a paginated response, which you can narrow down using filter criteria such as `page` and `size`.
      operationId: searchAttributeMappings
      security:
      - authorization: []
      parameters:
      - $ref: '#/components/parameters/xSiteContent'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributeMappingSearch'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeMappingPaginationResponse'
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
    servers:
    - url: https://live.copilot.fabric.inc
      description: Production
  /api-product/v1/product/attribute/mapping:
    post:
      tags:
      - Attributes
      summary: Create and Update Attribute Mappings
      description: Set your attribute mapping to begin configuring your catalog. You can update the mappings only if there are no SKUs present in the catalog.
      security:
      - authorization: []
      parameters:
      - $ref: '#/components/parameters/xSiteContent'
      operationId: modifyAttributeMappings
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributeMappingModify'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeMappingResponse'
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
    servers:
    - url: https://live.copilot.fabric.inc
      description: Production
  /v2/attributes/import:
    post:
      summary: Import Attributes from CSV
      description: 'Upload a CSV file to import attribute definitions for the specified brand/domain. The import is processed asynchronously.


        **Expected CSV columns**

        - **attribute_name** (required): Attribute display name

        - **attribute_key** (optional): Machine-readable key

        - **description** (optional): Attribute description

        - **data_type** (optional): Data type

        - **scope** (optional): Attribute scope

        - **enum_values** (optional): Allowed values, pipe-delimited (e.g. `S|M|L`)

        - **allow_ai_content** (optional): Allow AI to generate values (`true`/`false`)

        - **source** (optional): `MERCHANT` or `GOLD_STANDARD`

        - **guideline_reason** (optional): Guidance for AI enrichment

        '
      operationId: importAttributes
      parameters:
      - $ref: '#/components/parameters/DomainHeader'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV file containing attribute definitions.
                name:
                  type: string
                  description: Human-friendly import name.
                  example: Spring attributes import
      responses:
        '202':
          description: Import accepted for asynchronous processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeImportAcceptedResponse'
              example:
                import_id: e2716438-b763-4be8-82d2-36abe0cb92b1
                name: attribute_test.csv
                status: PENDING
                total_rows: 36
                processed_rows: 0
                created_count: 0
                updated_count: 0
                skipped_count: 0
                failed_count: 0
                input_filename: attribute_test.csv
                input_file_url: null
                error_file_url: null
                error_message: null
                errors: []
                started_at: null
                completed_at: null
                created_at: '2026-03-12T18:04:03.879876Z'
        '400':
          description: Bad request - invalid CSV or missing file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorized - missing or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
      tags:
      - Attributes
      security:
      - authorization: []
    servers:
    - url: https://commerceos.aiagents.fabric.inc/api
      description: Production API
  /v2/attributes/import/{import_id}:
    get:
      summary: Get Attribute Import Status
      description: Retrieve the current status and results of an attribute import created using `POST /v2/attributes/import`.
      operationId: getAttributeImportStatus
      parameters:
      - $ref: '#/components/parameters/DomainHeader'
      - name: import_id
        in: path
        required: true
        description: Import ID returned from `POST /v2/attributes/import`.
        schema:
          type: string
          format: uuid
          example: e2716438-b763-4be8-82d2-36abe0cb92b1
      responses:
        '200':
          description: Import status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeImportStatusResponse'
              example:
                import_id: e2716438-b763-4be8-82d2-36abe0cb92b1
                name: attribute_test.csv
                status: COMPLETED
                total_rows: 36
                processed_rows: 36
                created_count: 35
                updated_count: 0
                skipped_count: 0
                failed_count: 1
                input_filename: attribute_test.csv
                input_file_url: https://example.com/input.csv
                error_file_url: https://example.com/errors.csv
                error_message: null
                errors:
                - 'Row 35: invalid data_type ''BOOLREAN'''
                started_at: '2026-03-12T18:04:03.998437Z'
                completed_at: '2026-03-12T18:04:04.724584Z'
                created_at: '2026-03-12T18:04:03.879876Z'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '404':
          description: Import not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorResponse'
      tags:
      - Attributes
      security:
      - authorization: []
    servers:
    - url: https://commerceos.aiagents.fabric.inc/api
      description: Production API
components:
  schemas:
    ServerError:
      type: object
      properties:
        code:
          description: Error code
          type: string
          example: 500
        message:
          description: Human-readable error description
          type: string
          example: An internal error occurred. If the issue persists please contact support@fabric.inc.
    WorkflowAttributes:
      type: object
      properties: {}
    AttributeGroupTypeResponse:
      type: object
      properties:
        _id:
          description: A 24-character system-generated ID, for internal use
          example: 6259ec8defc2116dd6c0f3fc
          type: string
        attributeGroupId:
          description: A 24-character system-generated ID of attribute group
          example: 6259ec8d006b0d00092b3189
          type: string
        attributeId:
          description: A 24-character system-generated attribute ID
          example: 6245f16d11ae770009f19292
          type: string
        isEditable:
          type: boolean
          description: 'true: Attribute is editable <br /> false: Attribute is non-editable'
        createdOn:
          description: Time of attribute creation (UTC format)
          example: '2022-04-15T22:07:09.932Z'
          type: string
        modifiedOn:
          description: Time when attribute was last updated (UTC format)
          example: '2022-04-15T22:10:05.444Z'
          type: string
        order:
          description: Order of items within the attribute group
          example: 0
          type: number
        attribute:
          type: array
          items:
            type: object
            properties:
              _id:
                description: A 24-character system-generated attribute ID
                example: 6259ec8defc2116dd6c0f3fc
                type: string
              description:
                description: Accurate description of attribute and what it represents
                example: Item weight, in KG.
                type: string
              formulaManuallyOverWritten:
                type: boolean
                example: false
                description: 'true: Formula can be manually overwritten <br /> false: Formula cannot be manually overwritten'
              formula:
                description: Formula for the item attribute
                example: null
                type: string
              type:
                description: Attribute type
                example: TEXT
                type: string
              name:
                description: Attribute name
                example: weight
                type: string
              textSubType:
                description: Conditionally required sub-type for `TEXT` attribute type
                example: SMALL_TEXT
                type: string
              attributeValidationId:
                example: 624d92f8caa34e0009b5d849
                type: string
                description: Attribute validation ID
              modifiedBy:
                description: User ID that modified item attribute
                example: 60aad2c835c5fb000885f679
                type: string
              createdOn:
                description: Time of attribute creation (UTC format)
                example: '2022-04-15T22:07:09.932Z'
                type: string
              modifiedOn:
                description: Time when the attribute was last modified (UTC format)
                example: '2022-04-15T22:10:05.444Z'
                type: string
    AttributeMappingModify:
      type: object
      properties:
        mappings:
          type: array
          items:
            type: object
            properties:
              attributeId:
                description: Attribute ID
                type: string
                example: ATTR1234
              mapping:
                description: Attribute mapping
                type: string
                example: SKU
              name:
                description: Name of the attribute mapping
                type: string
              description:
                description: Description of the attribute mapping
                type: string
                example: Item SKU
              validation:
                $ref: '#/components/schemas/AttributeValidation'
              required:
                description: 'true: Mapping is mandatory <br /> false: Mapping is optional'
                type: boolean
    BulkAttributeResponse:
      type: object
      properties:
        attributes:
          type: object
          properties:
            success:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    example: 622932439c73c975335cb654
                    description: A 24-character system-generated attribute ID
                  name:
                    type: string
                    example: name
                    description: Attribute name
                  message:
                    type: string
                    description: Success message
                    example: Attribute created successfully
            failed:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: ITEM_ATTRIBUTE_VALUE_IS_INVALID
                    description: Failure reason as stored backend
                  errors:
                    type: array
                    items:
                      type: string
                      example:
                      - Attribute value is invalid
                      - Attribute value not found
                      description: Human-readable failure reasons
    AttributeGroupSearchResponse:
      type: object
      properties:
        totalSize:
          description: Total number of records (attribute group)
          example: 7
          type: number
        pageSize:
          description: Number of records (attribute group) per page
          example: 10
          type: number
        pages:
          description: Number of pages for the given `pageSize`
          example: 1
          type: number
        attributeGroups:
          type: array
          items:
            type: object
            properties:
              _id:
                description: A 24-character system-generated ID of the attribute group
                example: 6259ec8d006b0d00092b3189
                type: string
              description:
                description: Accurate description of the attribute and what it represents
                example: Item weight, in KG
                type: string
              type:
                description: Attribute group type
                example: COLLECTION
                type: string
                enum:
                - WORKFLOW
                - COLLECTION
              name:
                description: Attribute group name
                example: weight
                type: string
              priorityOrder:
                description: Priority order of attribute group
                example: 1
                type: number
              createdOn:
                description: Time of attribute group creation (UTC format)
                example: '2022-04-15T22:07:09.921Z'
                type: string
              modifiedOn:
                description: Time when attribute group was last modified (UTC format)
                example: '2022-04-15T22:10:05.427Z'
                type: string
              totalAttributes:
                description: Number of attributes in the attribute group
                example: 1
                type: number
              EditableAttributes:
                type: array
                items:
                  $ref: '#/components/schemas/AttributeGroupTypeResponse'
              ReadOnlyAttributes:
                type: array
                items:
                  $ref: '#/components/schemas/AttributeGroupTypeResponse'
              WorkflowAttributes:
                items:
                  description: Uses same response as AttributeGroupTypeResponse
                  $ref: '#/components/schemas/WorkflowAttributes'
              ImpactedAttributes:
                items:
                  description: Uses same response as AttributeGroupTypeResponse
                  $ref: '#/components/schemas/ImpactedAttributes'
    BulkAttributeRequest:
      type: array
      items:
        type: object
        required:
        - type
        - name
        - action
        properties:
          action:
            type: string
            enum:
            - CREATE
            - UPDATE
            - DELETE
            example: UPDATE
            description: 'Action type. <br /> **Note**: <br /> 1) Attribute ID is required only for `UPDATE` and `DELETE` actions (not for CREATE). <br /> 2) `CREATE` action replaces any existing category attribute with the same name.'
          id:
            description: A 24-character system-generated attribute ID
            example: 61ba11691a29d52cb2842541
            type: string
          name:
            description: Attribute name
            example: weight
            type: string
          description:
            description: Accurate description of the attribute and what it represents
            example: Item weight, in KG
            type: string
          type:
            description: Supported attribute types for the attribute
            example: INTEGER
            type: string
            enum:
            - TEXT
            - BOOLEAN
            - SERIAL
            - DECIMAL
            - INTEGER
            - DATETIME
            - OPTIONS
          textSubType:
            description: Conditionally required for `TEXT` attribute type
            example: HTML
            type: string
            enum:
            - SMALL_TEXT
            - TEXT_AREA
            - HTML
          serialStart:
            description: Conditionally required to indicate the starting value of `SERIAL` attribute type. When enabled, the subsequent attribute values increment by 1.
            example: 1000
            type: number
          optionsType:
            description: Conditionally required to indicate the selectable values for `OPTIONS` attribute type
            type: string
            example: DATETIME
            enum:
            - TEXT
            - BOOLEAN
            - DECIMAL
            - INTEGER
            - DATETIME
          format:
            description: Attribute format. Currently used only for `DATETIME` attribute type.
            type: string
            example: YYYY-MM-DD
          formula:
            description: 'JavaScript expression to dynamically compute the attribute value. The data type returned by this expression must match the attribute''s data type. <br /> **Note**: When this is provided, `validation` is ignored.'
            type: string
            example: '`${item.weightValue} ${item.weightUnit}`'
          validation:
            type: object
            properties:
              required:
                description: 'true: Attribute is mandatory <br /> false: Attribute is optional'
                type: boolean
              inheritable:
                description: 'true: Parent attributes inherited to children items <br /> false: Parent attributes not inherited to children items'
                type: boolean
                example: true
              inverse:
                description: 'true: Inverts existing validation (example - requires that the validation does not pass) <br /> false: Follows existing validation'
                type: boolean
              unique:
                description: 'true: Value is unique across all items or categories <br /> false: Value is not unique'
                type: boolean
              exact:
                description: Specified value must exactly match this value
                oneOf:
                - type: string
                - type: number
                - type: boolean
              attributeTypes:
                description: Attribute types
                type: array
                example:
                - Serial
                - Integer
                items:
                  type: string
                  enum:
                  - TEXT
                  - BOOLEAN
                  - SERIAL
                  - DECIMAL
                  - INTEGER
                  - ASSET
                  - DATETIME
              contains:
                description: Specified value must contain this string
                type: string
              range:
                description: Specified range of values must be between this min and/or max
                type: object
                properties:
                  min:
                    description: Specified value must be greater than or equal to this value
                    oneOf:
                    - type: string
                    - type: number
                  max:
                    description: Specified value must be less than or equal to this value
                    oneOf:
                    - type: string
                    - type: number
              formula:
                description: JavaScript expression to determine if the value matches
                type: string
                example: value < 10 || value > 20
              oneOf:
                description: Matches the value if it is one of these
                oneOf:
                - type: array
                  items:
                    type: string
                - type: array
                  items:
                    type: number
                - type: array
                  items:
                    type: boolean
    AttributeResponse:
      type: object
      properties:
        id:
          description: Attribute ID
          type: string
        statuses:
          description: For 'attribute modify request', the `PIM` statuses (if applicable). For 'attribute search request', the statuses defined by the `include.status` request parameter.
          type: array
          items:
            $ref: '#/components/schemas/StatusResponse'
        files:
          description: Array of file's associated with an item
          type: array
          items:
            $ref: '#/components/schemas/FileResponse'
        name:
          description: Attribute name
          type: string
        description:
          description: Attribute description
          type: string
        locales:
          type: array
          items:
            type: object
            properties:
              locale:
                description: Locale identifier
                type: string
                example: fr-ca
              name:
                description: Localized string value
                type: string
                example: Un Nom Français
        localizable:
          description: 'true: attribute can be localized <br /> false: attribute cannot be localized'
          type: boolean
        mapping:
          description: 'Attribute mapping. <br /> **Note**: Most attributes will not have a mapping, resulting in null value.'
          type:
          - string
          - 'null'
        type:
          description: Data type of the attribute
          type: string
          enum:
          - TEXT
          - BOOLEAN
          - SERIAL
          - DECIMAL
          - INTEGER
          - DATETIME
        serialStart:
          description: Conditionally required to indicate the starting value of `SERIAL` attribute type. When enabled, the subsequent attribute values increment by 1.
          type: number
        target:
          description: Indicates whether the attribute is for categories or items.
          type: string
          enum:
          - NODE
          - ITEM
        format:
          description: Attribute format. Currently used only for the attribute type `DATETIME`.
          type: string
          example: YYYY-MM-DD
        formula:
          description: 'JavaScript expression to dynamically  compute the attribute''s value. <br /> **Note**: The type returned must match the attribute''s type.'
          type: string
          example: value < 10 || value > 20
        validation:
          $ref: '#/components/schemas/AttributeValidation'
        createdOn:
          description: Time of attribute creation
          type: string
          format: date-time
        createdBy:
          description: ID that created the attribute
          type: string
          example: broma0
        modifiedOn:
          description: Time when the attribute was last modified
          type: string
          format: date-time
        modifiedBy:
          description: User ID that last modified the attribute
          type: string
          example: broma0
    AttributeMappingSearch:
      type: object
      required:
      - page
      - size
      properties:
        include:
          type: object
          properties:
            attribute:
              type: boolean
              description: 'true: include the `attribute` in the response; <br /> false: exclude `attribute` in the response'
        sort:
          $ref: '#/components/schemas/AttributeMappingSort'
        match:
          $ref: '#/components/schemas/AttributeMappingMatch'
   

# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-attributes-api-openapi.yml