API v1 preview

# The Model object

A reusable design: readiness status, inspection results, measurements and Model repair.

## Fields

`file_revision` integer · optional

Current customer file revision. Size and name changes do not create file revisions.

Minimum: 1

`file_repair` integer | null · optional

Current model repair of file_revision (1 and 1 is revision 1.1), or null.

Minimum: 1

`id` string · required

Immutable design identifier. File replacements append a customer file revision while preserving this ID and previous sources.

Min length: 11 · Max length: 11

`source` object · required

Reference to an uploaded geometry file and its supporting assets. One file can back multiple models in the same account. Set print size explicitly using longest_dimension_mm.

**source fields**

`file_id` string · required

Unique, server-generated file ID. Treat it as an opaque reference.

Min length: 37 · Max length: 37

`name` string · optional

Optional customer-supplied label. Unicode category C characters, including control and format characters, are rejected.

`external_id` string · optional

Optional identifier from your system. Not unique and does not deduplicate requests; filter by external_id when listing models.

`created_at` string (date-time) · required

When registration occurred; immutable. UTC RFC 3339 timestamp with six fractional-second digits (microseconds).

`updated_at` string (date-time) · required

Last persisted model update, including processing, readiness, preview and price changes. Use with updated_since to sync. Reading the model does not change this timestamp. Models have no time-based expiry. UTC RFC 3339 timestamp with six fractional-second digits (microseconds).

`status` string · required

Public readiness. ready: CalculatePrices, quotes and orders accept the model at its saved size, including any required Model repair price. processing: inspection, measurements or the repair estimate are still running. action_required: processing finished but the model cannot be priced; status_reasons says why and how to recover. failed: processing failed; replace the file. Poll until status is not processing, or subscribe to model.ready.

Allowed values: processing, ready, action_required, failed

`status_reasons` array · required

Why the model is not ready, in check order. Empty when ready.

**status_reasons item fields**

`code` string · required

Why the model is not ready. A failed model reports its processing error code.

Allowed values: inspection_pending, measurements_pending, repair_estimate_pending, measurements_unavailable, volume_unavailable, invalid_model_package, unreadable_model, missing_required_assets, unsupported_format, unsupported_model_features, invalid_geometry, processing_limit_exceeded, processing_timeout, inspection_unavailable, processing_failed, storage_unavailable

`message` string · required

Human-readable explanation; not a stable identifier.

`preview` object | null · required

Independent preview progress and seven image URLs when ready. Null for older models without a preview job or when temporary signing failure prevents safe delivery; other model fields remain available. Inspection does not wait for previews; repair cost estimation consumes all seven images or its documented fallback.

**preview fields**

At least one of these conditions applies:

**pending / processing / ready / failed**

`status` string · required

pending waits for normalization or rendering; processing renders images; ready makes all seven available; failed has an error. Poll GetModel with backoff until ready or failed.

Allowed values: pending, processing, ready, failed

`default_view` string · optional

Recommended image for cards and thumbnails. Present only when ready.

Always: `"angled"`

`expires_at` string (date-time) · optional

Earliest expiry of all preview URLs, at most 15 minutes after retrieval. Retrieve the model for fresh URLs. Issued URLs can remain usable until expiry after permission removal or model deletion.

`images` object · optional

Original transparent PNGs. Present only when ready. All seven source views are published together.

**images fields**

`angled` string (uri) · required

Camera at [1, 0.8, 1], looking toward the model center, with +Y up. Default view.

`front` string (uri) · required

Camera on +Z, +Y up.

`back` string (uri) · required

Camera on -Z, +Y up.

`left` string (uri) · required

Camera on -X, +Y up.

`right` string (uri) · required

Camera on +X, +Y up.

`top` string (uri) · required

Camera on +Y, -Z up.

`bottom` string (uri) · required

Camera on -Y, +Z up.

`error` object · optional

Preview generation failure; other model results remain usable.

[Error object](https://ottomfg.com/docs/error-object.md)

`thumbnails` object · optional

Transparent 384 by 384 pixel WebP images for compact views. Present only when ready. Each missing variant uses its source PNG URL.

**thumbnails fields**

`angled` string (uri) · required

Camera at [1, 0.8, 1], looking toward the model center, with +Y up. Default view.

`front` string (uri) · required

Camera on +Z, +Y up.

`back` string (uri) · required

Camera on -Z, +Y up.

`left` string (uri) · required

Camera on -X, +Y up.

`right` string (uri) · required

Camera on +X, +Y up.

`top` string (uri) · required

Camera on +Y, -Z up.

`bottom` string (uri) · required

Camera on -Y, +Z up.

`display` object · optional

Transparent 1024 by 1024 pixel WebP images for larger views. Present only when ready. Each missing variant uses its source PNG URL.

**display fields**

`angled` string (uri) · required

Camera at [1, 0.8, 1], looking toward the model center, with +Y up. Default view.

`front` string (uri) · required

Camera on +Z, +Y up.

`back` string (uri) · required

Camera on -Z, +Y up.

`left` string (uri) · required

Camera on -X, +Y up.

`right` string (uri) · required

Camera on +X, +Y up.

`top` string (uri) · required

Camera on +Y, -Z up.

`bottom` string (uri) · required

Camera on -Y, +Z up.

**null**

null

`metadata` object · optional

Optional customer key/value strings. Up to 50 keys, each 1–40 characters; values up to 500 characters. Unicode category C characters (including control and format characters) are rejected in keys and values. No secrets. Not interpreted for pricing, permissions or deduplication.

`longest_dimension_mm` number · required

Default print size and inspection reference size, in millimeters. Pricing items can select another size without changing this model or existing cart/order items.

Minimum: 30 · Maximum: 200

`mesh_check` object · required

Execution status, independent of the result. Successful checks may find defects or incomplete categories. The input geometry is not automatically repaired.

**mesh_check fields**

`status` string · required

Allowed values: pending, processing, completed, failed

`warnings` array · optional

Non-blocking appearance warnings. Missing materials use neutral gray; missing or unreadable textures use the material base color. Original uploads remain unchanged.

**warnings item fields**

`code` string · required

Allowed values: appearance_fallback

`message` string · required

`result` object · conditional

**result fields**

`passed` boolean | null · required

False: a supported check found a defect. True: all three supported primary checks completed and found none. Null: no defect established, but one or more primary checks are incomplete. This is not printability or manufacturing approval.

`incomplete_checks` array · required

Supported checks that did not finish completely. A known positive count can coexist with incomplete checks.

**incomplete_checks item fields**

string

Allowed values: inverted_normals, bad_edges, planar_holes

`inverted_normals` integer | null · required

Inverted triangle count. Null means unavailable, never zero.

Minimum: 0

`bad_edges` integer | null · required

Unpaired directed edge incidences; one geometric edge can contribute more than one. Null means unavailable, never zero.

Minimum: 0

`planar_holes` integer | null · required

Detected planar hole contours. Null means unavailable, never zero.

Minimum: 0

`shells` integer | null · required

Number of shared-edge connected components. Faces joined by an edge belong to the same component, even at non-manifold or reversed edges. Vertex-only contact does not join components. Multiple components are allowed. Null means unavailable.

Minimum: 0

`near_bad_edges` integer | null · required

Measured Magics count, or null when unavailable.

Minimum: 0

`noise_shells` integer | null · required

Measured Magics count, or null when unavailable.

Minimum: 0

`error` object · conditional

Processing failure included in a successful model lookup (HTTP 200). Correct source problems by uploading a new file and replacing the existing model's source, or by creating a separate model. For persistent service failures, contact support with the model ID. A terminally failed model can retry with PATCH at the same print size and If-Match; this queues a new processing revision without uploading again. Completed evidence may remain visible, but manufacturing_estimate is unavailable and pricing/quotes return pricing_unavailable while failed. Late inspection results do not clear this model-level error or emit a completion event.

**error fields**

`code` string · required

Allowed values: invalid_model_package, unreadable_model, missing_required_assets, unsupported_format, unsupported_model_features, invalid_geometry, processing_limit_exceeded, processing_timeout, inspection_unavailable, processing_failed, storage_unavailable

`message` string · required

Recovery instructions. Do not branch on message text.

Exactly one of these conditions applies:

**pending / processing**

Absent fields: result, error.

`status` string · required

Allowed values: pending, processing

**completed**

Required fields: result.

Absent fields: error.

`status` string · required

Always: `"completed"`

**failed**

Required fields: error.

Absent fields: result.

`status` string · required

Always: `"failed"`

`print_check` object · required

Mesh integrity assessment at longest_dimension_mm. Printable means a completed inspection with zero inverted normals, bad edges and planar holes. Hard mesh defects or an inspection time budget failure require repair. Missing, incomplete or failed analysis is not a pass. This assessment does not authorize an order.

**print_check fields**

`status` string · required

Allowed values: pending, processing, completed, failed

`longest_dimension_mm` number · conditional

Minimum: 30 · Maximum: 200

`waiting_for` array · optional

**waiting_for item fields**

string

Allowed values: mesh_check

`result` object · conditional

**result fields**

`passed` boolean · required

Allowed values: true, false

`decision` string · required

Allowed values: printable, repair_required

`blocking_mesh_checks` array · required

**blocking_mesh_checks item fields**

string

Allowed values: inverted_normals, bad_edges, planar_holes

`incomplete_mesh_checks` array · required

**incomplete_mesh_checks item fields**

string

Allowed values: inverted_normals, bad_edges, planar_holes

`risks` array · required

**risks item fields**

`severity` string · required

Allowed values: warning, high

`region_ids` array · required

Stable IDs within this assessment. Empty for whole-model or hard mesh issues.

**region_ids item fields**

string

`message` string · required

Min length: 1 · Max length: 1000

Exactly one of these conditions applies:

**object**

`passed` boolean · required

Always: `true`

`decision` string · required

Always: `"printable"`

**object**

`passed` boolean · required

Always: `false`

`decision` string · required

Always: `"repair_required"`

`error` object · conditional

**error fields**

`code` string · required

Always: `"printability_unavailable"`

`message` string · required

Exactly one of these conditions applies:

**pending / processing**

Absent fields: result, error.

`status` string · required

Allowed values: pending, processing

**completed**

Required fields: longest_dimension_mm, result.

Absent fields: waiting_for, error.

`status` string · required

Always: `"completed"`

**failed**

Required fields: longest_dimension_mm, error.

Absent fields: waiting_for, result.

`status` string · required

Always: `"failed"`

`repair` object · required

Model repair decided by the server. It applies when mesh inspection fails, when the account requested repair for this file revision, or when a paid order already covers the revision. A model that passes inspection prints as uploaded.

[Repair object](https://ottomfg.com/docs/repair-object.md)

`progress` object · optional

**progress fields**

`stage` string · required

Current inspection progress. inspection_completed and failed end polling for inspection; the overall model status can still be processing.

Allowed values: queued, preparing, inspecting, resizing, inspection_completed, failed

`volume` object | null · optional

Volume at the default print size in cubic millimeters, rounded to at most three decimal places. Null when unavailable.

**volume fields**

`value_mm3` number · required

Cubic millimeters at the selected size, rounded to at most three decimal places. Holes and inconsistent geometry can affect estimate accuracy.

Minimum: 0

`status` string · required

estimated: approximate measurement; confirmed: validated measurement. Currently returns estimated.

Allowed values: estimated, confirmed

`estimated_weight_g` number | null · optional

Estimated model material weight at the default print size, in grams, rounded to at most three decimal places. Excludes support material. Null when unavailable.

Minimum: 0

`orders` object · optional

Current order history for this model in its owning account. Includes all order statuses and revisions; count is distinct orders, not printed models or line items. Latest uses creation time then ID. Historical idempotent registration replays may omit this field.

**orders fields**

`count` integer · required

Minimum: 0

`latest_order_id` string | null · required

`manufacturing_estimate` object · optional

Independent manufacturing component at the default print size; excludes repair, shipping and tax. Provisional, never checkout approval. Uses settled account rates when available; final pricing settles discounts. Poll models while pending even after inspection completes. Terminally failed models return unavailable even if measurement evidence was already completed. Retry the failed model with PATCH at the same size, or correct and replace its source.

**manufacturing_estimate fields**

`status` string · required

Allowed values: pending, unavailable, provisional

`currency` string · conditional

Always: `"usd"`

`unit_price` integer · conditional

Cents per printed copy; repair excluded.

Minimum: 0

`longest_dimension_mm` number · conditional

Minimum: 30 · Maximum: 200

`pricing_version` string · conditional

`repair_cost_included` boolean · conditional

Always: `false`

Exactly one of these conditions applies:

**pending / unavailable**

Absent fields: currency, unit_price, longest_dimension_mm, pricing_version, repair_cost_included.

`status` string · required

Allowed values: pending, unavailable

**provisional**

Required fields: currency, unit_price, longest_dimension_mm, pricing_version, repair_cost_included.

`status` string · required

Always: `"provisional"`

`error` object · optional

Terminal preparation failure. Completed inspection and pricing evidence remain available, but this model cannot be quoted until preparation succeeds.

**error fields**

`code` string · required

Allowed values: invalid_model_package, unreadable_model, missing_required_assets, unsupported_format, unsupported_model_features, invalid_geometry, processing_limit_exceeded, processing_timeout, inspection_unavailable, processing_failed, storage_unavailable

`message` string · required

Recovery instructions. Do not branch on message text.

## Returned by

- [Create a model](https://ottomfg.com/docs/create-model.md)
- [List models](https://ottomfg.com/docs/list-models.md)
- [Get a model](https://ottomfg.com/docs/get-model.md)
- [Update a model](https://ottomfg.com/docs/update-model.md)
- [Replace a model file](https://ottomfg.com/docs/replace-model-file.md)

Example

JSON

```
{
  "id": "MD-739YQ549",
  "source": {
    "file_id": "file_6c82bd3e319b4bb099310d54a761879e"
  },
  "name": "Wedding figurine",
  "external_id": "design-123",
  "created_at": "2026-09-18T18:00:00.000000Z",
  "updated_at": "2026-09-18T18:00:00.000000Z",
  "status": "processing",
  "status_reasons": [
    {
      "code": "inspection_pending",
      "message": "Mesh inspection is running."
    }
  ],
  "preview": {
    "status": "pending"
  },
  "longest_dimension_mm": 100,
  "mesh_check": {
    "status": "pending"
  },
  "print_check": {
    "status": "pending"
  },
  "repair": {
    "required": false,
    "applied": false,
    "reason": null,
    "status": "not_applied",
    "fee": 0,
    "covered_by_order_id": null
  },
  "progress": {
    "stage": "queued"
  },
  "volume": null,
  "estimated_weight_g": null
}
```

API v1 preview

Source: https://ottomfg.com/docs/model-object