Factory MBOM

API Reference

The machine-to-machine Factory MBOM endpoint: authentication, headers, query parameters, and every response code. The planner export button produces the same schema.

Updated 27 October 2026

The primary way to get a Factory MBOM document is the Factory MBOM export button in the planner header, which downloads the JSON and CSV directly. This page documents the machine-to-machine path for ERP and MES middleware that pull the document itself.

Both paths produce the same scalarcut.factory_bom.v1.1 schema.

Endpoint

GET /v1/tiling/factory-bom

The endpoint is a server-to-server GET on the Scalarcut embed host. It serves a canonical sample for integrator trials; live scene/project pull is not shipped yet.

Authentication

Send one of the following with the request:

Header Value
X-Enterprise-Key Your Factory MBOM Enterprise Key (sc_wid_…). Preferred for ERP pullers.
X-Widget-Key Same key; accepted as an alias.
Authorization Bearer <token> — an embed widget HMAC token with claim typ=widget, issued after iframe load.

The Factory MBOM key purpose is distinct from the storefront Widget purpose. A key without the Factory MBOM purpose is rejected with 401.

Origin / Referer allowlist

  • An empty Origin/Referer is allowed, so ERP middleware that sends neither works without changes.
  • If Origin/Referer is present, it must match your enterprise allowlist (playground keys accept Scalarcut marketing origins only). A mismatch returns 403.

Query parameters

Parameter Type Meaning
scene_id integer Optional. Only garage id 121 is served in this release.
project_id integer Optional. Only garage id 121 is served in this release.

Any other id returns 404 { "message": "Layout not stored" }.

Conditional requests

The response carries an ETag (SHA-256 of the body). Send If-None-Match to skip re-downloading an unchanged document:

curl -sS -H "X-Enterprise-Key: sc_wid_…" \
  -H 'If-None-Match: "<etag>"' \
  "/v1/tiling/factory-bom"

A match returns 304 with no body.

Responses

Status Meaning Body
200 The Factory MBOM document. application/json (scalarcut.factory_bom.v1.1)
304 Not modified (If-None-Match matched). empty
401 Missing or invalid key / Bearer token. { "message": "Unauthorized" }
403 Origin/Referer not on the enterprise allowlist. { "message": "Forbidden" }
404 Layout not stored (non-garage scene/project id). { "message": "Layout not stored" }
429 Rate limit exceeded. —

The response headers include:

  • ETag — SHA-256 fingerprint of the body.
  • Cache-Control: private, no-store — do not cache between tenants.

Rate limiting

The endpoint is throttled at 30 requests per minute per client. Batch pulls should use If-None-Match to avoid re-downloading unchanged documents, and space polling rather than hitting the endpoint in a tight loop.

Usage metering

Each successful pull records an enterprise usage event (kind factory_bom) carrying the resolved scene_id/project_id and the authentication route. This feeds your plan's quota and reporting — it is not sent to your shoppers.

Try the MBOM API

Use the Try MBOM API button below this article to load the sample scalarcut.factory_bom.v1.1 response into a panel. Field semantics live in the Schema Reference.

Try the MBOM API

Load the sample scalarcut.factory_bom.v1.1 response into this panel.

{}