Skip to main content
Developer menu
Partner previewv0

API reference

The endpoints a provider implements, and every schema in the v0 contract. Generated from the same source the platform validates against.

Base URL

Your service, at a base path of your choosing, which your team gives when it connects the model, for example https://models.example.com/shockai/v0.

Authentication. Every request carries a ShockAI-Signature header, signed with the platform's Ed25519 key. See Signing requests.

Endpoints

get/healthz

Say the service is up

Optional and unsigned: the only endpoint that is. The platform may call it before a signed request, to wake a host that sleeps when idle, and ignores the body. Answer 200 without reading anything a case holds.

Responses

  • 200Up.
get/manifest

Describe the model

Returns the model manifest. The platform reads it at registration and whenever the provider announces a new version; a manifest change never alters a run already made, because every result is pinned to the version that produced it.

Responses

  • 200ModelManifestThe manifest.
  • 401ApiErrorThe signature is missing, expired or wrong (authentication).
  • 500ApiErrorThe model failed (provider_error). The platform retries with backoff.
post/quote

Price a case

For models priced by quote. Returns a binding price for the case; the platform shows it to the user and, on acceptance, passes the quote id with the run. Quoting must not start work.

Request body

BlastCase

Responses

  • 200QuoteThe quote.
  • 400ApiErrorThe request is malformed or the case fails validation (invalid_request).
  • 401ApiErrorThe signature is missing, expired or wrong (authentication).
  • 422ApiErrorThe case is valid but the model cannot run it (unsupported_case), or cannot honour its consent terms (consent_refused). Final: the platform will not retry.
  • 429ApiErrorToo many requests (rate_limited). Send Retry-After; the platform backs off accordingly.
  • 500ApiErrorThe model failed (provider_error). The platform retries with backoff.
post/runs

Run the model on a case

Sync models answer within 30 seconds with the run succeeded and its result. Async models answer 202 with the run queued, then report through the run.* webhooks. The case contains only the inputs the manifest declares. The platform sends an Idempotency-Key; a repeated key must return the original run, not start another.

Parameters

  • Idempotency-Key (header)required · Stable across retries of the same run request.

Request body

RunRequest

Responses

  • 200RunSync: the finished run.
  • 202RunAsync: the accepted run.
  • 400ApiErrorThe request is malformed or the case fails validation (invalid_request).
  • 401ApiErrorThe signature is missing, expired or wrong (authentication).
  • 422ApiErrorThe case is valid but the model cannot run it (unsupported_case), or cannot honour its consent terms (consent_refused). Final: the platform will not retry.
  • 429ApiErrorToo many requests (rate_limited). Send Retry-After; the platform backs off accordingly.
  • 500ApiErrorThe model failed (provider_error). The platform retries with backoff.

Callback

post{$request.body#/callbackUrl}

Run status changed. WebhookEvent Signed with the same scheme, with your key: one of the signing.callbackKeys your manifest declares, over the callback URL exactly as given. Sign each delivery afresh, so a retry carries a current timestamp. Deliver at least once: retry with backoff until a 2xx, stop on a 4xx other than 408 or 429, and after a restart send again what was not delivered, under the same event id. The platform de-duplicates on the event id, and polls a run whose callback does not come. The callback URL is the run's own, so keep it private.

get/runs/{runId}

Get a run

The platform polls this as a fallback when a webhook is late. Results must stay retrievable for at least 24 hours after the run finishes.

Parameters

  • runId (path)required · The id the provider assigned in POST /runs.

Responses

  • 200RunThe run.
  • 401ApiErrorThe signature is missing, expired or wrong (authentication).
  • 404ApiErrorNo such run.
  • 500ApiErrorThe model failed (provider_error). The platform retries with backoff.
delete/runs/{runId}

Cancel a run

Best effort. A run that has already finished is returned unchanged. A cancelled run is not charged.

Parameters

  • runId (path)required · The id the provider assigned in POST /runs.

Responses

  • 200RunThe run, cancelled or already final.
  • 401ApiErrorThe signature is missing, expired or wrong (authentication).
  • 404ApiErrorNo such run.
  • 500ApiErrorThe model failed (provider_error). The platform retries with backoff.

Schemas

Top-level documents first, then the parts they are made of. Each is also published as a standalone JSON Schema.

Everything a model may read about one blast: design, as-built record, site, receivers, calibration and the question asked.

FieldTypeDescription
specVersionrequired"0.1"Version of the ShockAI Model API specification this document follows.
caseIdrequiredstringSHA-256 of the canonical case (see Canonical JSON) without caseId and createdAt, and without the uri of any BlobRef (any object carrying uri, sha256 and mediaType): its bytes are named by the hash, and a signed URL changes from run to run. Identical cases have identical ids, which is what makes results cacheable and reproducible.pattern ^sha256:[0-9a-f]{64}$
createdAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
coordinateSystemrequiredCoordinateSystemThe frame every position in the case is expressed in.
siterequiredobject
site.namestringmin length 1 · max length 200
site.domainsrequiredarray of RockDomainA zone of rock the site treats as one material. Holes name the domain they sit in.max 100 items
site.terrainBlobRefSurface model, when the provider needs one.
designrequiredDesignThe blast as designed.
asBuiltobjectPresent once the blast is drilled, loaded or fired. A pre-blast prediction leaves it out.
asBuilt.holesarray of AsBuiltHoleA hole as drilled and loaded. Fields left out are as designed.max 5000 items
asBuilt.firingFiringRecordWhat actually fired, and when.
receiversrequiredarray of ReceiverA place a prediction is wanted. It has a position, a resolved distance, or both.max 1000 items
calibrationCalibrationWhat the site has measured. This is what lets a kinematic model be calibrated rather than assumed.
measuredMeasuredPresent once the blast has fired and its records are in.
requestrequiredOutputRequestThe question the case asks.
consentrequiredConsentThe data owner’s terms for this case. A provider that cannot honour them must refuse the run.

What a model says about itself: capabilities, inputs, validity, execution, pricing and data handling.

FieldTypeDescription
specVersionrequired"0.1"Version of the ShockAI Model API specification this document follows.
idrequiredModelIdA model identifier in the form vendor/model, lower case, for example shockai/site-law.
versionrequiredstringA semantic version. A result is always pinned to the exact version that produced it.pattern ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$
namerequiredstringmin length 1 · max length 120
summaryrequiredstringmin length 1 · max length 500
vendorrequiredobject
vendor.namerequiredstringmin length 1 · max length 120
vendor.urlstring (uri)
methodrequiredModelMethodThe family of method, so a user can tell a fitted law from a simulation.
capabilitiesrequiredarray of CapabilityOne kind of output a model produces, and what it needs to produce it.min 1 items
executionrequiredobject
execution.moderequiredenumSync models answer POST /runs within the timeout; async models accept the run and call back.syncasync
execution.typicalSecondsrequirednumber> 0
execution.maxSecondsrequirednumberHard limit. A run still going at this point is cancelled.> 0 · ≤ 604800
pricingrequiredobject (model = "included") | object (model = "per_run") | object (model = "per_hole") | object (model = "quote") | object (model = "licence")How a run is charged.
pricing.modelrequiredmodel = "included""included"
pricing.modelrequiredmodel = "per_run""per_run"
pricing.currencyrequiredmodel = "per_run"stringmin length 3 · max length 3
pricing.unitAmountrequiredmodel = "per_run"integerMinor units, e.g. cents.≥ 0
pricing.modelrequiredmodel = "per_hole""per_hole"
pricing.currencyrequiredmodel = "per_hole"stringmin length 3 · max length 3
pricing.unitAmountrequiredmodel = "per_hole"integer≥ 0
pricing.modelrequiredmodel = "quote""quote"
pricing.modelrequiredmodel = "licence""licence"
pricing.notemodel = "licence"stringThe customer brings their own licence; the platform charges nothing on the run.max length 500
dataHandlingrequiredobject
dataHandling.regionsrequiredarray of stringWhere the case is processed, for example au, eu, us.min 1 items · each item min length 2, max length 40
dataHandling.retentionrequiredenumnone30dcontract
dataHandling.trainsOnCustomerDatarequiredboolean
documentationUrlstring (uri)
signingobjectHow the provider signs what it sends the platform. Required of an async model, whose results arrive as signed callbacks.
signing.callbackKeysrequiredarray of Ed25519JwkThe public keys your callbacks are signed with, as Ed25519 JWKs: one, or two while you rotate. The platform pins them when the model is connected, so a changed key is a new manifest version.min 1 items · max 3 items
buildobjectWhat is deployed behind this version.
build.hashrequiredstringIdentifies the code and weights answering, for example a commit or image digest. Every result reports it in provenance.buildHash.min length 1 · max length 128 · pattern ^[A-Za-z0-9._:+/@-]+$

What a model returns for one case.

FieldTypeDescription
specVersionrequired"0.1"Version of the ShockAI Model API specification this document follows.
caseIdrequiredstringA content hash: sha256: followed by 64 lower-case hex digits.pattern ^sha256:[0-9a-f]{64}$
outputsrequiredarray of OutputOne answer, discriminated by kind.max 5000 items
unavailablerequiredarray of UnavailableA requested output the model declined to produce, and why.max 5000 items
warningsrequiredarray of WarningSomething the model wants a person to see.max 500 items
provenancerequiredProvenanceWhere a result came from. Reports cite it; the platform uses it to score the model later.

The body of POST /runs.

FieldTypeDescription
caserequiredBlastCaseEverything a model may read about one blast: design, as-built record, site, receivers, calibration and the question asked.
quoteIdstringThe accepted quote, for models priced by quote.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
callbackUrlstring (uri)Where an async model sends its run.* events. Always HTTPS.

A model run, by status. Sync models return it succeeded from POST /runs; async models return it queued.

One of QueuedRun | RunningRun | SucceededRun | FailedRun | CancelledRun

A binding price for one case, valid until it expires.

FieldTypeDescription
idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
caseIdrequiredstringA content hash: sha256: followed by 64 lower-case hex digits.pattern ^sha256:[0-9a-f]{64}$
currencyrequiredstringmin length 3 · max length 3
amountrequiredintegerMinor units, e.g. cents.≥ 0
expiresAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
estimatedSecondsrequirednumber> 0

Every non-2xx response carries this body.

FieldTypeDescription
errorrequiredobject
error.typerequiredenumThe error family. unsupported_case and consent_refused are final; rate_limited, provider_error and timeout may be retried.invalid_requestunsupported_caseconsent_refusedauthenticationrate_limitedquote_expiredprovider_errortimeout
error.coderequiredstringA stable machine-readable code within the family.max length 80 · pattern ^[a-z][a-z0-9_]*$
error.messagerequiredstringmin length 1 · max length 1000
error.paramstringThe case field at fault, as a JSON Pointer.max length 200

Sent by an async provider to the run’s callbackUrl, signed like every request. type is run. and the state the run in data has reached.

One of

type = "run.running"
FieldTypeDescription
idrequiredstringUnique per event; deliveries are at-least-once, so de-duplicate on it.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
createdAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
typerequired"run.running"
datarequiredobject
data.runrequiredRunningRunStarted and not yet finished.
type = "run.succeeded"
FieldTypeDescription
idrequiredstringUnique per event; deliveries are at-least-once, so de-duplicate on it.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
createdAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
typerequired"run.succeeded"
datarequiredobject
data.runrequiredSucceededRunFinished with the model’s result.
type = "run.failed"
FieldTypeDescription
idrequiredstringUnique per event; deliveries are at-least-once, so de-duplicate on it.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
createdAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
typerequired"run.failed"
datarequiredobject
data.runrequiredFailedRunFinished without a result, and why.
type = "run.cancelled"
FieldTypeDescription
idrequiredstringUnique per event; deliveries are at-least-once, so de-duplicate on it.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
createdAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
typerequired"run.cancelled"
datarequiredobject
data.runrequiredCancelledRunStopped before it finished, by the platform or the provider.

ImportDocument

Download JSON Schema

Predictions made by another tool, brought onto the platform with their provenance.

FieldTypeDescription
specVersionrequired"0.1"Version of the ShockAI Model API specification this document follows.
blastrequiredobject
blast.platformBlastIdstringThe blast on the platform, when the importer knows it.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
blast.externalRefstringThe blast’s name or number in the source tool.min length 1 · max length 200
sourcerequiredobject
source.toolrequiredstringThe software that produced the results.min length 1 · max length 120
source.versionrequiredstringmin length 1 · max length 60
source.vendorstringmin length 1 · max length 120
source.methodModelMethodThe family of method, so a user can tell a fitted law from a simulation.
source.fileobject
source.file.namerequiredstringmin length 1 · max length 255
source.file.sha256requiredstringA content hash: sha256: followed by 64 lower-case hex digits.pattern ^sha256:[0-9a-f]{64}$
source.producedAtstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
outputsrequiredarray of ImportedOutputOne prediction made elsewhere, discriminated by kind: every kind a prediction case asks.min 1 items · max 5000 items
unavailablearray of UnavailableA requested output the model declined to produce, and why.max 5000 items · default []
warningsarray of WarningSomething the model wants a person to see.max 500 items · default []

Airblast

Predicted peak overpressure at a receiver.

FieldTypeDescription
kindrequired"airblast"
receiverIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
peakParequiredEstimatePeak overpressure, Pa. dB(L) = 20·log10(Pa / 20 µPa).
peakDbLEstimateThe same peak in dB(L), as the model computed it, so a limit in decibels is read without a round trip.
scaledDistancenumberThe cube-root scaled distance the prediction was made at.> 0
validityrequiredValidityHow far to trust one output.

AirblastLaw

A fitted airblast attenuation law on cube-root scaled distance.

FieldTypeDescription
scalingrequired"cube_root"
kParequirednumberSite constant in P = K·SD^−β, pascals.> 0
betarequirednumberAttenuation exponent β.> 0
sigmaLnrequirednumberResidual standard deviation in ln(Pa).≥ 0
nrequirednumberReadings in the fit.> 0
fitrequiredLawFitStatisticsThe least-squares statistics of a log-log fit, for prediction intervals: ln y ± t(p, dof)·σ·√(1 + 1/n + (ln SD − mean)²/sxx).
scaledDistancerequiredRangeThe scaled-distance range the fit was made over.
sourcerequiredenumplatform_fituserprior

AsBuiltHole

A hole as drilled and loaded. Fields left out are as designed.

FieldTypeDescription
idrequiredstringThe design hole this record amends.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
collarPoint3A position in the case coordinate system, metres.
toePoint3A position in the case coordinate system, metres.
waterDepthMnumberStanding water measured at loading, m.≥ 0
decksarray of DeckThe hole as loaded, when it differs from the design.min 1 items · max 32 items

BackbreakReading

How far behind some of its holes a fired blast broke the wall it left: the damage a model judging it can be fitted to.

FieldTypeDescription
distanceMrequirednumberHow far behind the holes the final wall broke, m. A model judging damage reads it as a radius about each hole’s charge, square to its axis: for vertical holes, the distance in plan from the line of their collars to the broken crest.≥ 0
holeIdsrequiredarray of stringThe holes it was measured behind: the back row for one reading of the blast, or one hole for a reading per hole.min 1 items · max 5000 items · each item min length 1, max length 128, pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
methodenumHow it was measured: taped, surveyed, read from a scan, or estimated by eye.tapesurveyscanestimate
notestringAnything a reader should know.max length 500

BlobRef

A large payload passed by reference rather than inline: terrain, point clouds, long waveforms.

FieldTypeDescription
urirequiredstring (uri)A signed HTTPS URL. It expires; fetch it once when the run starts.
sha256requiredstringA content hash: sha256: followed by 64 lower-case hex digits.pattern ^sha256:[0-9a-f]{64}$
mediaTyperequiredstringIANA media type, for example image/tiff or application/vnd.las.min length 3 · max length 120
bytesintegerSize in bytes.≥ 0

Calibration

What the site has measured. This is what lets a kinematic model be calibrated rather than assumed.

FieldTypeDescription
siteLawSiteLawA fitted scaled-distance attenuation law.
airblastLawAirblastLawA fitted airblast attenuation law on cube-root scaled distance.
seedWaveformsarray of SeedWaveformA single-hole ground-motion record: the kinematic input a superposition model is calibrated from.max 500 items
vodarray of VodMeasurementA measured velocity of detonation.max 5000 items
outcomesarray of MeasuredOutcomeA reading from an earlier blast at this site.max 10000 items
strainAmplitudeStrainAmplitudeThe site's fit of the strain a blast puts in its rock near the charges, which a model judging damage scales its amplitude by.

CancelledRun

Stopped before it finished, by the platform or the provider.

FieldTypeDescription
idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
modelIdrequiredModelIdA model identifier in the form vendor/model, lower case, for example shockai/site-law.
modelVersionrequiredstringA semantic version. A result is always pinned to the exact version that produced it.pattern ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$
caseIdrequiredstringA content hash: sha256: followed by 64 lower-case hex digits.pattern ^sha256:[0-9a-f]{64}$
createdAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
updatedAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
statusrequired"cancelled"

Capability

One kind of output a model produces, and what it needs to produce it.

FieldTypeDescription
outputrequiredOutputKindA kind of answer: a prediction of what a blast will do, or, for hole_diagnosis and strain_amplitude, a reading of what a fired blast did.
inputsrequiredobject
inputs.requiredrequiredarray of InputPathA part of the BlastCase. The case a model receives is built from the parts it declares and nothing else. design.holes carries the holes and the layout family they form; design.drillingDeviation carries design.drillingDeviationM.min 1 items
inputs.requiredAnyOfarray of array of InputPathInputs that stand in for one another: the model needs at least one from each group, for example the charge, from the stated MIC or from the holes. A case carrying none of a group is declined with missing_input, as for a missing required input.default [] · each item min 2 items
inputs.optionalarray of InputPathA part of the BlastCase. The case a model receives is built from the parts it declares and nothing else. design.holes carries the holes and the layout family they form; design.drillingDeviation carries design.drillingDeviationM.default []
validityobjectThe domain the model is validated on. Outputs outside it must be marked outside or declined.
validity.distanceMRangeAn inclusive interval. Either bound may be omitted. A range whose min exceeds its max is empty: a model declared valid over one is valid nowhere, and no prediction falls inside a fitted range that is empty.
validity.scaledDistanceRangeAn inclusive interval. Either bound may be omitted. A range whose min exceeds its max is empty: a model declared valid over one is valid nowhere, and no prediction falls inside a fitted range that is empty.
validity.rockClassesarray of RockClassCoarse rock class used when no measured properties are available.
validity.notesstringmax length 1000

CaseUnavailable

A kind answered once for the case that the model declined.

FieldTypeDescription
kindrequiredenumppv_fielddamage_envelopestrain_fieldflyrock_zonefragmentation_curvemovement_fieldtiming_proposalhole_diagnosisstrain_amplitude
reasonrequiredenumWhy the model did not answer.not_supportedmissing_inputoutside_validityinsufficient_calibration
detailstringmax length 500

The data owner’s terms for this case. A provider that cannot honour them must refuse the run.

FieldTypeDescription
purposerequiredenumWhat the owner agreed the case be used for: prediction of what a blast will do, or diagnosis of what a fired blast did, which sends the blast’s own records. A case asks only for the kinds of its purpose.predictiondiagnosis
retentionrequiredenumHow long the provider may keep the case after the run.none30dcontract
allowTrainingrequiredbooleanWhether the provider may use the case to improve its model. False unless the owner opts in.

CoordinateSystem

The frame every position in the case is expressed in.

One of

kind = "epsg"
FieldTypeDescription
kindrequired"epsg"
coderequiredintegerEPSG code of a projected system, for example 28350 (GDA94 / MGA zone 50).> 0
kind = "local"
FieldTypeDescription
kindrequired"local"
namerequiredstringThe mine grid name.min length 1 · max length 120
gridBearingDegnumberBearing of grid north from true north, degrees clockwise.≥ -360 · ≤ 360
originobjectWGS 84 position of the local origin, when known.
origin.latituderequirednumber≥ -90 · ≤ 90
origin.longituderequirednumber≥ -180 · ≤ 180

DamageEnvelope

The zone around the charges where rock is expected to be damaged: the basis for wall control.

FieldTypeDescription
kindrequired"damage_envelope"
thresholdMmSrequirednumberThe PPV taken as the onset of damage for this envelope.> 0
criterionrequiredstringName of the damage criterion, for example holmberg-persson, charge-column-integration or hoek-brown-strain.min length 1 · max length 120
holesrequiredarray of objectmax 5000 items
holes[].holeIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
holes[].radiusMrequiredEstimateRadius from the hole axis at which the threshold is reached.
surfaceBlobRefThe envelope as a closed mesh, when available.
validityrequiredValidityHow far to trust one output.

Deck

One interval of a hole, collar downwards. Only an explosive deck carries a product and a mass.

One of ExplosiveDeck | UnchargedDeck

Design

The blast as designed.

FieldTypeDescription
namestringmin length 1 · max length 200
patternenumLayout family.squarerectangularstaggeredringdevelopmentother
holesrequiredarray of DesignHoleEvery hole, collar to toe. Empty when the platform holds only a summary of the design, as for a what-if question about a charge at a distance.max 5000 items
productsrequiredarray of ProductAn explosive product as loaded.max 50 items
initiationInitiationOmitted when the platform holds only a summary of the design.
maxInstantaneousChargeMaxInstantaneousChargeThe maximum instantaneous charge (MIC) as the platform computed it for compliance. A model that works from the charge rather than from every hole should use it; one that models the holes may recompute it.
drillingDeviationMnumberOne standard deviation of collar and drilling error, m (Cunningham’s W): what fragmentation uniformity loses to imperfect drilling.≥ 0

DesignHole

A hole as designed.

FieldTypeDescription
idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
rowinteger> 0
columninteger> 0
collarrequiredPoint3A position in the case coordinate system, metres.
toerequiredPoint3A position in the case coordinate system, metres.
diameterMmnumberHole diameter, mm. Left out when the plan does not state it.> 0 · ≤ 2000
domainIdstringThe rock domain the hole sits in.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
burdenMnumberBurden this hole breaks, m.> 0
spacingMnumberSpacing to its neighbour in the row, m.> 0
subdrillMnumberDrilled length below grade, m.
decksrequiredarray of DeckThe hole from collar to toe. Stemming is a deck like any other.min 1 items · max 32 items
delayrequiredHoleDelayWhen a hole is designed to fire.

DiagnosedHole

One hole’s diagnosis.

FieldTypeDescription
holeIdrequiredstringThe design hole.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
verdictrequiredHoleVerdictWhat became of a hole. on_time, late and early: it fired, within the model’s timing limit of its designed time, after it, or before it. not_detected: no motion of its own was found, so it is taken not to have fired. weak and strong: it fired, and its ground motion was well below or well above the blast’s typical hole. unrelieved: it fired confined, with no relief to break to; reserved for a model that can tell, and the platform’s own does not give it. unresolved: the records cannot tell it from the holes in resolvedWith. A verdict claims only what it names: a hole on time may also be weak, which size says.
confidencerequirednumberThe model’s probability that the verdict is right, about what the verdict claims and nothing more: for on_time, late and early, that the hole fired and when; for weak and strong, its size; for not_detected, that it did not fire.≥ 0 · ≤ 1
alternativesarray of objectThe other verdicts the model weighed, likeliest first. Each is a claim of its own, so with the verdict’s they need not sum to one.max 8 items
alternatives[].verdictrequiredHoleVerdictWhat became of a hole. on_time, late and early: it fired, within the model’s timing limit of its designed time, after it, or before it. not_detected: no motion of its own was found, so it is taken not to have fired. weak and strong: it fired, and its ground motion was well below or well above the blast’s typical hole. unrelieved: it fired confined, with no relief to break to; reserved for a model that can tell, and the platform’s own does not give it. unresolved: the records cannot tell it from the holes in resolvedWith. A verdict claims only what it names: a hole on time may also be weak, which size says.
alternatives[].confidencerequirednumber≥ 0 · ≤ 1
timingobjectWhen the hole fired. Left out for a hole not detected.
timing.offsetMsrequirednumberThe firing time the model found less the design hole’s delay.totalMs, ms.
timing.sigmaMsnumberOne standard deviation of that time, ms.≥ 0
sizeobjectHow big the hole was. Left out for a hole not detected.
size.relativerequirednumberIts ground motion over the blast’s typical hole’s: 1 is typical.≥ 0
size.sigmaLnnumberOne standard deviation of ln(relative).≥ 0
size.callobjectThe size as a claim of its own, where the records resolve sizes. A weak or strong verdict makes the same call.
size.call.valuerequiredenumweaktypicalstrong
size.call.confidencerequirednumberThe model’s probability that the call is right.≥ 0 · ≤ 1
confinementobjectHow much shear the hole carried, which is what confinement shows as. Only where a record’s heading is known.
confinement.relativerequirednumberIts shear over its compression (motion across the ray over motion along it) against the blast’s typical hole: 1 is typical.≥ 0
confinement.sigmaLnnumber≥ 0
clarityDbnumberThe hole’s motion over the noise at its clearest record, dB.
dominantFrequencyHznumber> 0
resolvedWitharray of stringThe other design holes the records cannot tell this one from: they fired too close together for any record to separate.max 5000 items · each item min length 1, max length 128, pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
flagsarray of stringWhat a reader should know about this hole’s answer, as stable codes. Reserved: heading_unknown, no record that heard it has a known heading; det_log_disagrees, the firing record says it did not fire and the records say it did; low_snr, it is barely above the noise; clipped_samples, a record that heard it was clipped; window_truncated, the record ends before its motion does; no_plan_time, the design gives it no firing time.max 20 items · each item max length 80, pattern ^[a-z][a-z0-9_.-]*$
evidenceHoleEvidenceThe working behind a verdict: the ground motion the model attributes to this hole alone, so a reader can see what it rests on.

Ed25519Jwk

An Ed25519 public key as an RFC 8037 JWK. Publish only the public half: the platform refuses a manifest whose key carries its private part (d).

FieldTypeDescription
ktyrequired"OKP"
crvrequired"Ed25519"
xrequiredstringThe 32-byte public key, base64url without padding.min length 43 · max length 43 · pattern ^[A-Za-z0-9_-]+$
kidstringIgnored: the key id is always the RFC 7638 thumbprint.min length 1 · max length 128
use"sig"
alg"EdDSA"

Estimate

A predicted quantity with its uncertainty. A point value with no spread is allowed but a spread is expected: a prediction without one cannot be scored for coverage.

FieldTypeDescription
medianrequirednumberThe best estimate (P50).
percentilesarray of objectFurther points on the predictive distribution, usually those the request asked for.max 99 items
percentiles[].prequirednumberPercentile, 0 to 100.≥ 0 · ≤ 100
percentiles[].valuerequirednumberThe value at that percentile, in the unit of the parent quantity.
ensemblearray of numberRaw ensemble members, for providers that sample rather than summarise.max 10000 items

ExplosiveDeck

An interval of a hole loaded with explosive.

FieldTypeDescription
kindrequired"explosive"
topDepthMrequirednumberDepth of the top of the deck along the hole, from the collar.≥ 0
bottomDepthMrequirednumberDepth of the bottom of the deck along the hole.≥ 0
productIdrequiredstringThe product loaded.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
massKgrequirednumberCharge mass.≥ 0

FailedRun

Finished without a result, and why.

FieldTypeDescription
idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
modelIdrequiredModelIdA model identifier in the form vendor/model, lower case, for example shockai/site-law.
modelVersionrequiredstringA semantic version. A result is always pinned to the exact version that produced it.pattern ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$
caseIdrequiredstringA content hash: sha256: followed by 64 lower-case hex digits.pattern ^sha256:[0-9a-f]{64}$
createdAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
updatedAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
statusrequired"failed"
errorrequiredobject
error.typerequiredenumThe error family. unsupported_case and consent_refused are final; rate_limited, provider_error and timeout may be retried.invalid_requestunsupported_caseconsent_refusedauthenticationrate_limitedquote_expiredprovider_errortimeout
error.coderequiredstringA stable machine-readable code within the family.max length 80 · pattern ^[a-z][a-z0-9_]*$
error.messagerequiredstringmin length 1 · max length 1000
error.paramstringThe case field at fault, as a JSON Pointer.max length 200

FiringRecord

What actually fired, and when.

FieldTypeDescription
sourcerequiredenumWhere the firing times come from: a detonator log, an imported timing file, or the design itself.det_logtiming_importdesign
firedAtstring (date-time)Wall-clock time of T0.
holesrequiredarray of objectmax 5000 items
holes[].idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
holes[].firedMsrequirednumber | nullMeasured firing time from T0, ms; null when the hole did not fire.
holes[].statusrequiredenumfiredmisfirecutoffunknown

FlyrockZone

Predicted flyrock range and clearance.

FieldTypeDescription
kindrequired"flyrock_zone"
maxThrowMrequiredEstimateMaximum expected throw, m.
mechanismrequiredenumface_burstcrateringriflingcombined
clearanceobjectRecommended clearance distances.
clearance.personnelMrequirednumber> 0
clearance.equipmentMrequirednumber> 0
holesarray of objectmax 5000 items
holes[].holeIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
holes[].maxThrowMrequirednumber≥ 0
holes[].faceBurstMnumberHow far the face would throw rock out through the hole’s burden, m.≥ 0
holes[].crateringMnumberHow far the hole’s stemming and the rock over its charge would be thrown if they blew out, m. Whether they do is not this figure: the hole’s confinement says that.≥ 0
holes[].stemmingMnumberThe stemming the hole was read at, m: as loaded where the case’s as-built record states the hole’s decks, else as designed.≥ 0
holes[].stemmingAsLoadedbooleanTrue where stemmingM is the as-built record’s.
validityrequiredValidityHow far to trust one output.

FragmentationCurve

Predicted size distribution of the broken rock.

FieldTypeDescription
kindrequired"fragmentation_curve"
domainIdstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
curverequiredarray of objectThe curve, by ascending sieve size.min 2 items · max 200 items
curve[].sizeMmrequirednumberSieve size, mm.> 0
curve[].passingPercentrequirednumberPercent of the rock passing that size.≥ 0 · ≤ 100
x50MmrequiredEstimateA predicted quantity with its uncertainty. A point value with no spread is allowed but a spread is expected: a prediction without one cannot be scored for coverage.
x80MmrequiredEstimateA predicted quantity with its uncertainty. A point value with no spread is allowed but a spread is expected: a prediction without one cannot be scored for coverage.
uniformityIndexnumber≥ 0
validityrequiredValidityHow far to trust one output.

FrequencyBin

One band of log10(scaled distance) and the median dominant frequency the site recorded in it.

FieldTypeDescription
log10SdMinrequirednumber
log10SdMaxrequirednumber
medianHzrequirednumberMedian dominant frequency of the readings in the band, Hz.> 0
countrequiredinteger> 0

Grid

A plan-view grid for field outputs. A field’s values sit at the nodes minX + i·cellM, minY + j·cellM for i below its columns and j below its rows, the last node within a cell of maxX and maxY; a reader takes columns and rows from the output and never recomputes them.

FieldTypeDescription
minXrequirednumber
minYrequirednumber
maxXrequirednumber
maxYrequirednumber
cellMrequirednumberCell size, m.> 0
elevationrequiredenumWhere grid points sit vertically.terraincollar_plane

HoleDelay

When a hole is designed to fire.

FieldTypeDescription
totalMsrequirednumberDesigned firing time from T0, milliseconds.
surfaceMsnumberDelay carried by the surface connector.≥ 0
downholeMsnumberDelay of the in-hole unit.≥ 0
tieInFromstringThe hole this one receives its signal from on the surface tie-in.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$

HoleDiagnosis

What each hole of a fired blast did, read from the blast’s own ground-motion records and its firing record.

FieldTypeDescription
kindrequired"hole_diagnosis"
holesrequiredarray of DiagnosedHoleEvery design hole with an explosive deck, once each.max 5000 items
recordsarray of objectWhat became of each record the model was given.max 64 items
records[].recordIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
records[].userequiredenumWhat the model did with the record: read it; set it aside as unable to tell the holes apart; or skipped it unread, for example beyond the number of records it reads, or at a receiver with no position.readset_asideskipped
records[].residualFractionnumberFor a record read: the energy left in it once every hole’s motion is taken out, over what was there.≥ 0
validityrequiredValidityHow far to trust one output.

HoleEvidence

The working behind a verdict: the ground motion the model attributes to this hole alone, so a reader can see what it rests on.

FieldTypeDescription
recordIdrequiredstringThe record of measured.records the motion is modelled on: the one that heard the hole most clearly.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
sampleRateHzrequirednumberThe rate of the rows, which is the model’s own and need not be the record’s.> 0
startMsrequirednumberTime of the first row from T0, ms, as the model aligned the record.
samplesrequiredarray of [3 × number]The hole’s own motion at that record, one [a, b, c] row per sample on the record’s axes, mm/s. At most a second or so: enough to draw.max 8192 items

HoleVerdict

What became of a hole. on_time, late and early: it fired, within the model’s timing limit of its designed time, after it, or before it. not_detected: no motion of its own was found, so it is taken not to have fired. weak and strong: it fired, and its ground motion was well below or well above the blast’s typical hole. unrelieved: it fired confined, with no relief to break to; reserved for a model that can tell, and the platform’s own does not give it. unresolved: the records cannot tell it from the holes in resolvedWith. A verdict claims only what it names: a hole on time may also be weak, which size says.

Valueson_timelateearlynot_detectedweakstrongunrelievedunresolved

ImportedOutput

One prediction made elsewhere, discriminated by kind: every kind a prediction case asks.

One of ReceiverPpv | MaxCharge | ReceiverWaveform | ReceiverSpectrum | PpvField | Airblast | DamageEnvelope | StrainField | FlyrockZone | FragmentationCurve | MovementField | TimingProposal

Initiation

How the blast is initiated.

FieldTypeDescription
systemrequiredInitiationSystemThe detonator technology. It sets the delay scatter a model should assume when none is given.
delayScatterobjectOne standard deviation of detonator timing error: a fixed part plus a percentage of the nominal delay.
delayScatter.fixedMsnumber≥ 0
delayScatter.percentnumber≥ 0

InitiationSystem

The detonator technology. It sets the delay scatter a model should assume when none is given.

Valueselectronicnonelelectricdetonating_cord

InputPath

A part of the BlastCase. The case a model receives is built from the parts it declares and nothing else. design.holes carries the holes and the layout family they form; design.drillingDeviation carries design.drillingDeviationM.

Valuesdesign.holesdesign.productsdesign.initiationdesign.maxInstantaneousChargedesign.drillingDeviationasBuilt.holesasBuilt.firingsite.domainssite.terrainreceiverscalibration.siteLawcalibration.airblastLawcalibration.seedWaveformscalibration.vodcalibration.outcomescalibration.strainAmplitudemeasured.recordsmeasured.backbreak

LawFitStatistics

The least-squares statistics of a log-log fit, for prediction intervals: ln y ± t(p, dof)·σ·√(1 + 1/n + (ln SD − mean)²/sxx).

FieldTypeDescription
dofrequirednumberResidual degrees of freedom of the fit.> 0
meanLnScaledDistancerequirednumberMean of ln(scaled distance) over the readings.
sxxrequirednumber | nullΣ(ln SD − mean)² over the readings. Null when only the law’s summary is known; intervals then leave out the leverage term.> 0

MaxCharge

The inverse question: how much charge per delay a receiver’s limit allows. The design value blasters plan with.

FieldTypeDescription
kindrequired"max_charge"
receiverIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
limitMmSrequirednumberThe PPV limit the charge was held to: the receiver’s own limit.> 0
percentilerequirednumberThe percentile the limit was read at.≥ 50 · ≤ 99.9
maxChargeKgrequirednumber | nullThe largest maximum instantaneous charge whose prediction at that percentile stays at or under the limit. Null when even a token charge exceeds it.> 0
scaledDistancenumberThe scaled distance at that charge.> 0
validityrequiredValidityHow far to trust one output.

MaxInstantaneousCharge

The maximum instantaneous charge (MIC) as the platform computed it for compliance. A model that works from the charge rather than from every hole should use it; one that models the holes may recompute it.

FieldTypeDescription
massKgrequirednumberThe largest charge detonating inside any one window, kg.> 0
windowMsrequirednumberThe window, ms. Jurisdictions set it; 8 ms is common.> 0

Measured

What was measured of this blast itself, once it has fired. calibration holds what earlier blasts taught the site; this holds the blast in question.

FieldTypeDescription
recordsarray of MeasuredRecordA ground-motion record of this blast, as a monitor wrote it. Its time against T0 is not known: a recorder starts on the motion reaching it, and its clock is not the initiation system’s. A model that needs the two aligned finds the alignment itself.max 64 items
backbreakarray of BackbreakReadingHow far behind its holes the blast broke the wall, once it was seen.max 5000 items

MeasuredOutcome

A reading from an earlier blast at this site.

FieldTypeDescription
blastRefrequiredstringWhich earlier blast this came from.min length 1 · max length 200
receiverIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
distanceMnumber> 0
micKgnumberMaximum instantaneous charge of that blast, kg.> 0
ppvMmSnumber≥ 0
basisPpvBasisHow peak particle velocity is taken: the largest single component (max_axis) or the peak vector sum (pvs).
dominantFrequencyHznumber> 0
airblastDbLnumber≥ 0

MeasuredRecord

A ground-motion record of this blast, as a monitor wrote it. Its time against T0 is not known: a recorder starts on the motion reaching it, and its clock is not the initiation system’s. A model that needs the two aligned finds the alignment itself.

FieldTypeDescription
idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
receiverIdrequiredstringThe receiver it was recorded at. That receiver carries a position, with or without an elevation: a record with no place on the grid tells a model nothing about which hole it heard.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
sampleRateHzrequirednumber> 0
axesrequiredenumHow the rows’ three components lie. recorded: as the unit wrote them, with nothing known of how it lay. levelled: turned so the third component is vertical, up positive, and the first two lie in the level plane on an unknown bearing. oriented: levelled, with the first component along headingDeg and the second a quarter turn clockwise of it seen from above.recordedlevelledoriented
headingDegnumberBearing of the first component, degrees clockwise from grid north. Given for oriented axes only.≥ 0 · ≤ 360
quietUntilIndexrequiredintegerThe rows before this index were recorded before the blast’s motion arrived: what a model measures the noise from.≥ 0
dominantFrequencyHznumberDominant frequency of the record, Hz, as the platform’s analysis found it.> 0
clipMmSnumberThe recorder’s full scale, mm/s. A sample at it was clipped.> 0
recordedAtstring (date-time)Wall-clock time of the first row, by the recorder’s own clock.
samplesrequiredParticleVelocityThree-component particle velocity, mm/s: one [a, b, c] row per sample in frame order, so every component has the same length; or a reference to the same rows.

ModelId

A model identifier in the form vendor/model, lower case, for example shockai/site-law.

stringmin length 3 · max length 128 · pattern ^[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9.-]*$

ModelMethod

The family of method, so a user can tell a fitted law from a simulation.

Valuesempiricalkinematicnumericalstatisticalhybrid

MovementField

Predicted displacement of the burden, and the muckpile it forms.

FieldTypeDescription
kindrequired"movement_field"
pointsrequiredarray of objectmax 50000 items
points[].idrequiredstringNames the point within this field.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
points[].fromrequiredPoint3A position in the case coordinate system, metres.
points[].torequiredPoint3A position in the case coordinate system, metres.
points[].flightobjectWhen the point moves. Without a touchdown, a viewer may draw it as an arc under gravity that joins from and to in that time; the model’s own path may differ, such as a block that rolls after it lands. Left out, only the displacement is stated.
points[].flight.launchMsrequirednumberWhen the point leaves from, milliseconds from T0.
points[].flight.durationMsrequirednumberHow long it then takes to come to rest at to, milliseconds.≥ 0
points[].flight.touchdownobjectWhere the point first comes down on something, or the rock round it closes on it: the end of its flight through the air, before it rolls, slides, slumps or drops to to, or is carried up to it. The arc under gravity that joins from and at in afterMs is the model’s own flight; from there the point moves to to, arriving at durationMs. Left out, the flight is not told apart from what follows it.
points[].flight.touchdown.atrequiredPoint3A position in the case coordinate system, metres.
points[].flight.touchdown.afterMsrequirednumberWhen it gets there, milliseconds after it leaves from: never after durationMs.≥ 0
points[].sourceobjectThe point as a source for a model of the broken rock’s surface, a flow over the ground the blast empties: how much rock, how heavy, the momentum it starts with and whether the mass carries it. A field that states sources states one for every point with a flight (conformance holds it to that). Left out, a viewer infers the flow from where the points rest.
points[].source.volumeM3requirednumberThe rock the point stands for as it stood in the bench, m³: in situ, before any swell.> 0
points[].source.massKgrequirednumberThat rock’s mass, kg.> 0
points[].source.momentumrequiredobjectThe level momentum the rock leaves from with at flight.launchMs, kg·m/s, once whatever confines or relieves it has taken its share: what a flow of the broken rock over the ground starts with. Its vertical part is not stated; the flight is.
points[].source.momentum.xrequirednumberEastward, kg·m/s.
points[].source.momentum.yrequirednumberNorthward, kg·m/s.
points[].source.carriedrequiredbooleanTrue where the mass carries the rock: it rides the burden as its cover (a model may hold the stemming above the charge so wherever it comes down), or it comes down and rests over the ground the blast breaks or the bench round it. False where it is thrown clear, out through the free face onto the floor in front, a piece of its own.
muckpileSurfaceBlobRefThe predicted muckpile surface.
validityrequiredValidityHow far to trust one output.

Output

One answer, discriminated by kind.

One of ReceiverPpv | MaxCharge | ReceiverWaveform | ReceiverSpectrum | PpvField | Airblast | DamageEnvelope | StrainField | FlyrockZone | FragmentationCurve | MovementField | TimingProposal | HoleDiagnosis | StrainAmplitudeFit

OutputKind

A kind of answer: a prediction of what a blast will do, or, for hole_diagnosis and strain_amplitude, a reading of what a fired blast did.

Valuesreceiver_ppvmax_chargereceiver_waveformreceiver_spectrumppv_fieldairblastdamage_envelopestrain_fieldflyrock_zonefragmentation_curvemovement_fieldtiming_proposalhole_diagnosisstrain_amplitude

OutputRequest

The question the case asks.

FieldTypeDescription
outputsrequiredarray of OutputKindWhat the caller wants back.min 1 items
receiverIdsarray of stringReceivers to predict at; all receivers when omitted.each item min length 1, max length 128, pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
gridGridA plan-view grid for field outputs. A field’s values sit at the nodes minX + i·cellM, minY + j·cellM for i below its columns and j below its rows, the last node within a cell of maxX and maxY; a reader takes columns and rows from the output and never recomputes them.
percentilesarray of numberPoints of the predictive distribution to report. 50 and 95 when omitted.max 20 items · default [50,95] · each item ≥ 0, ≤ 100
designPercentilenumberThe percentile design values are read at: a charge limit is the largest charge whose prediction at this percentile stays under the limit. 95 when omitted.≥ 50 · ≤ 99.9 · default 95
seedintegerSeed for any sampling, so a run can be reproduced exactly.≥ 0

ParticleVelocity

Three-component particle velocity, mm/s: one [a, b, c] row per sample in frame order, so every component has the same length; or a reference to the same rows.

One of

array of [3 × number]max 200000 itemsOne row per sample, [a, b, c] in frame order, mm/s.

Point3

A position in the case coordinate system, metres.

FieldTypeDescription
xrequirednumberEasting, metres.
yrequirednumberNorthing, metres.
zrequirednumberElevation, metres. Up is positive.

PpvBasis

How peak particle velocity is taken: the largest single component (max_axis) or the peak vector sum (pvs).

Valuesmax_axispvs

PpvField

Peak particle velocity over a plan-view grid, at one percentile.

FieldTypeDescription
kindrequired"ppv_field"
gridrequiredGridA plan-view grid for field outputs. A field’s values sit at the nodes minX + i·cellM, minY + j·cellM for i below its columns and j below its rows, the last node within a cell of maxX and maxY; a reader takes columns and rows from the output and never recomputes them.
percentilerequirednumber≥ 0 · ≤ 100
basisrequiredPpvBasisHow peak particle velocity is taken: the largest single component (max_axis) or the peak vector sum (pvs).
columnsrequiredintegerNodes along x: ⌊(maxX − minX) / cellM⌋ + 1.> 0
rowsrequiredintegerNodes along y: ⌊(maxY − minY) / cellM⌋ + 1.> 0
valuesMmSrequiredarray of (number | null) | BlobRefRow-major from the south-west corner; null where the model declines to predict.max 4000000 items · each item ≥ 0
validityrequiredValidityHow far to trust one output.

Product

An explosive product as loaded.

FieldTypeDescription
idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
namerequiredstringmin length 1 · max length 120
classrequiredenumProduct family.anfoheavy_anfoemulsionwatergelpackagedboosterother
densityGccnumberIn-hole density, g/cm³.> 0 · ≤ 3
relativeWeightStrengthnumberRelative weight strength, ANFO = 100.> 0
energyMjKgnumberRated energy, MJ/kg.> 0
nominalVodMsnumberNominal velocity of detonation, m/s.> 0

Provenance

Where a result came from. Reports cite it; the platform uses it to score the model later.

FieldTypeDescription
modelIdrequiredModelIdA model identifier in the form vendor/model, lower case, for example shockai/site-law.
modelVersionrequiredstringA semantic version. A result is always pinned to the exact version that produced it.pattern ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$
caseIdrequiredstringA content hash: sha256: followed by 64 lower-case hex digits.pattern ^sha256:[0-9a-f]{64}$
startedAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
finishedAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
inputsUsedrequiredarray of InputPathWhich parts of the case the model actually read, as input paths.max 50 items
parametersmap of (string | number | boolean)Any parameters the model fitted or chose, so the result can be explained.
buildHashstringThe build that answered, as the manifest's build.hash names it.min length 1 · max length 128 · pattern ^[A-Za-z0-9._:+/@-]+$

QueuedRun

Accepted and waiting to start.

FieldTypeDescription
idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
modelIdrequiredModelIdA model identifier in the form vendor/model, lower case, for example shockai/site-law.
modelVersionrequiredstringA semantic version. A result is always pinned to the exact version that produced it.pattern ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$
caseIdrequiredstringA content hash: sha256: followed by 64 lower-case hex digits.pattern ^sha256:[0-9a-f]{64}$
createdAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
updatedAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
statusrequired"queued"
progressnumberFraction complete, for display only.≥ 0 · ≤ 1

Range

An inclusive interval. Either bound may be omitted. A range whose min exceeds its max is empty: a model declared valid over one is valid nowhere, and no prediction falls inside a fitted range that is empty.

FieldTypeDescription
minnumber
maxnumber

Receiver

A place a prediction is wanted. It has a position, a resolved distance, or both.

Needs at least one of position, distanceM

FieldTypeDescription
idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
namestringmin length 1 · max length 200
kindrequiredenumA seismograph location, a structure to protect, a lease or property boundary point, or any point of interest.monitorstructureboundarypoint
positionSurfacePositionWhere the receiver is. Omitted when only its distance is known. A monitor placed on a plan often has no surveyed height: its z is then left out.
distanceMnumberThe source-to-receiver distance the platform resolved: a surveyed or entered distance, or the slant distance to the nearest charge. A model should use it unless it models the geometry itself.> 0
distanceSourcestringWhere distanceM came from, for example manual, placement or georeference.min length 1 · max length 40
limitsobjectThe limits that apply here: a model reports exceedance probability against them, and a charge limit is held to the PPV limit.
limits.ppvMmSnumber> 0
limits.airblastDbLnumber> 0
limits.standardstringThe standard the limit comes from, for example AS 2187.2.max length 120

ReceiverPpv

Predicted peak particle velocity at a receiver.

FieldTypeDescription
kindrequired"receiver_ppv"
receiverIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
basisrequiredPpvBasisHow peak particle velocity is taken: the largest single component (max_axis) or the peak vector sum (pvs).
ppvMmSrequiredEstimatePeak particle velocity, mm/s.
dominantFrequencyHzEstimateFrequency at the peak, Hz.
scaledDistancenumberThe scaled distance the prediction was made at.> 0
exceedanceProbabilitynumberProbability of exceeding the receiver’s PPV limit, when it has one.≥ 0 · ≤ 1
validityrequiredValidityHow far to trust one output.

ReceiverSpectrum

A predicted amplitude spectrum at a receiver.

FieldTypeDescription
kindrequired"receiver_spectrum"
receiverIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
spectrumrequiredarray of objectThe spectrum, by ascending frequency.max 10000 items
spectrum[].frequencyHzrequirednumber> 0
spectrum[].amplituderequirednumberFourier amplitude, mm/s·s.≥ 0
validityrequiredValidityHow far to trust one output.

ReceiverUnavailable

A kind answered per receiver that the model declined, at one receiver or at all of them.

FieldTypeDescription
kindrequiredenumreceiver_ppvmax_chargereceiver_waveformreceiver_spectrumairblast
receiverIdrequiredstring | nullThe receiver the model declined at, or null when it declines the kind at every receiver (for example, the case names none).min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
reasonrequiredenumWhy the model did not answer.not_supportedmissing_inputoutside_validityinsufficient_calibration
detailstringmax length 500

ReceiverWaveform

A predicted ground-motion time history at a receiver.

FieldTypeDescription
kindrequired"receiver_waveform"
receiverIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
percentilenumberWhich member of the distribution this trace represents, when the model samples.≥ 0 · ≤ 100
sampleRateHzrequirednumber> 0
startMsrequirednumberTime of the first sample from T0, ms.
framerequiredenumxyztvl
samplesrequiredParticleVelocityThree-component particle velocity, mm/s: one [a, b, c] row per sample in frame order, so every component has the same length; or a reference to the same rows.
validityrequiredValidityHow far to trust one output.

RockClass

Coarse rock class used when no measured properties are available.

Valuessuper_softsoftmediumhard

RockDomain

A zone of rock the site treats as one material. Holes name the domain they sit in.

FieldTypeDescription
idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
namestringmin length 1 · max length 120
rockClassRockClassCoarse class when nothing better is known.
densityKgM3numberIn-situ density, kg/m³.> 0
ucsMPanumberUniaxial compressive strength, MPa.> 0
youngsModulusGPanumberYoung's modulus, GPa.> 0
hoekBrownMinumberHoek–Brown constant m_i of the intact rock: the m in σ1 = σ3 + σci·(m·σ3/σci + 1)^0.5, which with the UCS gives its tensile strength σci·(√(m² + 4) − m)/2, about UCS/m_i.> 0
poissonsRationumberPoisson's ratio of the intact rock, between 0 and 0.5.> 0 · < 0.5
strengthStageStrengthStageWhich stage of failure the strength figures describe (Martin and Chandler 1994): crack initiation, the onset of strain localisation, or peak. A model judging damage reads the UCS and m_i as that stage's; peak when unstated.
strainCriterionStrainCriterionA strain criterion for this rock, usually regressed from its measured failure strains, which a model judging damage reads in place of the strength it derives from the figures.
pWaveVelocityMsnumberP-wave velocity, m/s.> 0
rmrnumberRock mass rating (Bieniawski).≥ 0 · ≤ 100
gsinumberGeological strength index.≥ 0 · ≤ 100
kuzRamRockFactornumberKuz-Ram rock factor A, when calibrated.> 0

RunningRun

Started and not yet finished.

FieldTypeDescription
idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
modelIdrequiredModelIdA model identifier in the form vendor/model, lower case, for example shockai/site-law.
modelVersionrequiredstringA semantic version. A result is always pinned to the exact version that produced it.pattern ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$
caseIdrequiredstringA content hash: sha256: followed by 64 lower-case hex digits.pattern ^sha256:[0-9a-f]{64}$
createdAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
updatedAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
statusrequired"running"
progressnumberFraction complete, for display only.≥ 0 · ≤ 1

Scaling

Charge scaling for scaled distance: D/√Q for ground vibration, D/∛Q for airblast and near-field work.

Valuessquare_rootcube_root

SeedWaveform

A single-hole ground-motion record: the kinematic input a superposition model is calibrated from.

FieldTypeDescription
idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
holeIdstringThe single hole that produced it.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
receiverIdstringWhere it was recorded.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
distanceMrequirednumberCharge-to-sensor distance, m.> 0
chargeKgrequirednumberCharge mass of the seed hole, kg.> 0
sampleRateHzrequirednumber> 0
framerequiredenumComponent frame: instrument axes, or transverse / vertical / longitudinal to the source.xyztvl
samplesrequiredParticleVelocityThree-component particle velocity, mm/s: one [a, b, c] row per sample in frame order, so every component has the same length; or a reference to the same rows.
recordedAtstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.

SiteLaw

A fitted scaled-distance attenuation law.

FieldTypeDescription
metricrequired"ppv"
basisrequiredPpvBasisHow peak particle velocity is taken: the largest single component (max_axis) or the peak vector sum (pvs).
scalingrequiredScalingCharge scaling for scaled distance: D/√Q for ground vibration, D/∛Q for airblast and near-field work.
krequirednumberSite constant K in PPV = K·SD^−β, mm/s.> 0
betarequirednumberAttenuation exponent β.> 0
sigmaLnnumberResidual standard deviation in natural-log units.≥ 0
nnumberReadings in the fit. Fractional when a regional prior lends the fit its weight in readings.≥ 0
scaledDistanceRangeThe scaled-distance range the fit was made over.
fitLawFitStatisticsWhat a prediction interval needs beyond σ and n.
frequencyBinsarray of FrequencyBinDominant frequency by scaled distance, from the site’s own readings.max 60 items
sourcerequiredenumA law fitted by the platform from this site’s readings, one entered by the user, or a regional prior.platform_fituserprior

StrainAmplitude

The site's fit of the strain a blast puts in its rock near the charges, which a model judging damage scales its amplitude by.

FieldTypeDescription
factorrequirednumberThe ratio of the P wave's amplitude near the charges to the site law's PPV extrapolated inward, as the model that fitted it reads both: above 1 the rock is strained more than the law alone says. A model judging damage scales its near-field amplitude by it.> 0
basisrequiredenumWhat the factor was fitted to: how far behind the back row the wall broke, half-cast counts on the final wall, a post-blast scan against the design, strain read from an array of synchronised monitors, or judgement.backbreakhalf_castscanstrain_arrayjudgement
blastRefstringWhich blast it was fitted on.min length 1 · max length 200
fittedWithobjectThe model and version whose amplitude the factor scales. A factor fitted against one model's assumptions is that model's: another model, another version, or any model when this is left out, reads it as judgement.
fittedWith.modelIdrequiredModelIdA model identifier in the form vendor/model, lower case, for example shockai/site-law.
fittedWith.modelVersionrequiredstringA semantic version. A result is always pinned to the exact version that produced it.pattern ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$
notestringHow the fit was made, for a reader.max length 500

StrainAmplitudeFit

A damage model's amplitude fitted to the damage a fired blast did: how much the strain near its charges exceeded, or fell short of, what the model takes from the site law.

FieldTypeDescription
kindrequired"strain_amplitude"
factorrequiredEstimateThe factor on the model's near-field amplitude that makes the damage radius it reports on the observed holes what was seen: the median over the holes, in log, with their spread as percentiles. What a later case of the site carries as calibration.strainAmplitude.
basisrequiredenumWhat it was fitted to: the backbreak measured behind the holes.backbreak
holesrequiredarray of objectEach hole the fit read, once.max 5000 items
holes[].holeIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
holes[].observedMrequirednumberThe backbreak seen behind it, m.≥ 0
holes[].factorrequirednumberThe least factor at which the model reports its radius as the backbreak, stated rounded up.> 0
validityrequiredValidityHow far to trust one output.

StrainCriterion

A strain-based Hoek–Brown criterion of the intact rock as Yang and Green (2025) write it, eq. 4: ε1 = ε3 ± (a·σci·ε3 + b·σci²)^0.5 + c·σci, strain a dimensionless fraction, compression positive. A model judging damage reads it on a state's greatest and least compressive principal strains, the middle one ignored, with no tension cutoff beyond the curve's own, in place of the strength it would derive from the domain's figures: so a criterion derived from the same E, μ and m need not answer as the figures do.

FieldTypeDescription
stageStrengthStageThe stage of failure the criterion describes; peak when unstated.
sigmaCiMParequirednumberThe σci the constants were fitted or derived with, MPa.> 0
arequirednumberPer MPa, for strain as a fraction (not percent).
brequirednumberPer MPa², for strain as a fraction. Must exceed c², or the curve does not enclose the unstrained state: a model judges such a criterion by the form it derives from the figures instead, and warns.> 0
crequirednumberPer MPa, for strain as a fraction.
lesserStrainRangeThe least compressive principal strain ε3 over the failures the fit was made from: compression positive, so the lateral extension of a triaxial test is negative. A model warns where it reads the curve outside it; an empty range covers nothing.
greaterStrainRangeThe greatest compressive principal strain ε1 over the same failures. The curve has two limbs, and at a lesser strain inside its range the other limb was not fitted: with this, a model can tell which it read.
basisrequiredenumWhether the constants were regressed from measured failure strains (their eq. 14) or derived from E, μ and m (their eqs 5–7).regressionderived
notestringWhere the failure strains or figures came from, for a reader.max length 500

StrainField

Peak extension of the rock over a plan-view grid at a depth: where a blast strains the rock past its strength, and by how much.

FieldTypeDescription
kindrequired"strain_field"
gridrequiredGridA plan-view grid for field outputs. A field’s values sit at the nodes minX + i·cellM, minY + j·cellM for i below its columns and j below its rows, the last node within a cell of maxX and maxY; a reader takes columns and rows from the output and never recomputes them.
depthMrequirednumberHow far below the grid's plane the field was read, m, the plane being the charged holes' mean collar height for collar_plane: the strain the rock sees at the charges' level, not at the surface.≥ 0
columnsrequiredintegerNodes along x: ⌊(maxX − minX) / cellM⌋ + 1.> 0
rowsrequiredintegerNodes along y: ⌊(maxY − minY) / cellM⌋ + 1.> 0
valuesMicrostrainrequiredarray of (number | null) | BlobRefPeak principal extension of the rock at each cell over the whole blast, microstrain, row-major from the south-west corner; null where the model declines to predict.max 4000000 items · each item ≥ 0
thresholdMicrostrainrequirednumberThe extension at which a plane P wave reaches the model's criterion, for a viewer to contour: the strain of the PPV its damage_envelope reports as thresholdMmS.> 0
validityrequiredValidityHow far to trust one output.

StrengthStage

A stage of the progressive failure of intact rock, from the first cracks to the peak load.

Valuescrack_initiationstrain_localisationpeak

SucceededRun

Finished with the model’s result.

FieldTypeDescription
idrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
modelIdrequiredModelIdA model identifier in the form vendor/model, lower case, for example shockai/site-law.
modelVersionrequiredstringA semantic version. A result is always pinned to the exact version that produced it.pattern ^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$
caseIdrequiredstringA content hash: sha256: followed by 64 lower-case hex digits.pattern ^sha256:[0-9a-f]{64}$
createdAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
updatedAtrequiredstring (date-time)An ISO 8601 timestamp in UTC, for example 2026-09-26T04:12:00Z.
statusrequired"succeeded"
resultrequiredModelResultWhat a model returns for one case.

SurfacePosition

A place on the ground in the case coordinate system, metres, whose elevation may not be known.

FieldTypeDescription
xrequirednumberEasting, metres.
yrequirednumberNorthing, metres.
znumberElevation, metres. Up is positive. Left out where the height was never surveyed: unknown, not zero.

TimingProposal

A proposed set of firing times.

FieldTypeDescription
kindrequired"timing_proposal"
objectiverequiredstringWhat the proposal optimises, for example minimise P95 PPV at receiver R3.min length 1 · max length 500
holesrequiredarray of objectmax 5000 items
holes[].holeIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
holes[].totalMsrequirednumber
expectedarray of objectWhat the model expects the proposed timing to achieve.max 1000 items
expected[].receiverIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
expected[].ppvMmSrequiredEstimateA predicted quantity with its uncertainty. A point value with no spread is allowed but a spread is expected: a prediction without one cannot be scored for coverage.
validityrequiredValidityHow far to trust one output.

Unavailable

A requested output the model declined to produce, and why.

One of ReceiverUnavailable | CaseUnavailable

UnchargedDeck

An interval of a hole with no explosive in it.

FieldTypeDescription
kindrequiredenumWhat fills this interval of the hole.stemmingairwaterinert
topDepthMrequirednumberDepth of the top of the deck along the hole, from the collar.≥ 0
bottomDepthMrequirednumberDepth of the bottom of the deck along the hole.≥ 0

Validity

How far to trust one output.

FieldTypeDescription
statusrequiredenumWhether the inputs sit inside the range the model was validated on.withinextrapolatedoutside
codestringWhich way it is outside, as a stable code: for example below_fitted_range, above_fitted_range, near_field.max length 60 · pattern ^[a-z][a-z0-9_]*$
notestringmax length 500

VodMeasurement

A measured velocity of detonation.

FieldTypeDescription
holeIdrequiredstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
productIdstringAn opaque identifier: letters, digits, ., _, : and -, up to 128 characters.min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]*$
vodMsrequirednumberMeasured velocity of detonation, m/s.> 0
methodrequiredenumcontinuous_resistancepoint_to_pointoptical

Warning

Something the model wants a person to see.

FieldTypeDescription
coderequiredstringA stable machine-readable code. Reserved: interval.approximate, the intervals on this result are approximate (for example, the fit came without its leverage statistics); target narrows it to a receiver. Reserved for a diagnosis: diagnosis.not_converged, the fit had not settled when it stopped; diagnosis.single_record, only one record was read, so nothing cross-checks it; diagnosis.det_log_disagrees, a hole the firing record says did not fire shows in the records; diagnosis.heading_unknown, no record’s heading is known, so shear is not read.max length 80 · pattern ^[a-z][a-z0-9_.-]*$
messagerequiredstringmin length 1 · max length 1000
targetstringWhat the warning is about: a hole id, a receiver id or a field path.max length 200