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 return the same scalarcut.factory_bom.v1.1 document for the same project.

Endpoint

GET /v1/tiling/factory-bom

The endpoint is a server-to-server GET on the Scalarcut embed host. An authenticated enterprise integration requests the Factory MBOM for one of its own projects by scene_id or project_id.

Authentication

Send your Factory MBOM Enterprise Key as a header:

Header Value
X-Enterprise-Key Your Factory MBOM Enterprise Key (sc_bom_…). Required.

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. Selects the project by scene id.
project_id integer Optional. Selects the project by project id.

The request is scoped to the enterprise identified by the key. Until live scene retrieval ships, the endpoint returns the sample document for any id; the ids you send are recorded in the usage event for metering and will select the real project once retrieval is live.

The sample document

For integrator trials, documentation examples, and the Try MBOM API panel, the endpoint also serves a public sample document — the garage fixture. It is sample data and conforms to the same scalarcut.factory_bom.v1.1 schema; it is not evidence that live project retrieval is unavailable.

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_bom_…" \
  -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. { "message": "Unauthorized" }
403 Origin/Referer not on the enterprise allowlist. { "message": "Forbidden" }
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.

{}