Endpoint reference

Interactive API explorer → Prefer to click around? The explorer renders every endpoint with live schemas, parameters, and ready-to-copy code samples.

The tables below are a quick scan of the routes and filters. For full request/response schemas, the interactive explorer is the richer view.

OpenAPI spec

The full machine-readable contract is served publicly (no auth, no shop data) at:

GET https://assemblified.com/api/v1/openapi.json

Point Postman, Insomnia, or any OpenAPI 3.1 client at that URL to generate a typed client or browse every parameter and response shape.

Endpoints

Method	Path	Scope	What it does
`GET`	`/api/v1/raw-materials`	read	List raw materials (filters: `search`, `usageFilter`, `originFilter`, `vendorFilter` (repeatable), `sortBy`, `sortOrder`, `page`, `pageSize`)
`GET`	`/api/v1/raw-materials/{variantId}`	read	One material; `?includeConnections=true` adds the BOMs + sub-assemblies that use it
`PATCH`	`/api/v1/raw-materials/{variantId}`	write	Edit fields — *virtual (`VMAT-`) materials only**
`GET`	`/api/v1/raw-materials/{variantId}/inventory`	read	Real per-location stock (`?locationIds=` repeatable) — live from Shopify for Shopify-linked materials
`PATCH`	`/api/v1/raw-materials/{variantId}/inventory`	write	Set per-location stock — *virtual (`VMAT-`) materials only**
`GET`	`/api/v1/openapi.json`	public	The machine-readable spec — no auth required

sortBy on the list accepts productName (default), variantName, or inventoryQuantity; an unrecognized value is ignored and the default productName ordering is used.

Shopify-managed materials are read-only in v1

Every GET works for both origins — Shopify-linked and virtual. The two PATCH endpoints accept only virtual materials (ids starting VMAT-). A PATCH against a numeric Shopify variant id returns 400 INVALID_INPUT with a “read-only in API v1” message, before anything is changed. This is deliberate: fields like name, sku, price, and cost on Shopify-linked materials are mirrored from Shopify, so a local API edit would be silently reverted by the next product update. Editing those belongs in the Shopify admin (or a future API version with true write-back).

Examples

List raw materials

curl -s -H "Authorization: Bearer $ASMK_TOKEN" \
  "https://assemblified.com/api/v1/raw-materials?originFilter=virtual&usageFilter=unused&pageSize=25"

{
  "data": {
    "items": [
      {
        "variantId": "VMAT-VAR-7f3d2c1a-9b4e-4c8d-a2f6-5e1b0d9c8a7f",
        "productId": "VMAT-PROD-2a9c8b7d-6e5f-4a3b-8c1d-0e9f8a7b6c5d",
        "inventoryItemId": "VMAT-INV-5c4d3e2f-1a0b-4c9d-8e7f-6a5b4c3d2e1f",
        "productName": "Oak board 20 mm",
        "variantName": "120 x 60 cm",
        "sku": "OAK-20-120",
        "vendor": "Holzwerk GmbH",
        "unit": "pcs",
        "unitCost": 12.5,
        "unitPrice": 0,
        "inventoryQuantity": 240,
        "isVirtual": true,
        "bomUsageCount": 0,
        "subAssemblyUsageCount": 0
        /* … specifications, imageUrl, isNonEssentialMaterial, weightValue,
           weightUnitId, productType, productCategory … */
      }
    ],
    "totalCount": 7, "page": 1, "pageSize": 25, "totalPages": 1,
    "availableVendors": ["Holzwerk GmbH", "Acme Supplies"]
  },
  "meta": { "requestId": "…", "apiVersion": "1.0" }
}

Get one material (with connections)

curl -s -H "Authorization: Bearer $ASMK_TOKEN" \
  "https://assemblified.com/api/v1/raw-materials/VMAT-VAR-7f3d2c1a-9b4e-4c8d-a2f6-5e1b0d9c8a7f?includeConnections=true"

Returns data.material (same fields as a list row, minus the usage counts) plus data.connections with boms and subAssemblies arrays — each entry names the BOM / sub-assembly, the quantity of this material it uses, and its location. Works for Shopify-linked materials too (numeric id in the path).

Update a virtual material

curl -s -X PATCH \
  -H "Authorization: Bearer $ASMK_TOKEN" -H "Content-Type: application/json" \
  -d '{ "unitCost": 13.1, "vendor": "Holzwerk GmbH" }' \
  "https://assemblified.com/api/v1/raw-materials/VMAT-VAR-7f3d2c1a-9b4e-4c8d-a2f6-5e1b0d9c8a7f"

Returns data.material — the full updated row. Only the fields you send change; the editable field list is in Conventions.

Read per-location inventory

curl -s -H "Authorization: Bearer $ASMK_TOKEN" \
  "https://assemblified.com/api/v1/raw-materials/VMAT-VAR-7f3d2c1a-9b4e-4c8d-a2f6-5e1b0d9c8a7f/inventory"

{
  "data": {
    "variantId": "VMAT-VAR-7f3d2c1a-9b4e-4c8d-a2f6-5e1b0d9c8a7f",
    "origin": "virtual",
    "totalAvailable": 240,
    "cachedQuantity": 240,
    "levels": [
      { "locationId": "74001236152", "available": 190 },
      { "locationId": "74001268920", "available": 50 }
    ]
  },
  "meta": { "requestId": "…", "apiVersion": "1.0" }
}

For a Shopify-linked material (numeric id), origin is "shopify", the levels are a live Shopify read, and each level row additionally carries a locationName. Virtual materials return locationId + available only — no locationName.

Set per-location inventory (virtual only)

curl -s -X PATCH \
  -H "Authorization: Bearer $ASMK_TOKEN" -H "Content-Type: application/json" \
  -d '{ "updates": [ { "locationId": "74001236152", "absolute": 200 } ] }' \
  "https://assemblified.com/api/v1/raw-materials/VMAT-VAR-7f3d2c1a-9b4e-4c8d-a2f6-5e1b0d9c8a7f/inventory"

Returns the per-row batch envelope (results / okCount / failedCount / skippedCount). Each row carries exactly one of absolute (retry-safe — prefer it) or delta; full body semantics in Conventions. Every adjustment is recorded in the material’s adjustment history.

Back to overview