MintModel (mintmodel, mintmodel_history)

packs:mintpress

JSON:API types: mintmodel (a concretised MintModel document) and mintmodel_history (one assignment of a MintModel to an asset). Both hang off an asset's node path and are populated by the MintModel render lane: every successful render — whether triggered by a generate-actions request or by the explicit mintmodels/generate endpoint — stores the concrete model, its derived step trees, and an assignment row (unless the asset's latest assignment already carries the same MintModel and step trees). Before the first render every index below honestly answers an empty collection, and the GUI's MintModel tab reads the asset show's mintmodel_valid / mintmodel_invalid_reason pair (see the node page) to say why.

Endpoints

Verb	Path	Behaviour
GET	<asset path>/mintmodel_history	The asset's assignment history, newest first. limit (default 100, 206 + meta.partial_response past it), filter[sorts][] over the serialized attributes, include=template_version,mintmodel. Non-assignment (diff) rows never appear.
GET	<asset path>/mintmodel_history/{id}	One assignment; default includes mintmodel, opschain_changes.
GET	<asset path>/mintmodels	The asset's distinct assigned MintModels, newest assignment first. ?version=… narrows to the MintModels that template version's concretise tasks generated; a version never assigned to the asset answers the named Unknown template version 422.
GET	<asset path>/mintmodels/{mintmodel_id}	One MintModel, resolved through the asset's history.
GET	<asset path>/mintmodels/generate	The concretisation trigger — reach it via the asset's links.mintmodels, never a hand-built path. Named 422s: Template required (non-asset), MintModel folder required (the pinned version has no MintModel), Generate actions request in flight, and the model-error Task already in progress… when a concretise task is already active. Otherwise records a MintModelConcretiseTask, answers 202 with the task (node_background_task shape), and dispatches a render-only job on the runner: a concretise always re-renders (a valid stored row never short-circuits it) and never runs the template-actions phase. Poll the task — success carries the stored mintmodel id; a render failure settles it as MintModel concretisation failed: <cause> with a customer-visible error:mint_model_concretise_task:concretise event.
POST	<asset path>/mintmodels/{old}/diff/{new}	Not yet served (answers 404) — the MintModel diff-tree compute.

All of them authorise read on the asset's path, 404-on-deny.

What makes a MintModel valid

A stored MintModel is valid for an asset when the asset_mintmodel_actions row keyed on the asset, its pinned template version's commit and the converged-properties key is a successful render (no cached generation error). The properties key is the SHA-256 of the asset's converged MintModel properties (the repository-committed document overlaid by mintpress.mintmodel_overrides and the mintpress subtree), so changing a property that feeds the render invalidates the stored MintModel just as repointing the template version to a commit whose MintModel/ folder differs does. A repoint to a commit whose MintModel/ tree is unchanged (an actions.rb-only commit, a floating repin) does not invalidate it: the next generation request reuses the stored render and materialises its row for the new commit (the reuse rule on opschain docs resources/template), so the asset reads valid again without a render. Validity gates templated change creation on MintModel-backed versions: an invalid MintModel refuses the change with a message naming the reason (never concretised, properties changed, template version changed, or a failed render), and regenerating via mintmodels/generate restores it.

mintmodel_history

Attributes: created_at, updated_at (microsecond timestamps). Relationships: mintmodel (with a related link to the node-path member route), opschain_changes (changes created from the assignment), template_version (the history record active when the row was recorded), parents (the owning asset's path nodes). Links: self (node-path member route). Index meta: authorisations.update, partial_response.

mintmodel

Attributes: data (the concretised document), sha256, created_at, updated_at, render_logs (key-sorted), phase_output. Relationships: mintmodel_history (the asset-scoped rows, diffs included). Links: self and parent_mintmodel_history (the history collection), present when a history row resolves the owning asset.

The v2 service — MintModelService

ListMintModelHistory (newest first), GetMintModel (the stored document with render_logs_json/phase_output_json) and GenerateMintModel — the v1 GET …/mintmodels/generate lane declared as the mutation it is, keeping the v1 validation messages verbatim and answering the accepted concretise task. See opschain docs api-v2.

Related pages

• opschain docs resources/node — the asset show's mintmodel_valid/mintmodel_invalid_reason pair and the mintmodels/mintmodel_history links.
• opschain docs resources/node_comparison — the per-side stored MintModel data in a node comparison.