API Endpoint Reference / Materials

Upsert an organization catalog filament by partner external id

POST https://api.printhiv3d.com/v1/filament-catalog

Operation ID upsertCatalogFilament. Requires the control API key scope.

Request body

Content type application/json.

FieldTypeRequiredDescription
externalIdstringYes
brandstringYes
materialstringYes
colorNamestringYes
colorHexstringNo
hexstringNo
skustringYes
replacementFilamentIdstring | nullNo
bambuFilamentIdstringNoBambu filament ID of the stock profile this color slices with, such as GFG02. It must be in the bundled stock catalog and accept the color's material type. Omit it to take the stock default for the material type. Hive stores the link on every upsert, so an upsert that omits it selects the default again. The link changes how a plate slices and how the color assigns to a printer only for an organization with the hiveslice_loaded_filament_profiles flag, which stays off until the runtime is qualified.

Responses

StatusDescription
200Default Response

200 response fields

FieldTypeRequiredDescription
iduuidYes
namestringNo
brandstring | nullNo
material_typestringNo
categorystringNo
skustring | nullNo
colorstring | nullNo
colorsstring[]No
colorNamestring | nullNo
bambuFilamentIdstring | nullNoBambu filament ID of the stock profile this color is linked to, or null when it has no link: a color saved before the link existed, with a material type the stock catalog does not name, or while the stock profile had no usable database row. The link changes slicing and assignment only for an organization with the hiveslice_loaded_filament_profiles flag.
diameternumber | nullNo
organization_iduuid | nullNo
import_source_product_idstring | nullNo
created_atstring | nullNo
updated_atstring | nullNo

Example 200 response

{
  "id": "9c2e7b4a-1d8f-4a63-8f5b-6e0d3a9c7b21",
  "name": "Bambu Lab PLA Basic Jade White",
  "brand": "Bambu Lab",
  "material_type": "PLA",
  "category": "filament",
  "sku": "PLA-BASIC-JADE-WHITE",
  "color": "#FFFFFF",
  "colors": [
    "#FFFFFF"
  ],
  "colorName": "Jade White",
  "bambuFilamentId": "GFA00",
  "diameter": 1.75,
  "organization_id": "3b9e4d71-0c2f-4a58-8e6d-91f2a7c4b605",
  "import_source_product_id": "partner-catalog:pla-basic-jade-white",
  "created_at": "2026-11-04T18:00:00.000Z",
  "updated_at": "2026-11-04T18:00:00.000Z"
}