PrintHive

Filaments

Sync your filament catalog

The client methods need @printhive/api 0.3.0 or later. Create a client with a Control API key stored in PRINTHIVE_API_KEY. Send each partner record with a stable externalId.

import { PrintHive } from "@printhive/api";

if (!process.env.PRINTHIVE_API_KEY) {
  throw new Error("Set PRINTHIVE_API_KEY to a Control API key");
}
const hive = new PrintHive({ apiKey: process.env.PRINTHIVE_API_KEY });
const filament = await hive.filamentCatalog.upsert({
  externalId: "printie-blue", brand: "Printie", material: "PLA",
  colorName: "Blue", colorHex: "#0000FF", sku: "PLA-BLUE"
});
console.log(filament.id, filament.sku);
const page = await hive.filamentCatalog.list({ externalId: "printie-blue" });
const saved = await hive.filamentCatalog.get(filament.id);

Without the client, send the same record over HTTP with your key in the x-api-key header:

curl -X POST https://api.printhiv3d.com/v1/filament-catalog \
  -H "x-api-key: $PRINTHIVE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"externalId":"printie-blue","brand":"Printie","material":"PLA","colorName":"Blue","colorHex":"#0000FF","sku":"PLA-BLUE"}'

Repeat the upsert when a partner record changes. Repeated and concurrent calls reuse the same organization-owned Hive material id. The latest write replaces the catalog fields. Coordinate externalId values across integrations in the same organization. Hive trims surrounding whitespace from externalId and sku on writes and list filters. Both fields must remain nonempty.

hex is an alias for colorHex. If you supply both, their values must agree. replacementFilamentId is optional partner metadata; Hive does not resolve it as a material id. Keep the returned id and sku for subsequent lookups.

Endpoint reference

  • POST /v1/filament-catalog upserts one record and returns the material row with status 200. It requires Control scope.
  • GET /v1/filament-catalog accepts exact externalId and sku filters, limit (1 to 200, default 100), and offset (default 0). It returns materials andtotal, ordered by Hive id.
  • GET /v1/filament-catalog/:id returns one material row. Both read endpoints require Read scope. All endpoints enforce organization ownership.

Error reference

  • 400 invalid_catalog_input means an input fails the catalog contract.
  • 400 conflicting_color_hex means the hex aliases disagree. Schema validation also returns 400.
  • 403 API_KEY_SCOPE_REQUIRED means the key lacks the required scope.
  • 404 catalog_filament_not_found means the catalog row is unavailable in this organization.
  • 409 catalog_conflict means a uniqueness constraint rejected the write.
  • 500 catalog_store_failed means the catalog store operation failed.