Create a new cell specification with nested component/material data

Creates a new cell specification with nested component and material data.

Materials and components are automatically upserted based on uniqueness:

• Materials: unique on (organization_id, name, manufacturer)
• Components: unique on (organization_id, component_type, material_id, properties)

Example request body:

{
    "name": "NCM622/Graphite Coin Cell",
    "capacity": 0.002,
    "lower_voltage_cutoff": 2.5,
    "upper_voltage_cutoff": 4.2,
    "form_factor": "R2032",
    "anode": {
        "properties": {"diameter_mm": 15, "thickness_um": 23},
        "material": {"name": "Graphite", "manufacturer": "Customcells"}
    },
    "cathode": {
        "properties": {"diameter_mm": 14, "thickness_um": 22},
        "material": {
            "name": "NCM622",
            "definition": {"formula": "LiNi0.6Co0.2Mn0.2O2"}
        }
    }
}

Create a new cell specification with nested component/material data

cURL

curl --request POST \
  --url https://api.ionworks.com/cell_specifications \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "ratings": {
    "capacity": {
      "value": 123,
      "unit": "<string>"
    },
    "voltage_min": {
      "value": 123,
      "unit": "<string>"
    },
    "voltage_max": {
      "value": 123,
      "unit": "<string>"
    },
    "nominal_voltage": {
      "value": 123,
      "unit": "<string>"
    },
    "energy": {
      "value": 123,
      "unit": "<string>"
    },
    "energy_density_gravimetric": {
      "value": 123,
      "unit": "<string>"
    },
    "energy_density_volumetric": {
      "value": 123,
      "unit": "<string>"
    },
    "max_discharge_rate": {
      "value": 123,
      "unit": "<string>"
    },
    "max_charge_rate": {
      "value": 123,
      "unit": "<string>"
    }
  },
  "project_id": "<string>",
  "form_factor": "<string>",
  "manufacturer": "<string>",
  "properties": {},
  "source": {},
  "anode": {
    "material": {
      "name": "<string>",
      "definition": {},
      "manufacturer": "<string>",
      "product_id": "<string>"
    },
    "properties": {}
  },
  "cathode": {
    "material": {
      "name": "<string>",
      "definition": {},
      "manufacturer": "<string>",
      "product_id": "<string>"
    },
    "properties": {}
  },
  "electrolyte": {
    "material": {
      "name": "<string>",
      "definition": {},
      "manufacturer": "<string>",
      "product_id": "<string>"
    },
    "properties": {}
  },
  "separator": {
    "material": {
      "name": "<string>",
      "definition": {},
      "manufacturer": "<string>",
      "product_id": "<string>"
    },
    "properties": {}
  },
  "case": {
    "material": {
      "name": "<string>",
      "definition": {},
      "manufacturer": "<string>",
      "product_id": "<string>"
    },
    "properties": {}
  },
  "notes": "<string>"
}
'

201

{
  "name": "<string>",
  "ratings": {
    "capacity": {
      "value": 123,
      "unit": "<string>"
    },
    "voltage_min": {
      "value": 123,
      "unit": "<string>"
    },
    "voltage_max": {
      "value": 123,
      "unit": "<string>"
    },
    "nominal_voltage": {
      "value": 123,
      "unit": "<string>"
    },
    "energy": {
      "value": 123,
      "unit": "<string>"
    },
    "energy_density_gravimetric": {
      "value": 123,
      "unit": "<string>"
    },
    "energy_density_volumetric": {
      "value": 123,
      "unit": "<string>"
    },
    "max_discharge_rate": {
      "value": 123,
      "unit": "<string>"
    },
    "max_charge_rate": {
      "value": 123,
      "unit": "<string>"
    }
  },
  "id": "<string>",
  "organization_id": "<string>",
  "form_factor": "<string>",
  "manufacturer": "<string>",
  "anode_id": "<string>",
  "cathode_id": "<string>",
  "electrolyte_id": "<string>",
  "separator_id": "<string>",
  "case_id": "<string>",
  "properties": {},
  "source": {},
  "notes": "<string>",
  "created_by": "<string>",
  "created_by_email": "<string>",
  "instance_ids": [
    {}
  ],
  "anode": {
    "component_type": "cathode",
    "material_id": "<string>",
    "id": "<string>",
    "organization_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "properties": {},
    "material": {
      "name": "<string>",
      "id": "<string>",
      "organization_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "definition": {},
      "manufacturer": "<string>",
      "product_id": "<string>"
    }
  },
  "cathode": {
    "component_type": "cathode",
    "material_id": "<string>",
    "id": "<string>",
    "organization_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "properties": {},
    "material": {
      "name": "<string>",
      "id": "<string>",
      "organization_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "definition": {},
      "manufacturer": "<string>",
      "product_id": "<string>"
    }
  },
  "electrolyte": {
    "component_type": "cathode",
    "material_id": "<string>",
    "id": "<string>",
    "organization_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "properties": {},
    "material": {
      "name": "<string>",
      "id": "<string>",
      "organization_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "definition": {},
      "manufacturer": "<string>",
      "product_id": "<string>"
    }
  },
  "separator": {
    "component_type": "cathode",
    "material_id": "<string>",
    "id": "<string>",
    "organization_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "properties": {},
    "material": {
      "name": "<string>",
      "id": "<string>",
      "organization_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "definition": {},
      "manufacturer": "<string>",
      "product_id": "<string>"
    }
  },
  "case": {
    "component_type": "cathode",
    "material_id": "<string>",
    "id": "<string>",
    "organization_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "properties": {},
    "material": {
      "name": "<string>",
      "id": "<string>",
      "organization_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "definition": {},
      "manufacturer": "<string>",
      "product_id": "<string>"
    }
  }
}

Body

application/json

Model for creating a cell specification with nested component/material data.

Components and materials are upserted based on uniqueness constraints:

• Materials: unique on (organization_id, name, manufacturer, product_id)
• Components: unique on (organization_id, component_type, material_id, properties)

name · string · required

Name of the cell specification

ratings · Ratings · object · required

Electrical ratings from spec sheet

Show child attributes

project_id · string · required

Project to associate with

form_factor · string | null

Form factor (e.g., R2032, 18650, pouch)

manufacturer · string | null

Who assembled/manufactured the cell

properties · Properties · object

Non-electrical design properties (assembly_method, etc.)

source · Source · object

Source/provenance info: doi, license, publication_date, citation, creator_name, creator_orcid

anode · NestedComponentInput · object

Anode component with material

Show child attributes

cathode · NestedComponentInput · object

Cathode component with material

Show child attributes

electrolyte · NestedComponentInput · object

Electrolyte component with material

Show child attributes

separator · NestedComponentInput · object

Separator component with material

Show child attributes

case · NestedComponentInput · object

Case component with material

Show child attributes

notes · string | null

Optional notes about the cell specification

Response

201

application/json

Successful Response

Cell specification with nested component information.

name · string · required

Name of the cell specification

ratings · Ratings · object · required

Electrical ratings from the spec sheet / design targets (rated capacity, voltage min/max, optional nominal voltage, energy, energy densities, max charge/discharge C-rates). See :class:Ratings.

Show child attributes

id · string · required

Unique identifier for the cell specification

organization_id · string · required

Organization ID of the cell specification

form_factor · string | null

Physical form factor. Common values: '18650', '21700', 'R2032' (coin cell), 'pouch', 'prismatic', 'cylindrical'.

manufacturer · string | null

Who assembled/manufactured the cell

anode_id · string | null

ID of the anode component

cathode_id · string | null

ID of the cathode component

electrolyte_id · string | null

ID of the electrolyte component

separator_id · string | null

ID of the separator component

case_id · string | null

ID of the case component

properties · Properties · object

Other design-level properties that are not electrical ratings and not tied to a specific component — e.g. assembly method, overall cell dimensions, mass, target thickness. Numeric values must use the Quantity format ({'value': ..., 'unit': ...}).

source · Source · object

Provenance of the design. Typical keys: 'doi', 'citation', 'publication_date' (ISO 8601), 'license', 'creator_name', 'creator_orcid'. Lives on the specification (not the instance) because it describes the published design.

notes · string | null

Free-text notes about the cell specification

created_by · string | null

User ID of the user who created this specification

created_by_email · string | null

Email of the user who created this specification

instance_ids · Instance Ids · object[] | null

List of instance IDs associated with the cell specification

anode · CellComponentWithMaterial · object

Anode component with material

Show child attributes

cathode · CellComponentWithMaterial · object

Cathode component with material

Show child attributes

electrolyte · CellComponentWithMaterial · object

Electrolyte component with material

Show child attributes

separator · CellComponentWithMaterial · object

Separator component with material

Show child attributes

case · CellComponentWithMaterial · object

Case component with material

Show child attributes