API Endpoint Reference / Materials
Upsert an organization catalog filament by partner external id
POST https://api.printhiv3d.com/ v1/ filament-catalogOperation ID upsertCatalogFilament. Requires the control API key scope.
Request body
Content type application/json.
| Field | Type | Required | Description |
|---|---|---|---|
externalId | string | Yes | |
brand | string | Yes | |
material | string | Yes | |
colorName | string | Yes | |
colorHex | string | No | |
hex | string | No | |
sku | string | Yes | |
replacementFilamentId | string | null | No | |
bambuFilamentId | string | No | Bambu 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
| Status | Description |
|---|---|
200 | Default Response |
200 response fields
| Field | Type | Required | Description |
|---|---|---|---|
id | uuid | Yes | |
name | string | No | |
brand | string | null | No | |
material_type | string | No | |
category | string | No | |
sku | string | null | No | |
color | string | null | No | |
colors | string[] | No | |
colorName | string | null | No | |
bambuFilamentId | string | null | No | Bambu 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. |
diameter | number | null | No | |
organization_id | uuid | null | No | |
import_source_product_id | string | null | No | |
created_at | string | null | No | |
updated_at | string | null | No |
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"
}