> ## Documentation Index
> Fetch the complete documentation index at: https://developer.worldly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MSI Create Materials

## Introduction

This API endpoint allows for the creation of custom materials in the Higg MSI.

To create a custom material, the following base attributes are required:

* Name (open text field, must be unique within an MSI library)
* Category (user defined from the set of categories available in the MSI). See [MSI Get Material Categories](/api-reference/product-tools/msi-api-full/get-material-categories) for additional information.
* At least one base material (user defined from the set of base materials available in the MSI) See [MSI Get Base Materials](/api-reference/product-tools/msi-api-full/get-base-materials) for additional information.

An optional text field material code can be added as 'code'.  For example, this field can be used to store a PLM id. Note that the field is editable by users within MSI.

```json Example minimal material creation theme={null}
{
    "name": "My custom material",
    "code": "my PLM code",
    "category": "TX",
    "baseMaterials":[{
        "baseMaterialId": "FM002"
    }]
}
```

## Creating blends

Blends are based on % of material for 1kg of MSI material.  For example the code below represents an MSI material with 60% organic cotton, 40% polyester.  The % blend must equal 100%.

```json Example blended material creation theme={null}
{

    "name": "Organic/Poly Blend",
    "code": "my PLM code",
    "baseMaterials":[{
        "baseMaterialId": "TX0010",
        "blendPercentage": 60
    }, {
        "baseMaterialId": "TX0001",
        "blendPercentage": 40
    }],
      "category": "TX"
}
```

## Setting Yields

Optionally one or multiple yields can be sent for a material.  All materials in MSI are normalized to 1kg.  Yields provide conversions for the MSI 1kg material to a linear/volumetric unit. See [MSI Get Yield Options](/api-reference/product-tools/msi-api-full/get-yield-options) for additional information.

```json Example blend material with yield creation theme={null}
{
    "name": "Example MSI custom material",
    "code": "yield 2",
    "baseMaterials": [
        {
            "baseMaterialId": "FM002"
        }
    ],
    "yieldInfo": [
        {
            "type": "Yards (volumetric)",
            "width": 1,
            "widthUnit": "m",
            "thickness": 2,
            "thicknessUnit": "in",
            "densityVolumetric": 13,
            "densityVolumetricUnit": "kg/m3"
        }
    ],
    "category": "TX"
}
```

## Setting Base Material Processes

The stage process for a base material can be changed via the API using the `processId`.  For example, changing 'cotton, fiber' to 'cotton fiber, organic" in the raw material formation stage.  The processes must be available for the base material to change it. See [MSI Get Processes for Base Material](/api-reference/product-tools/msi-api-full/get-processes) for how to get a list of available processes and their IDs.

```json Example material creation with specific process theme={null}
{
    "name": "Test blend",
    "code": "xyz PLM code",
    "baseMaterials":[{
        "baseMaterialId": "FM002",
        "blendPercentage": 60,
        "processes": {
      	 "P001": "PR0804000648",
         "P002": "PR0804000331"
        }
    }, {
       "baseMaterialId": "TX0010",
       "blendPercentage": 40,
       "processes": {
       	"P006": "PR0804000543"
       }
   }],
      "category": "TX"
}
```

See [MSI Data Dictionary](/data-dictionary/msi#materialtrimpackage-metadata) for details about the parameters.


## OpenAPI

````yaml api-reference/openapi/msi-api.json POST /materials/create-limited-lcia
openapi: 3.0.0
info:
  title: msi-api
  version: 1.0.0
servers:
  - url: https://api-v2.production.higg.org/msi-api/v1
    description: Production
  - url: https://api-v2.demo.higg.org/msi-api/v1
    description: Demo
security:
  - sec0: []
    sec1: []
paths:
  /materials/create-limited-lcia:
    post:
      operationId: CreateMaterialLimitedLcia
      requestBody:
        $ref: '#/components/requestBodies/CreateMaterialApi'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MaterialEntityWithoutProcessLimited'
components:
  requestBodies:
    CreateMaterialApi:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateMaterialApi'
      required: true
  schemas:
    MaterialEntityWithoutProcessLimited:
      properties:
        version:
          $ref: '#/components/schemas/MaterialVersionWithoutProcessLimited'
        history:
          items:
            $ref: '#/components/schemas/MaterialVersionWithoutProcessLimited'
          type: array
          nullable: true
      required:
        - version
      type: object
      additionalProperties: false
    CreateMaterialApi:
      properties:
        name:
          type: string
        code:
          type: string
          nullable: true
        baseMaterials:
          items:
            $ref: '#/components/schemas/BaseMaterialProcessId'
          type: array
        yieldInfo:
          items:
            $ref: '#/components/schemas/YieldInfo'
          type: array
          nullable: true
        category:
          type: string
      required:
        - baseMaterials
        - category
        - name
      type: object
      additionalProperties: false
    MaterialVersionWithoutProcessLimited:
      properties:
        baseMaterials:
          items:
            $ref: '#/components/schemas/BaseMaterialEntityOptionalProcessLimited'
          type: array
      required:
        - baseMaterials
      type: object
      additionalProperties: false
    BaseMaterialProcessId:
      properties:
        blendPercentage:
          type: number
          format: double
          nullable: true
        baseMaterialId:
          type: string
        processes:
          properties: {}
          additionalProperties:
            type: string
          type: object
          nullable: true
      required:
        - baseMaterialId
      type: object
      additionalProperties: false
    YieldInfo:
      properties:
        type:
          $ref: '#/components/schemas/YieldType'
        width:
          type: number
          format: double
          nullable: true
        widthUnit:
          $ref: '#/components/schemas/YieldWidth'
        thickness:
          type: number
          format: double
          nullable: true
        thicknessUnit:
          $ref: '#/components/schemas/YieldThickness'
        densityLinear:
          type: number
          format: double
          nullable: true
        densityLinearUnit:
          $ref: '#/components/schemas/YieldDensityLinear'
        densityVolumetric:
          type: number
          format: double
          nullable: true
        densityVolumetricUnit:
          $ref: '#/components/schemas/YieldDensityVolumetric'
      required:
        - type
      type: object
      additionalProperties: false
    BaseMaterialEntityOptionalProcessLimited:
      properties:
        cycles:
          $ref: '#/components/schemas/MaterialCyclesLimited'
      type: object
      additionalProperties: false
    YieldType:
      enum:
        - Yards (linear)
        - Meters (linear)
        - Feet (linear)
        - Square Yards (linear)
        - Square Meters (linear)
        - Square Feet (linear)
        - Yards (volumetric)
        - Meters (volumetric)
        - Feet (volumetric)
        - Square Yards (volumetric)
        - Square Meters (volumetric)
        - Square Feet (volumetric)
      type: string
    YieldWidth:
      enum:
        - m
        - yd
        - in
        - cm
      type: string
    YieldThickness:
      enum:
        - in
        - cm
        - mm
      type: string
    YieldDensityLinear:
      enum:
        - g/m2
        - kg/m2
        - lb/yd2
        - oz/yd2
      type: string
    YieldDensityVolumetric:
      enum:
        - kg/m3
        - lb/ft3
      type: string
    MaterialCyclesLimited:
      properties: {}
      type: object
      additionalProperties:
        $ref: '#/components/schemas/MaterialCycleResultLimited'
    MaterialCycleResultLimited:
      properties:
        selected:
          items:
            $ref: '#/components/schemas/MaterialSelectedProcessLimited'
          type: array
        scores:
          $ref: '#/components/schemas/MsiImpactScoresLimited'
        detailProcesses:
          items:
            $ref: '#/components/schemas/DetailProcesses'
          type: array
          nullable: true
        stageName:
          type: string
          nullable: true
      required:
        - scores
        - selected
      type: object
      additionalProperties: false
    MaterialSelectedProcessLimited:
      properties:
        scores:
          $ref: '#/components/schemas/MsiImpactScoresLimited'
      required:
        - scores
      type: object
      additionalProperties: false
    MsiImpactScoresLimited:
      properties:
        impact:
          type: number
          format: double
        globalWarmingPct:
          type: number
          format: double
        eutrophicationPct:
          type: number
          format: double
        waterScarcityPct:
          type: number
          format: double
        abioticDepletionPct:
          type: number
          format: double
        chemistryPct:
          type: number
          format: double
        waterConsumptionPct:
          type: number
          format: double
        biogenicCarbonPct:
          type: number
          format: double
        globalWarmingPts:
          type: number
          format: double
        eutrophicationPts:
          type: number
          format: double
        waterScarcityPts:
          type: number
          format: double
        abioticDepletionPts:
          type: number
          format: double
        chemistryPts:
          type: number
          format: double
      required:
        - abioticDepletionPct
        - abioticDepletionPts
        - biogenicCarbonPct
        - chemistryPct
        - chemistryPts
        - eutrophicationPct
        - eutrophicationPts
        - globalWarmingPct
        - globalWarmingPts
        - impact
        - waterConsumptionPct
        - waterScarcityPct
        - waterScarcityPts
      type: object
      additionalProperties: false
    DetailProcesses:
      properties:
        name:
          type: string
        id:
          type: string
      required:
        - id
        - name
      type: object
      additionalProperties: false
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: x-api-key
    sec1:
      type: apiKey
      in: header
      name: x-developer-request-token

````