Digital Twins
Lists digital twins in the workspace. Paginated (limit, cursor). Read from platform MongoDB. Versions are listed under /versions.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Page size (1-1000, default 50).
1Opaque cursor from a previous response's pagination.cursor.
exampleSuccessful response
Unauthorized
Forbidden
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"id": "text",
"organisationId": "text",
"workspaceId": "text",
"name": "text",
"normalizedName": null,
"type": "static",
"canonicalInputSchema": [
{
"field": "text",
"type": "None",
"subtype": "Integer",
"availableTypes": [
"None"
],
"isIndex": null,
"categories": [
"text"
],
"aliases": [
"text"
],
"description": null,
"displayWidth": null,
"originalFormat": null,
"displayFormat": null,
"unit": null,
"unitModifier": null,
"dateOrderAssumed": null
}
],
"tags": [
"text"
],
"status": "active",
"createdAt": "text",
"suggestedSimulations": [
{
"id": "text",
"name": "text",
"description": "text",
"scenario": {
"type": "text",
"objectives": [
{
"direction": "maximise",
"variable": "text",
"metricSqlQuery": "text",
"unit": {},
"weight": 1,
"variablesRelevantToMetric": [
"text"
],
"target": {
"type": "percentage",
"value": null
},
"conceptId": null,
"conceptEditVersion": 1
}
],
"conditions": [
{
"variable": "text",
"operator": "eq",
"value": 1
}
],
"decisionVars": [
"text"
],
"variableConstraints": [
{
"variable": "text",
"type": "range",
"minValue": null,
"maxValue": null,
"allowedValues": [
"text"
],
"maxChangePercent": 1,
"conditionalAllowedValues": [
{
"condition": {
"variable": "text",
"operator": "eq",
"value": 1
},
"allowedValues": [
"text"
],
"minValue": null,
"maxValue": null
}
]
}
],
"metricConstraints": [
{
"metricName": "text",
"sqlQuery": "text",
"constraintType": "min_value",
"value": null,
"booleanValue": null,
"temporal": {
"startDate": null,
"endDate": null,
"startTimestampMs": null,
"endTimestampMs": null,
"intervalSteps": null
}
}
],
"segmentDefinitions": [
{
"id": "text",
"description": null,
"conditions": [
{
"variable": "text",
"operator": "eq",
"value": 1
}
]
}
],
"enableSegmentInterventions": false,
"interventionTypes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"interventionCountConfig": {
"maxInterventions": 1,
"optimizeCount": true
}
},
"createdAt": "text"
}
],
"suggestionsGeneratedAt": null,
"environmentGroups": [
{
"id": "text",
"name": "text",
"definition": "[Circular Reference]",
"createdAt": "text",
"createdBy": null,
"updatedAt": null,
"splitColumn": null,
"splitValue": null
}
],
"autoUpdate": {
"enabled": false,
"mode": "assimilate_only"
}
}
],
"pagination": {
"cursor": "text",
"hasMore": true,
"total": 1
}
}Creates a new digital twin and its first version (1.0.0). Body: name, type (static, temporal, multi-environment-temporal, multi-environment-static), optional tags, and the data to model: datasetId (a derived dataset) OR sourceId (model a raw source directly, no dataset required) — at most one of the two. Twin and version records are created in platform MongoDB only; no data-service call until discover, run-pipeline, or train. The response includes versionId for the initial version.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123staticPossible values: Successful response
Bad Request
Unauthorized
Forbidden
Not Found
Conflict
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 158
{
"name": "text",
"type": "static",
"tags": [
"text"
],
"datasetId": null,
"sourceId": null,
"selectedTimeColumnName": null,
"environmentColumns": [
"text"
],
"shardCount": null
}{
"data": {
"id": "text",
"organisationId": "text",
"workspaceId": "text",
"name": "text",
"normalizedName": null,
"type": "static",
"canonicalInputSchema": [
{
"field": "text",
"type": "None",
"subtype": "Integer",
"availableTypes": [
"None"
],
"isIndex": null,
"categories": [
"text"
],
"aliases": [
"text"
],
"description": null,
"displayWidth": null,
"originalFormat": null,
"displayFormat": null,
"unit": null,
"unitModifier": null,
"dateOrderAssumed": null
}
],
"tags": [
"text"
],
"status": "active",
"createdAt": "text",
"suggestedSimulations": [
{
"id": "text",
"name": "text",
"description": "text",
"scenario": {
"type": "text",
"objectives": [
{
"direction": "maximise",
"variable": "text",
"metricSqlQuery": "text",
"unit": {},
"weight": 1,
"variablesRelevantToMetric": [
"text"
],
"target": {
"type": "percentage",
"value": null
},
"conceptId": null,
"conceptEditVersion": 1
}
],
"conditions": [
{
"variable": "text",
"operator": "eq",
"value": 1
}
],
"decisionVars": [
"text"
],
"variableConstraints": [
{
"variable": "text",
"type": "range",
"minValue": null,
"maxValue": null,
"allowedValues": [
"text"
],
"maxChangePercent": 1,
"conditionalAllowedValues": [
{
"condition": {
"variable": "text",
"operator": "eq",
"value": 1
},
"allowedValues": [
"text"
],
"minValue": null,
"maxValue": null
}
]
}
],
"metricConstraints": [
{
"metricName": "text",
"sqlQuery": "text",
"constraintType": "min_value",
"value": null,
"booleanValue": null,
"temporal": {
"startDate": null,
"endDate": null,
"startTimestampMs": null,
"endTimestampMs": null,
"intervalSteps": null
}
}
],
"segmentDefinitions": [
{
"id": "text",
"description": null,
"conditions": [
{
"variable": "text",
"operator": "eq",
"value": 1
}
]
}
],
"enableSegmentInterventions": false,
"interventionTypes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"interventionCountConfig": {
"maxInterventions": 1,
"optimizeCount": true
}
},
"createdAt": "text"
}
],
"suggestionsGeneratedAt": null,
"environmentGroups": [
{
"id": "text",
"name": "text",
"definition": {
"mode": "columnValues",
"columnValues": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"environments": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
],
"statFilters": "[Circular Reference]",
"agreementThreshold": 1
},
"createdAt": "text",
"createdBy": null,
"updatedAt": null,
"splitColumn": null,
"splitValue": null
}
],
"autoUpdate": {
"enabled": false,
"mode": "assimilate_only"
},
"versionId": "text"
}
}Returns the digital twin by id from platform MongoDB. Must belong to the workspace. Includes canonicalInputSchema, suggestedSimulations.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Successful response
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": {
"id": "text",
"organisationId": "text",
"workspaceId": "text",
"name": "text",
"normalizedName": null,
"type": "static",
"canonicalInputSchema": [
{
"field": "text",
"type": "None",
"subtype": "Integer",
"availableTypes": [
"None"
],
"isIndex": null,
"categories": [
"text"
],
"aliases": [
"text"
],
"description": null,
"displayWidth": null,
"originalFormat": null,
"displayFormat": null,
"unit": null,
"unitModifier": null,
"dateOrderAssumed": null
}
],
"tags": [
"text"
],
"status": "active",
"createdAt": "text",
"suggestedSimulations": [
{
"id": "text",
"name": "text",
"description": "text",
"scenario": {
"type": "text",
"objectives": [
{
"direction": "maximise",
"variable": "text",
"metricSqlQuery": "text",
"unit": {},
"weight": 1,
"variablesRelevantToMetric": [
"text"
],
"target": {
"type": "percentage",
"value": null
},
"conceptId": null,
"conceptEditVersion": 1
}
],
"conditions": [
{
"variable": "text",
"operator": "eq",
"value": 1
}
],
"decisionVars": [
"text"
],
"variableConstraints": [
{
"variable": "text",
"type": "range",
"minValue": null,
"maxValue": null,
"allowedValues": [
"text"
],
"maxChangePercent": 1,
"conditionalAllowedValues": [
{
"condition": {
"variable": "text",
"operator": "eq",
"value": 1
},
"allowedValues": [
"text"
],
"minValue": null,
"maxValue": null
}
]
}
],
"metricConstraints": [
{
"metricName": "text",
"sqlQuery": "text",
"constraintType": "min_value",
"value": null,
"booleanValue": null,
"temporal": {
"startDate": null,
"endDate": null,
"startTimestampMs": null,
"endTimestampMs": null,
"intervalSteps": null
}
}
],
"segmentDefinitions": [
{
"id": "text",
"description": null,
"conditions": [
{
"variable": "text",
"operator": "eq",
"value": 1
}
]
}
],
"enableSegmentInterventions": false,
"interventionTypes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"interventionCountConfig": {
"maxInterventions": 1,
"optimizeCount": true
}
},
"createdAt": "text"
}
],
"suggestionsGeneratedAt": null,
"environmentGroups": [
{
"id": "text",
"name": "text",
"definition": {
"mode": "columnValues",
"columnValues": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"environments": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
],
"statFilters": "[Circular Reference]",
"agreementThreshold": 1
},
"createdAt": "text",
"createdBy": null,
"updatedAt": null,
"splitColumn": null,
"splitValue": null
}
],
"autoUpdate": {
"enabled": false,
"mode": "assimilate_only"
}
}
}Deletes the twin. Proxies DELETE to data-service so that data-service state (orchestrator, models, runs) is cleaned up; then the platform record would typically be removed by the caller or a follow-up. Requires digital-twins:delete and full permission.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123No Content
No content
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
DELETE /api/v1/workspaces/{wsId}/digital-twins/{id} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Updates name and/or tags. Only these fields are writable. Stored in platform MongoDB.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Successful response
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
PATCH /api/v1/workspaces/{wsId}/digital-twins/{id} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 31
{
"name": "text",
"tags": [
"text"
]
}{
"data": {
"id": "text",
"organisationId": "text",
"workspaceId": "text",
"name": "text",
"normalizedName": null,
"type": "static",
"canonicalInputSchema": [
{
"field": "text",
"type": "None",
"subtype": "Integer",
"availableTypes": [
"None"
],
"isIndex": null,
"categories": [
"text"
],
"aliases": [
"text"
],
"description": null,
"displayWidth": null,
"originalFormat": null,
"displayFormat": null,
"unit": null,
"unitModifier": null,
"dateOrderAssumed": null
}
],
"tags": [
"text"
],
"status": "active",
"createdAt": "text",
"suggestedSimulations": [
{
"id": "text",
"name": "text",
"description": "text",
"scenario": {
"type": "text",
"objectives": [
{
"direction": "maximise",
"variable": "text",
"metricSqlQuery": "text",
"unit": {},
"weight": 1,
"variablesRelevantToMetric": [
"text"
],
"target": {
"type": "percentage",
"value": null
},
"conceptId": null,
"conceptEditVersion": 1
}
],
"conditions": [
{
"variable": "text",
"operator": "eq",
"value": 1
}
],
"decisionVars": [
"text"
],
"variableConstraints": [
{
"variable": "text",
"type": "range",
"minValue": null,
"maxValue": null,
"allowedValues": [
"text"
],
"maxChangePercent": 1,
"conditionalAllowedValues": [
{
"condition": {
"variable": "text",
"operator": "eq",
"value": 1
},
"allowedValues": [
"text"
],
"minValue": null,
"maxValue": null
}
]
}
],
"metricConstraints": [
{
"metricName": "text",
"sqlQuery": "text",
"constraintType": "min_value",
"value": null,
"booleanValue": null,
"temporal": {
"startDate": null,
"endDate": null,
"startTimestampMs": null,
"endTimestampMs": null,
"intervalSteps": null
}
}
],
"segmentDefinitions": [
{
"id": "text",
"description": null,
"conditions": [
{
"variable": "text",
"operator": "eq",
"value": 1
}
]
}
],
"enableSegmentInterventions": false,
"interventionTypes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"interventionCountConfig": {
"maxInterventions": 1,
"optimizeCount": true
}
},
"createdAt": "text"
}
],
"suggestionsGeneratedAt": null,
"environmentGroups": [
{
"id": "text",
"name": "text",
"definition": {
"mode": "columnValues",
"columnValues": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"environments": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
],
"statFilters": "[Circular Reference]",
"agreementThreshold": 1
},
"createdAt": "text",
"createdBy": null,
"updatedAt": null,
"splitColumn": null,
"splitValue": null
}
],
"autoUpdate": {
"enabled": false,
"mode": "assimilate_only"
}
}
}Imports a digital twin from an export zip. Request body: raw zip bytes (Content-Type application/zip, filename via x-filename header, must contain twin.json). Max 512 MB on this route; larger imports go through the platform UI. Optional query param webhookUrl — POSTed once (best effort, unsigned) at the terminal state. Returns 202 with jobId; poll links.self. Requires digital-twins:write scope.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Called with the job result when the import reaches a terminal state.
exampleFilename to store the upload under
exampleRaw file bytes
Accepted; poll the linked resource for completion
Bad Request
Unauthorized
Forbidden
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/import HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
x-filename: text
Content-Type: application/zip
Accept: */*
{
"data": {
"jobId": "text",
"status": "text",
"createdAt": "text",
"links": {
"self": "text",
"cancel": "text"
}
}
}Multi-environment (panel) twins: returns the twin's saved environment groups. A group is a named, declarative rule over the twin's environment columns — mode columnValues (allowed values per environment column), environments (exact combos, each {column: value}), or statFilters (select environments by per-environment aggregates over any twin column). Groups belong to the twin, not to a version, so they survive retraining; their concrete membership only exists relative to a version and is computed by POST .../versions/{vId}/environment-groups/resolve. Single-environment twins have none.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Successful response
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id}/environment-groups HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"id": "text",
"name": "text",
"definition": {
"mode": "columnValues",
"columnValues": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"environments": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
],
"statFilters": {
"booleanOperator": "AND",
"filters": "[Circular Reference]"
},
"agreementThreshold": 1
},
"createdAt": "text",
"createdBy": null,
"updatedAt": null,
"splitColumn": null,
"splitValue": null
}
]
}Multi-environment (panel) twins: saves a named environment group on the twin. The id is minted server-side. Names are unique per twin and a twin is capped at 200 groups — both are 409 Conflict, not validation errors. The definition is stored verbatim and is not resolved here: a rule naming a column no version has is accepted and reports itself as unresolvable when resolved against a version. Resolve it with POST .../versions/{vId}/environment-groups/resolve, aggregate a scoped graph with POST .../versions/{vId}/graph/slice, or scope a run with environmentGroupIds on POST /simulations.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Display name; unique per twin
Successful response
Bad Request
Unauthorized
Forbidden
Not Found
Conflict
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/environment-groups HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 309
{
"name": "text",
"definition": {
"mode": "columnValues",
"columnValues": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"environments": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
],
"statFilters": {
"booleanOperator": "AND",
"filters": [
{
"column": "text",
"comparisonOperator": "text",
"value": "text",
"reduce": "value"
}
]
},
"agreementThreshold": 1
}
}{
"data": {
"id": "text",
"name": "text",
"definition": {
"mode": "columnValues",
"columnValues": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"environments": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
],
"statFilters": {
"booleanOperator": "AND",
"filters": [
{
"column": "text",
"comparisonOperator": "text",
"value": "text",
"reduce": "value"
}
]
},
"agreementThreshold": 1
},
"createdAt": "text",
"createdBy": null,
"updatedAt": null,
"splitColumn": null,
"splitValue": null
}
}Starts an async export of the digital twin as a portable zip: twin metadata, selected versions with their trained model params (full serialized parameters including tree ensembles), and optionally simulation runs. Body (all optional): includeRuns, versions (ids), environments (panel twins), webhookUrl (POSTed once, best effort, at the terminal state). Returns 202 with jobId; poll links.self and fetch links.download when completed. The zip round-trips through POST digital-twins/import.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Include simulation run artifacts in the export (default false)
Version ids to export; all versions when omitted
Panel twins: environment keys to export; all environments when omitted
Optional URL called once when the export completes
Accepted; poll the linked resource for completion
Bad Request
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/export HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 99
{
"includeRuns": true,
"versions": [
"text"
],
"environments": [
"text"
],
"webhookUrl": "https://example.com"
}{
"data": {
"jobId": "text",
"status": "text",
"createdAt": "text",
"links": {
"self": "text",
"cancel": "text"
}
}
}Lists all versions of this digital twin. Paginated (limit, cursor). Read from platform MongoDB (digitalTwinVersion collection). Versions carry lifecycleState, causalGraph, and the data they model as datasetId (a derived dataset) or sourceId (a raw source) — whichever the twin was created with.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Page size (1-1000, default 50).
1Opaque cursor from a previous response's pagination.cursor.
exampleSuccessful response
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id}/versions HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"id": "text",
"twinId": "text",
"organisationId": "text",
"workspaceId": "text",
"versionMajor": 1,
"versionMinor": 1,
"versionPatch": 1,
"version": null,
"createdAt": "text",
"createdBy": null,
"derivedFromVersionId": null,
"changelog": {
"temporalDependenciesDiffs": [
{
"type": "added",
"variable": "text",
"oldPrerequisites": [
"text"
],
"newPrerequisites": [
"text"
]
}
],
"fixedSubGraphDiffs": [
{
"type": "added",
"changeTarget": "relationships",
"relationship": {
"source": "text",
"target": "text",
"strength": 1,
"strengthStatus": "measured",
"timeLagEffects": [
{
"lag": 1,
"strength": 1,
"granularity": null
}
],
"cyclicalEffects": [
{
"frequency": "text",
"strength": 1
}
],
"confidence": null,
"agreementRate": null,
"isEnvironmentGated": false
}
}
],
"causalGraphDiffs": [
{
"type": "added",
"relationship": {
"source": "text",
"target": "text",
"strength": 1,
"strengthStatus": "measured",
"timeLagEffects": [
{
"lag": 1,
"strength": 1,
"granularity": null
}
],
"cyclicalEffects": [
{
"frequency": "text",
"strength": 1
}
],
"confidence": null,
"agreementRate": null,
"isEnvironmentGated": false
},
"oldRelationship": {
"source": "text",
"target": "text",
"strength": 1,
"strengthStatus": "measured",
"timeLagEffects": [
{
"lag": 1,
"strength": 1,
"granularity": null
}
],
"cyclicalEffects": [
{
"frequency": "text",
"strength": 1
}
],
"confidence": null,
"agreementRate": null,
"isEnvironmentGated": false
}
}
],
"nodesDiffs": [
{
"type": "added",
"node": {
"name": "text",
"nodeType": "observed",
"type": "None",
"categories": [
"text"
],
"latentClusterId": null,
"environmentColumns": [
"text"
],
"isDerived": false,
"symbolicEquation": {
"expression": "text",
"r2": 1,
"noisePercentage": 1,
"termBreakdown": [
{
"expression": "text",
"parentVariable": null,
"parentVariables": [
"text"
],
"coefficient": 1,
"operator": "text",
"contributionPercentage": 1
}
],
"complexity": 1,
"explanationType": "regression",
"epsilonSigma": null,
"epsilonSigmaRelative": null,
"expressionWithNoise": null,
"discoveryMethod": null,
"parentContributions": [
{
"parent": "text",
"contributionPct": 1,
"signedEffect": 1,
"direction": "positive",
"terms": [
"text"
],
"status": "included"
}
],
"unexplainedPct": null,
"directionReferenceClass": null,
"alternatives": [
{
"label": "text",
"expression": "text",
"r2": null,
"complexity": null
}
]
},
"derivedInfo": {
"derivedType": "text",
"targetColumn": "text",
"sourceColumns": [
"text"
],
"expression": "text",
"r2": null,
"isDeterministic": true,
"implausibilityReason": null,
"lag": null,
"cumulativeDirection": null,
"seasonalTerms": [
{
"period": 1,
"order": 1
}
],
"isMonotonicallyIncreasing": null,
"isMonotonicallyDecreasing": null
},
"parentImpacts": {
"node": "text",
"method": "forecast_attribution",
"parents": [
{
"parent": "text",
"impactPct": 1,
"signedEffect": 1,
"lagBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}
],
"exogenous": [
{
"parent": "text",
"impactPct": 1,
"signedEffect": 1,
"lagBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}
],
"nonParentShare": null
}
},
"oldNode": {
"name": "text",
"nodeType": "observed",
"type": "None",
"categories": [
"text"
],
"latentClusterId": null,
"environmentColumns": [
"text"
],
"isDerived": false,
"symbolicEquation": {
"expression": "text",
"r2": 1,
"noisePercentage": 1,
"termBreakdown": [
{
"expression": "text",
"parentVariable": null,
"parentVariables": [
"text"
],
"coefficient": 1,
"operator": "text",
"contributionPercentage": 1
}
],
"complexity": 1,
"explanationType": "regression",
"epsilonSigma": null,
"epsilonSigmaRelative": null,
"expressionWithNoise": null,
"discoveryMethod": null,
"parentContributions": [
{
"parent": "text",
"contributionPct": 1,
"signedEffect": 1,
"direction": "positive",
"terms": [
"text"
],
"status": "included"
}
],
"unexplainedPct": null,
"directionReferenceClass": null,
"alternatives": [
{
"label": "text",
"expression": "text",
"r2": null,
"complexity": null
}
]
},
"derivedInfo": {
"derivedType": "text",
"targetColumn": "text",
"sourceColumns": [
"text"
],
"expression": "text",
"r2": null,
"isDeterministic": true,
"implausibilityReason": null,
"lag": null,
"cumulativeDirection": null,
"seasonalTerms": [
{
"period": 1,
"order": 1
}
],
"isMonotonicallyIncreasing": null,
"isMonotonicallyDecreasing": null
},
"parentImpacts": {
"node": "text",
"method": "forecast_attribution",
"parents": [
{
"parent": "text",
"impactPct": 1,
"signedEffect": 1,
"lagBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}
],
"exogenous": [
{
"parent": "text",
"impactPct": 1,
"signedEffect": 1,
"lagBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}
],
"nonParentShare": null
}
}
}
],
"evaluationDiffs": [
{
"type": "improvement",
"metric": "text",
"oldValue": null,
"newValue": 1,
"percentChange": null
}
]
},
"datasetId": "text",
"type": "static",
"inputFields": [
{
"field": "text",
"type": "None",
"subtype": "Integer",
"availableTypes": [
"None"
],
"isIndex": null,
"categories": [
"text"
],
"aliases": [
"text"
],
"description": null,
"displayWidth": null,
"originalFormat": null,
"displayFormat": null,
"unit": null,
"unitModifier": null,
"dateOrderAssumed": null
}
],
"temporalDependencies": null,
"timeSeriesMetadata": {
"colName": "text",
"granularity": "ms",
"validGranularities": [
"text"
],
"startDate": "text",
"endDate": "text",
"typicalDeltaSeconds": null,
"selectedGrid": null,
"candidateGrids": [
"text"
],
"scoring": {
"ANY_ADDITIONAL_PROPERTY": {
"ANY_ADDITIONAL_PROPERTY": 1
}
},
"coverage": {
"observedSteps": 1,
"gridSteps": 1,
"imputedSteps": 1,
"gapCount": 1,
"gaps": [
{
"startDate": "text",
"endDate": "text",
"missingSteps": 1
}
]
}
},
"granularity": null,
"fixedSubGraph": {
"relationships": [
{
"source": "text",
"target": "text",
"strength": 1,
"strengthStatus": "measured",
"timeLagEffects": [
{
"lag": 1,
"strength": 1,
"granularity": null
}
],
"cyclicalEffects": [
{
"frequency": "text",
"strength": 1
}
],
"confidence": null,
"agreementRate": null,
"isEnvironmentGated": false
}
],
"antiRelationships": [
{
"source": "text",
"target": "text",
"strength": 1,
"strengthStatus": "measured",
"timeLagEffects": [
{
"lag": 1,
"strength": 1,
"granularity": null
}
],
"cyclicalEffects": [
{
"frequency": "text",
"strength": 1
}
],
"confidence": null,
"agreementRate": null,
"isEnvironmentGated": false
}
]
},
"variableRoles": {
"sources": [
"text"
],
"targets": [
"text"
]
},
"derivedColumns": [
{
"derivedType": "text",
"targetColumn": "text",
"sourceColumns": [
"text"
],
"expression": "text",
"r2": null,
"isDeterministic": true,
"implausibilityReason": null,
"lag": null,
"cumulativeDirection": null,
"seasonalTerms": [
{
"period": 1,
"order": 1
}
],
"isMonotonicallyIncreasing": null,
"isMonotonicallyDecreasing": null
}
],
"dataSignature": "text",
"configSignature": "text",
"nTrainSamples": null,
"causalGraph": [
{
"source": "text",
"target": "text",
"strength": 1,
"strengthStatus": "measured",
"timeLagEffects": [
{
"lag": 1,
"strength": 1,
"granularity": null
}
],
"cyclicalEffects": [
{
"frequency": "text",
"strength": 1
}
],
"confidence": null,
"agreementRate": null,
"isEnvironmentGated": false
}
],
"nodes": [
{
"name": "text",
"nodeType": "observed",
"type": "None",
"categories": [
"text"
],
"latentClusterId": null,
"environmentColumns": [
"text"
],
"isDerived": false,
"symbolicEquation": {
"expression": "text",
"r2": 1,
"noisePercentage": 1,
"termBreakdown": [
{
"expression": "text",
"parentVariable": null,
"parentVariables": [
"text"
],
"coefficient": 1,
"operator": "text",
"contributionPercentage": 1
}
],
"complexity": 1,
"explanationType": "regression",
"epsilonSigma": null,
"epsilonSigmaRelative": null,
"expressionWithNoise": null,
"discoveryMethod": null,
"parentContributions": [
{
"parent": "text",
"contributionPct": 1,
"signedEffect": 1,
"direction": "positive",
"terms": [
"text"
],
"status": "included"
}
],
"unexplainedPct": null,
"directionReferenceClass": null,
"alternatives": [
{
"label": "text",
"expression": "text",
"r2": null,
"complexity": null
}
]
},
"derivedInfo": {
"derivedType": "text",
"targetColumn": "text",
"sourceColumns": [
"text"
],
"expression": "text",
"r2": null,
"isDeterministic": true,
"implausibilityReason": null,
"lag": null,
"cumulativeDirection": null,
"seasonalTerms": [
{
"period": 1,
"order": 1
}
],
"isMonotonicallyIncreasing": null,
"isMonotonicallyDecreasing": null
},
"parentImpacts": {
"node": "text",
"method": "forecast_attribution",
"parents": [
{
"parent": "text",
"impactPct": 1,
"signedEffect": 1,
"lagBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}
],
"exogenous": [
{
"parent": "text",
"impactPct": 1,
"signedEffect": 1,
"lagBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}
],
"nonParentShare": null
}
}
],
"evaluation": {
"modelType": "cbn",
"nodeMetrics": {
"ANY_ADDITIONAL_PROPERTY": {
"accuracy": null,
"accuracyPerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"weightedAccuracy": null,
"falsePositiveRate": null,
"falseNegativeRate": null,
"truePositiveRate": null,
"trueNegativeRate": null,
"precision": null,
"recall": null,
"f1Score": null,
"precisionPerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"recallPerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"f1ScorePerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"positiveClassLabel": null,
"mse": null,
"r2": null,
"logLikelihood": null,
"auc": null,
"brierScore": null,
"mae": null,
"mape": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
},
"globalMetrics": {
"logLikelihood": null,
"averageMse": null,
"averageMae": null,
"averageAccuracy": null,
"averageMape": null
},
"skippedReason": "insufficient_data",
"skipReasons": [
"text"
],
"nEvalPoints": null
},
"panelEvaluation": {
"ANY_ADDITIONAL_PROPERTY": {
"modelType": "cbn",
"nodeMetrics": {
"ANY_ADDITIONAL_PROPERTY": {
"accuracy": null,
"accuracyPerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"weightedAccuracy": null,
"falsePositiveRate": null,
"falseNegativeRate": null,
"truePositiveRate": null,
"trueNegativeRate": null,
"precision": null,
"recall": null,
"f1Score": null,
"precisionPerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"recallPerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"f1ScorePerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"positiveClassLabel": null,
"mse": null,
"r2": null,
"logLikelihood": null,
"auc": null,
"brierScore": null,
"mae": null,
"mape": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
},
"globalMetrics": {
"logLikelihood": null,
"averageMse": null,
"averageMae": null,
"averageAccuracy": null,
"averageMape": null
},
"skippedReason": "insufficient_data",
"skipReasons": [
"text"
],
"nEvalPoints": null
}
},
"graphRecommendations": [
{
"x": "text",
"y": "text",
"direction": "forward",
"reasons": [
"text"
]
}
],
"environmentColumns": [
"text"
],
"selectedEnvironmentColumns": [
"text"
],
"selectedTimeColumnName": null,
"environmentSelection": {
"baseline": "all",
"exceptions": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
]
},
"extraOps": [
{
"id": "text",
"sourceId": "text",
"config": "[Circular Reference]"
}
],
"nEnvironments": null,
"latentClusters": [
{
"clusterId": 1,
"affectedNodes": [
"text"
],
"estimatedDim": 1,
"dicSatisfied": true,
"interColumnNames": [
"text"
],
"intraColumnNames": [
"text"
],
"modelStatus": "modelled",
"modelFailureReason": "tooFewMembers",
"modelFailureDetail": null,
"avgLcScore": null,
"reconstructionError": null,
"envPredictability": null,
"memberLatentShare": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"seasonalStrength": null
}
],
"latentDiscoveryConfig": {
"enabled": true,
"residualCorrelationThreshold": 0.3,
"ciTestAlpha": 0.05,
"minClusterSize": 2,
"maxLatentDim": 5
},
"nodeDomains": {
"ANY_ADDITIONAL_PROPERTY": {
"min": 1,
"max": 1
}
},
"lastTimestampMs": null,
"headCommit": 1,
"trainedWindowSignature": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"trainedWindowProfile": {
"ANY_ADDITIONAL_PROPERTY": {
"count": null,
"distinct": null,
"min": null,
"max": null
}
},
"resolvedInputs": [
{
"datasetId": "text",
"versionId": null,
"deltaVersion": 1
}
],
"updateEligibility": {
"updateMode": "assimilable",
"reasons": [
"text"
],
"newRows": null,
"fromTsMs": null,
"toTsMs": null,
"historyDiff": {
"changedColumns": [
{
"column": "text",
"stored": {
"count": null,
"distinct": null,
"min": null,
"max": null
},
"current": {
"count": null,
"distinct": null,
"min": null,
"max": null
}
}
],
"deltaOperations": [
{
"datasetId": "text",
"version": 1,
"operation": "text",
"timestampMs": null
}
],
"rewrittenDatasets": [
"text"
]
}
},
"trainingStages": {
"confounderModelling": true,
"equationDiscovery": true,
"lagScreening": null,
"evalHorizons": [
{
"count": 1,
"unit": "S"
}
]
},
"timeComponent": {
"models": {
"ANY_ADDITIONAL_PROPERTY": {
"theilSenSlope": 1,
"theilSenIntercept": 1,
"harmonic": {
"periodsWithHarmonics": [
[]
],
"sinCosCoefficients": [
1
],
"productPairs": [
[]
],
"productCoefficients": [
1
]
}
}
},
"varExplained": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"trainNSamples": 1
},
"causalAlgorithmVersion": null,
"digitalTwinAlgorithmVersion": null,
"shardCount": 1,
"maxLag": 1,
"layout": {
"success": true,
"positions": {
"ANY_ADDITIONAL_PROPERTY": {
"x": 1,
"y": 1
}
},
"edgeWaypoints": {
"ANY_ADDITIONAL_PROPERTY": {
"x": 1,
"y": 1
}
}
},
"lifecycleState": "created",
"currentTaskId": null,
"failureContext": {
"error": "text",
"failedAtStage": "causal_discovery",
"retryable": true,
"userFacing": false
},
"traces": {
"ANY_ADDITIONAL_PROPERTY": {
"start": null,
"end": null,
"name": null
}
},
"arrayFeatureMap": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"arrayFeatureToBase": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"pagination": {
"cursor": "text",
"hasMore": true,
"total": 1
}
}Derives a new version from an existing one — the retrain primitive. Body (all optional): bump (major | minor | patch, default patch), baseVersionId (default: the latest version), datasetId (point the new version at different data). The new version inherits the base's configuration and causal graph, resets all training outputs, and lands in lifecycleState resolved — train it with POST .../versions/{vId}/train. Version numbers never collide: the bumped component skips past any label already taken.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Which version component to bump (default patch)
patchPossible values: Version to derive from; the latest version when omitted
Point the new version at a different dataset
Successful response
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/versions HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54
{
"bump": "patch",
"baseVersionId": null,
"datasetId": null
}{
"data": {
"id": "text",
"twinId": "text",
"organisationId": "text",
"workspaceId": "text",
"versionMajor": 1,
"versionMinor": 1,
"versionPatch": 1,
"version": null,
"createdAt": "text",
"createdBy": null,
"derivedFromVersionId": null,
"changelog": {
"temporalDependenciesDiffs": [
{
"type": "added",
"variable": "text",
"oldPrerequisites": [
"text"
],
"newPrerequisites": [
"text"
]
}
],
"fixedSubGraphDiffs": [
{
"type": "added",
"changeTarget": "relationships",
"relationship": {
"source": "text",
"target": "text",
"strength": 1,
"strengthStatus": "measured",
"timeLagEffects": [
{
"lag": 1,
"strength": 1,
"granularity": null
}
],
"cyclicalEffects": [
{
"frequency": "text",
"strength": 1
}
],
"confidence": null,
"agreementRate": null,
"isEnvironmentGated": false
}
}
],
"causalGraphDiffs": [
{
"type": "added",
"relationship": {
"source": "text",
"target": "text",
"strength": 1,
"strengthStatus": "measured",
"timeLagEffects": [
{
"lag": 1,
"strength": 1,
"granularity": null
}
],
"cyclicalEffects": [
{
"frequency": "text",
"strength": 1
}
],
"confidence": null,
"agreementRate": null,
"isEnvironmentGated": false
},
"oldRelationship": {
"source": "text",
"target": "text",
"strength": 1,
"strengthStatus": "measured",
"timeLagEffects": [
{
"lag": 1,
"strength": 1,
"granularity": null
}
],
"cyclicalEffects": [
{
"frequency": "text",
"strength": 1
}
],
"confidence": null,
"agreementRate": null,
"isEnvironmentGated": false
}
}
],
"nodesDiffs": [
{
"type": "added",
"node": {
"name": "text",
"nodeType": "observed",
"type": "None",
"categories": [
"text"
],
"latentClusterId": null,
"environmentColumns": [
"text"
],
"isDerived": false,
"symbolicEquation": {
"expression": "text",
"r2": 1,
"noisePercentage": 1,
"termBreakdown": [
{
"expression": "text",
"parentVariable": null,
"parentVariables": [
"text"
],
"coefficient": 1,
"operator": "text",
"contributionPercentage": 1
}
],
"complexity": 1,
"explanationType": "regression",
"epsilonSigma": null,
"epsilonSigmaRelative": null,
"expressionWithNoise": null,
"discoveryMethod": null,
"parentContributions": [
{
"parent": "text",
"contributionPct": 1,
"signedEffect": 1,
"direction": "positive",
"terms": [
"text"
],
"status": "included"
}
],
"unexplainedPct": null,
"directionReferenceClass": null,
"alternatives": [
{
"label": "text",
"expression": "text",
"r2": null,
"complexity": null
}
]
},
"derivedInfo": {
"derivedType": "text",
"targetColumn": "text",
"sourceColumns": [
"text"
],
"expression": "text",
"r2": null,
"isDeterministic": true,
"implausibilityReason": null,
"lag": null,
"cumulativeDirection": null,
"seasonalTerms": [
{
"period": 1,
"order": 1
}
],
"isMonotonicallyIncreasing": null,
"isMonotonicallyDecreasing": null
},
"parentImpacts": {
"node": "text",
"method": "forecast_attribution",
"parents": [
{
"parent": "text",
"impactPct": 1,
"signedEffect": 1,
"lagBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}
],
"exogenous": [
{
"parent": "text",
"impactPct": 1,
"signedEffect": 1,
"lagBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}
],
"nonParentShare": null
}
},
"oldNode": {
"name": "text",
"nodeType": "observed",
"type": "None",
"categories": [
"text"
],
"latentClusterId": null,
"environmentColumns": [
"text"
],
"isDerived": false,
"symbolicEquation": {
"expression": "text",
"r2": 1,
"noisePercentage": 1,
"termBreakdown": [
{
"expression": "text",
"parentVariable": null,
"parentVariables": [
"text"
],
"coefficient": 1,
"operator": "text",
"contributionPercentage": 1
}
],
"complexity": 1,
"explanationType": "regression",
"epsilonSigma": null,
"epsilonSigmaRelative": null,
"expressionWithNoise": null,
"discoveryMethod": null,
"parentContributions": [
{
"parent": "text",
"contributionPct": 1,
"signedEffect": 1,
"direction": "positive",
"terms": [
"text"
],
"status": "included"
}
],
"unexplainedPct": null,
"directionReferenceClass": null,
"alternatives": [
{
"label": "text",
"expression": "text",
"r2": null,
"complexity": null
}
]
},
"derivedInfo": {
"derivedType": "text",
"targetColumn": "text",
"sourceColumns": [
"text"
],
"expression": "text",
"r2": null,
"isDeterministic": true,
"implausibilityReason": null,
"lag": null,
"cumulativeDirection": null,
"seasonalTerms": [
{
"period": 1,
"order": 1
}
],
"isMonotonicallyIncreasing": null,
"isMonotonicallyDecreasing": null
},
"parentImpacts": {
"node": "text",
"method": "forecast_attribution",
"parents": [
{
"parent": "text",
"impactPct": 1,
"signedEffect": 1,
"lagBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}
],
"exogenous": [
{
"parent": "text",
"impactPct": 1,
"signedEffect": 1,
"lagBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}
],
"nonParentShare": null
}
}
}
],
"evaluationDiffs": [
{
"type": "improvement",
"metric": "text",
"oldValue": null,
"newValue": 1,
"percentChange": null
}
]
},
"datasetId": "text",
"type": "static",
"inputFields": [
{
"field": "text",
"type": "None",
"subtype": "Integer",
"availableTypes": [
"None"
],
"isIndex": null,
"categories": [
"text"
],
"aliases": [
"text"
],
"description": null,
"displayWidth": null,
"originalFormat": null,
"displayFormat": null,
"unit": null,
"unitModifier": null,
"dateOrderAssumed": null
}
],
"temporalDependencies": null,
"timeSeriesMetadata": {
"colName": "text",
"granularity": "ms",
"validGranularities": [
"text"
],
"startDate": "text",
"endDate": "text",
"typicalDeltaSeconds": null,
"selectedGrid": null,
"candidateGrids": [
"text"
],
"scoring": {
"ANY_ADDITIONAL_PROPERTY": {
"ANY_ADDITIONAL_PROPERTY": 1
}
},
"coverage": {
"observedSteps": 1,
"gridSteps": 1,
"imputedSteps": 1,
"gapCount": 1,
"gaps": [
{
"startDate": "text",
"endDate": "text",
"missingSteps": 1
}
]
}
},
"granularity": null,
"fixedSubGraph": {
"relationships": [
{
"source": "text",
"target": "text",
"strength": 1,
"strengthStatus": "measured",
"timeLagEffects": [
{
"lag": 1,
"strength": 1,
"granularity": null
}
],
"cyclicalEffects": [
{
"frequency": "text",
"strength": 1
}
],
"confidence": null,
"agreementRate": null,
"isEnvironmentGated": false
}
],
"antiRelationships": [
{
"source": "text",
"target": "text",
"strength": 1,
"strengthStatus": "measured",
"timeLagEffects": [
{
"lag": 1,
"strength": 1,
"granularity": null
}
],
"cyclicalEffects": [
{
"frequency": "text",
"strength": 1
}
],
"confidence": null,
"agreementRate": null,
"isEnvironmentGated": false
}
]
},
"variableRoles": {
"sources": [
"text"
],
"targets": [
"text"
]
},
"derivedColumns": [
{
"derivedType": "text",
"targetColumn": "text",
"sourceColumns": [
"text"
],
"expression": "text",
"r2": null,
"isDeterministic": true,
"implausibilityReason": null,
"lag": null,
"cumulativeDirection": null,
"seasonalTerms": [
{
"period": 1,
"order": 1
}
],
"isMonotonicallyIncreasing": null,
"isMonotonicallyDecreasing": null
}
],
"dataSignature": "text",
"configSignature": "text",
"nTrainSamples": null,
"causalGraph": [
{
"source": "text",
"target": "text",
"strength": 1,
"strengthStatus": "measured",
"timeLagEffects": [
{
"lag": 1,
"strength": 1,
"granularity": null
}
],
"cyclicalEffects": [
{
"frequency": "text",
"strength": 1
}
],
"confidence": null,
"agreementRate": null,
"isEnvironmentGated": false
}
],
"nodes": [
{
"name": "text",
"nodeType": "observed",
"type": "None",
"categories": [
"text"
],
"latentClusterId": null,
"environmentColumns": [
"text"
],
"isDerived": false,
"symbolicEquation": {
"expression": "text",
"r2": 1,
"noisePercentage": 1,
"termBreakdown": [
{
"expression": "text",
"parentVariable": null,
"parentVariables": [
"text"
],
"coefficient": 1,
"operator": "text",
"contributionPercentage": 1
}
],
"complexity": 1,
"explanationType": "regression",
"epsilonSigma": null,
"epsilonSigmaRelative": null,
"expressionWithNoise": null,
"discoveryMethod": null,
"parentContributions": [
{
"parent": "text",
"contributionPct": 1,
"signedEffect": 1,
"direction": "positive",
"terms": [
"text"
],
"status": "included"
}
],
"unexplainedPct": null,
"directionReferenceClass": null,
"alternatives": [
{
"label": "text",
"expression": "text",
"r2": null,
"complexity": null
}
]
},
"derivedInfo": {
"derivedType": "text",
"targetColumn": "text",
"sourceColumns": [
"text"
],
"expression": "text",
"r2": null,
"isDeterministic": true,
"implausibilityReason": null,
"lag": null,
"cumulativeDirection": null,
"seasonalTerms": [
{
"period": 1,
"order": 1
}
],
"isMonotonicallyIncreasing": null,
"isMonotonicallyDecreasing": null
},
"parentImpacts": {
"node": "text",
"method": "forecast_attribution",
"parents": [
{
"parent": "text",
"impactPct": 1,
"signedEffect": 1,
"lagBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}
],
"exogenous": [
{
"parent": "text",
"impactPct": 1,
"signedEffect": 1,
"lagBreakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}
],
"nonParentShare": null
}
}
],
"evaluation": {
"modelType": "cbn",
"nodeMetrics": {
"ANY_ADDITIONAL_PROPERTY": {
"accuracy": null,
"accuracyPerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"weightedAccuracy": null,
"falsePositiveRate": null,
"falseNegativeRate": null,
"truePositiveRate": null,
"trueNegativeRate": null,
"precision": null,
"recall": null,
"f1Score": null,
"precisionPerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"recallPerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"f1ScorePerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"positiveClassLabel": null,
"mse": null,
"r2": null,
"logLikelihood": null,
"auc": null,
"brierScore": null,
"mae": null,
"mape": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
},
"globalMetrics": {
"logLikelihood": null,
"averageMse": null,
"averageMae": null,
"averageAccuracy": null,
"averageMape": null
},
"skippedReason": "insufficient_data",
"skipReasons": [
"text"
],
"nEvalPoints": null
},
"panelEvaluation": {
"ANY_ADDITIONAL_PROPERTY": {
"modelType": "cbn",
"nodeMetrics": {
"ANY_ADDITIONAL_PROPERTY": {
"accuracy": null,
"accuracyPerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"weightedAccuracy": null,
"falsePositiveRate": null,
"falseNegativeRate": null,
"truePositiveRate": null,
"trueNegativeRate": null,
"precision": null,
"recall": null,
"f1Score": null,
"precisionPerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"recallPerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"f1ScorePerClass": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"positiveClassLabel": null,
"mse": null,
"r2": null,
"logLikelihood": null,
"auc": null,
"brierScore": null,
"mae": null,
"mape": {
"ANY_ADDITIONAL_PROPERTY": null
}
}
},
"globalMetrics": {
"logLikelihood": null,
"averageMse": null,
"averageMae": null,
"averageAccuracy": null,
"averageMape": null
},
"skippedReason": "insufficient_data",
"skipReasons": [
"text"
],
"nEvalPoints": null
}
},
"graphRecommendations": [
{
"x": "text",
"y": "text",
"direction": "forward",
"reasons": [
"text"
]
}
],
"environmentColumns": [
"text"
],
"selectedEnvironmentColumns": [
"text"
],
"selectedTimeColumnName": null,
"environmentSelection": {
"baseline": "all",
"exceptions": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
]
},
"extraOps": [
{
"id": "text",
"sourceId": "text",
"config": "[Circular Reference]"
}
],
"nEnvironments": null,
"latentClusters": [
{
"clusterId": 1,
"affectedNodes": [
"text"
],
"estimatedDim": 1,
"dicSatisfied": true,
"interColumnNames": [
"text"
],
"intraColumnNames": [
"text"
],
"modelStatus": "modelled",
"modelFailureReason": "tooFewMembers",
"modelFailureDetail": null,
"avgLcScore": null,
"reconstructionError": null,
"envPredictability": null,
"memberLatentShare": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"seasonalStrength": null
}
],
"latentDiscoveryConfig": {
"enabled": true,
"residualCorrelationThreshold": 0.3,
"ciTestAlpha": 0.05,
"minClusterSize": 2,
"maxLatentDim": 5
},
"nodeDomains": {
"ANY_ADDITIONAL_PROPERTY": {
"min": 1,
"max": 1
}
},
"lastTimestampMs": null,
"headCommit": 1,
"trainedWindowSignature": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"trainedWindowProfile": {
"ANY_ADDITIONAL_PROPERTY": {
"count": null,
"distinct": null,
"min": null,
"max": null
}
},
"resolvedInputs": [
{
"datasetId": "text",
"versionId": null,
"deltaVersion": 1
}
],
"updateEligibility": {
"updateMode": "assimilable",
"reasons": [
"text"
],
"newRows": null,
"fromTsMs": null,
"toTsMs": null,
"historyDiff": {
"changedColumns": [
{
"column": "text",
"stored": {
"count": null,
"distinct": null,
"min": null,
"max": null
},
"current": {
"count": null,
"distinct": null,
"min": null,
"max": null
}
}
],
"deltaOperations": [
{
"datasetId": "text",
"version": 1,
"operation": "text",
"timestampMs": null
}
],
"rewrittenDatasets": [
"text"
]
}
},
"trainingStages": {
"confounderModelling": true,
"equationDiscovery": true,
"lagScreening": null,
"evalHorizons": [
{
"count": 1,
"unit": "S"
}
]
},
"timeComponent": {
"models": {
"ANY_ADDITIONAL_PROPERTY": {
"theilSenSlope": 1,
"theilSenIntercept": 1,
"harmonic": {
"periodsWithHarmonics": [
[]
],
"sinCosCoefficients": [
1
],
"productPairs": [
[]
],
"productCoefficients": [
1
]
}
}
},
"varExplained": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"trainNSamples": 1
},
"causalAlgorithmVersion": null,
"digitalTwinAlgorithmVersion": null,
"shardCount": 1,
"maxLag": 1,
"layout": {
"success": true,
"positions": {
"ANY_ADDITIONAL_PROPERTY": {
"x": 1,
"y": 1
}
},
"edgeWaypoints": {
"ANY_ADDITIONAL_PROPERTY": {
"x": 1,
"y": 1
}
}
},
"lifecycleState": "created",
"currentTaskId": null,
"failureContext": {
"error": "text",
"failedAtStage": "causal_discovery",
"retryable": true,
"userFacing": false
},
"traces": {
"ANY_ADDITIONAL_PROPERTY": {
"start": null,
"end": null,
"name": null
}
},
"arrayFeatureMap": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"arrayFeatureToBase": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
}Delete an environment group
Removes the group from the twin. Nothing downstream is deleted: simulation runs scoped to the group keep the membership frozen on their environmentGroupSnapshots, and any saved link to the group id simply stops resolving. 404 when the twin has no group with this id.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: groupId
123No Content
No content
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
DELETE /api/v1/workspaces/{wsId}/digital-twins/{id}/environment-groups/{groupId} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Update an environment group
Renames an environment group and/or replaces its membership rule. Send at least one of name or definition; a definition replaces the stored one wholesale rather than merging into it. Names stay unique per twin, so a colliding rename is 409 Conflict. Groups are twin-level, so the change applies to every version at once — a saved group is re-resolved against whichever version reads it next, and runs already submitted keep the membership frozen on their snapshots.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: groupId
123New display name; unique per twin
Successful response
Bad Request
Unauthorized
Forbidden
Not Found
Conflict
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
PATCH /api/v1/workspaces/{wsId}/digital-twins/{id}/environment-groups/{groupId} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 309
{
"name": "text",
"definition": {
"mode": "columnValues",
"columnValues": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"environments": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
],
"statFilters": {
"booleanOperator": "AND",
"filters": [
{
"column": "text",
"comparisonOperator": "text",
"value": "text",
"reduce": "value"
}
]
},
"agreementThreshold": 1
}
}{
"data": {
"id": "text",
"name": "text",
"definition": {
"mode": "columnValues",
"columnValues": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"environments": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
],
"statFilters": {
"booleanOperator": "AND",
"filters": [
{
"column": "text",
"comparisonOperator": "text",
"value": "text",
"reduce": "value"
}
]
},
"agreementThreshold": 1
},
"createdAt": "text",
"createdBy": null,
"updatedAt": null,
"splitColumn": null,
"splitValue": null
}
}Returns one version by id from platform MongoDB. Version must belong to this twin and workspace. Includes causalGraph, nodes, inputFields, lifecycleState, variableRoles, temporalDependencies, evaluation, and the data it models as datasetId or sourceId (matching how the twin was created).
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Deletes the version. Proxies DELETE to data-service so orchestrator/model state is removed; platform version record is not deleted by this route. Requires digital-twins:delete and full permission.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123No Content
No content
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
DELETE /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId} HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Download completed export
Streams the completed export zip (application/zip). 404 if the run does not exist in this workspace; 409 while the export job is still running. Requires exports:read scope.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: pipelineRunId
123Successful response
Payload not declared in this repo
Unauthorized
Forbidden
Not Found
Conflict
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id}/export/{pipelineRunId}/download HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Runs causal discovery for this version (infers causal graph from data). Proxies to data-service execute-causal-discovery. Returns 202 with jobId (pipelineRunId or workflowId) and links (self, cancel). Poll jobs/{jobId} for status; when complete, the version's causal graph is updated. Optional body: webhookUrl — POSTed once (best effort, unsigned) when the job reaches a terminal state; polling stays the source of truth.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Accepted; poll the linked resource for completion
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/discover HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19
{
"webhookUrl": null
}{
"data": {
"jobId": "text",
"status": "text",
"createdAt": "text",
"links": {
"self": "text",
"cancel": "text"
}
}
}List the version's environments
Multi-environment (panel) twins: returns environmentColumns and the environments the version's data contains — each with its envKey, column values, and sample size. Works before training (computed from the data, cached server-side). Use the envKeys to target specific environments in sample, intervene, and forecast calls.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/environments HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Returns evaluation and panelEvaluation for this version from platform MongoDB. No proxy; values are set when training or run-pipeline completes. Null if not yet evaluated.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/evaluation HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Returns the version's causal graph: relationships (edges), nodes, and fixedSubGraph (user-fixed edges/anti-edges). Read from platform MongoDB.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/graph HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Replaces the entire causal graph. Body: relationships (array of {source, target, strength?}), nodes (array of {name, nodeType, type}). Overwrites causalGraph and nodes in platform MongoDB. fixedSubGraph is left unchanged — pin or forbid edges through graph/fixed.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
PUT /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/graph HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 124
{
"relationships": [
{
"source": "text",
"target": "text",
"strength": 1
}
],
"nodes": [
{
"name": "text",
"nodeType": "text",
"type": "text"
}
]
}{
"data": "text"
}Returns learned or configured parameters for this version (e.g. model params). Proxies to data-service GET /api/digital-twin/{twinId}/version/{vId}/params. Only available after training or pipeline run.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/params HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Runs the full digital-twin pipeline: discovery (if needed), temporal dependencies, variable roles, training. Version must have a dataset (datasetId). Platform fetches the dataset schema and may auto-populate inputFields on the version if empty. Proxies to data-service execute-full-pipeline. Returns 202 with jobId and links (self, cancel). Poll jobs/{jobId} for completion. Optional body: webhookUrl — POSTed once (best effort, unsigned) at the terminal state.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Accepted; poll the linked resource for completion
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/run-pipeline HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19
{
"webhookUrl": null
}{
"data": {
"jobId": "text",
"status": "text",
"createdAt": "text",
"links": {
"self": "text",
"cancel": "text"
}
}
}Sample raw draws from the trained model
Runs conditional sampling in-process on the trained model and returns the raw joint posterior draws, columnar — the primitive every simulation family is built on. Body: spec (InterventionSpec | TimeSeriesInterventionSpec | PanelInterventionSpec with interventions, valueSpecs, and optional conditions), n (default 1000, max 100000), seed (panel twins derive stable per-environment child seeds from it). Non-panel twins answer {columns: {column: values}, n}; panel twins answer {environments: {envKey: {column: values}}, n}, each environment sampled independently. Version must be trained. Synchronous — no job to poll.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Number of joint posterior draws (default 1000)
Reproducibility seed. Panel twins derive a stable per-environment child seed from it.
Successful response
Payload not declared in this repo
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/sample HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 62
{
"spec": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"n": 1,
"seed": 1
}{
"data": "text"
}Generate scenario from natural-language query
Generates a structured simulation scenario from a natural-language query using the platform LLM (same generator as the New Simulation wizard's Generate from Query). Body: query, optional scenarioType. Proxies to data-service scenario-from-query. Returns the generated scenario plus a validation report; run it via POST simulations.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/scenario-from-query HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 36
{
"query": "text",
"scenarioType": null
}{
"data": "text"
}Batch counterfactual scoring: for each supplied row, the trained model finds the smallest set of changes that reaches the target outcome(s). Static trained twins only. Body: rows (≤500; keys name twin variables, a non-variable column becomes the row label), targets ([{variable, value, matchMode?}]), maxChanges (default 3), constraints, webhookUrl. Returns 202 with runId; read the verdicts back via GET simulations/{runId}/score once completed.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Most changes a counterfactual may make per row (default 3)
Optional URL called once when the run completes
Accepted; poll the linked resource for completion
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/score HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 253
{
"rows": [
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"targets": [
{
"variable": "text",
"value": null,
"matchMode": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"maxChanges": 1,
"constraints": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"webhookUrl": "https://example.com"
}{
"data": {
"runId": "text",
"status": "text",
"createdAt": "text",
"links": {
"self": "text",
"results": "text"
}
}
}Get temporal dependencies
Returns temporal dependencies for this version. If already stored on the version (platform MongoDB), returns that; otherwise computes them from the version's dataset via the data-service and returns the result (not persisted by this call).
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/temporal-dependencies HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Set temporal dependencies
Stores temporal dependencies in the version (platform MongoDB). Body: object as returned by GET. Used to override or persist computed dependencies.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
PUT /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/temporal-dependencies HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54
{
"prerequisites": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
}
}{
"data": "text"
}Starts training for this version. Proxies to data-service create-digital-twin (orchestrator). Returns 202 with jobId (pipelineRunId or workflowId) and links (self, cancel). Poll jobs/{jobId} for status. Optional body: webhookUrl — POSTed once (best effort, unsigned) at the terminal state.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Accepted; poll the linked resource for completion
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/train HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19
{
"webhookUrl": null
}{
"data": {
"jobId": "text",
"status": "text",
"createdAt": "text",
"links": {
"self": "text",
"cancel": "text"
}
}
}Check whether the model can assimilate new data
Reports whether update-model would find new data and whether it can be assimilated incrementally: pending row counts, drift signals, and the recommended action (update vs retrain). Read-only and cheap — orchestrators should call this before firing update-model.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/update-eligibility HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Assimilate new data into the trained model
Folds data added to the version's backing source or dataset since the last train/update into the trained model incrementally — no retrain. No request body: new data reaches the model by extending or syncing the source first, then calling this. Requires lifecycleState trained. The job SUCCEEDS with a terminal status rather than failing: committed (new rows folded in), up_to_date (nothing new), or retrain_required (the model cannot take these rows incrementally — the data drifted structurally, or the twin kind does not assimilate: static and temporal twins do out of the box, panel twins need the v2 panel engine, multi-environment-static does not; metadata.reasons says which). One update runs per version at a time; a concurrent call returns 409. Check GET update-eligibility first to know the likely outcome without starting a job. Optional body: webhookUrl — POSTed once (best effort, unsigned) at the terminal state.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Accepted; poll the linked resource for completion
Bad Request
Unauthorized
Forbidden
Not Found
Conflict
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/update-model HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19
{
"webhookUrl": null
}{
"data": {
"jobId": "text",
"status": "text",
"createdAt": "text",
"links": {
"self": "text",
"cancel": "text"
}
}
}Returns variable roles (input/target/etc.) for this version. If version.variableRoles exists in platform MongoDB, returns it; otherwise computes them from the version's dataset via the data-service (not persisted).
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/variable-roles HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Stores variable roles on the version (platform MongoDB). Body: record of variable role assignments. Overwrites existing variableRoles. Roles naming a variable outside the version's input fields are dropped, so the stored roles always describe the variables the version was trained on; the stored value is what the response returns.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
PUT /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/variable-roles HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 39
{
"sources": [
"text"
],
"targets": [
"text"
]
}{
"data": "text"
}Resolve an environment group against a version
Multi-environment (panel) twins: turns a group's declarative rule into the concrete environments it matches on this version. Send exactly one of groupId (a group saved on the twin) or definition (an ad-hoc rule, resolved without saving). Returns environmentColumns, the matching combos, their envKeys, sampleSize, totalEnvCount (environments this version has causal-discovery evidence for), unresolvedEnvCount, and — for statFilters rules — matchedBeforeEvidenceFilter, how many environments the filter selected in the data before intersecting with that evidence.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Id of a saved environment group on this twin
Successful response
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/environment-groups/resolve HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 312
{
"groupId": "text",
"definition": {
"mode": "columnValues",
"columnValues": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"environments": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
],
"statFilters": {
"booleanOperator": "AND",
"filters": [
{
"column": "text",
"comparisonOperator": "text",
"value": "text",
"reduce": "value"
}
]
},
"agreementThreshold": 1
}
}{
"data": {
"groupId": null,
"name": null,
"environmentColumns": [
"text"
],
"environments": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
],
"envKeys": [
"text"
],
"sampleSize": 1,
"totalEnvCount": 1,
"unresolvedEnvCount": 0,
"matchedBeforeEvidenceFilter": null,
"unresolvable": {
"reason": "noEnvironmentColumns",
"message": "text",
"columns": [
"text"
]
}
}
}Query environments by data statistics
Panel twins: resolves a stat-filter group to the concrete environments it matches — filter on ANY twin column, not just the environment columns, via per-environment aggregates (mean/min/max), constant values, or categorical presence (any). Returns environmentColumns, the matching environments as {column: value} combos, their envKeys, sampleSize, and totalEnvCount. Feed the combos to graph/slice or scope simulations with them. Example: {statFilters: {booleanOperator: "AND", filters: [{column: "revenue", reduce: "mean", comparisonOperator: ">", value: 400}]}}.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/environments/resolve HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 54
{
"statFilters": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}{
"data": {
"groupId": null,
"name": null,
"environmentColumns": [
"text"
],
"environments": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
],
"envKeys": [
"text"
],
"sampleSize": 1,
"totalEnvCount": 1,
"unresolvedEnvCount": 0,
"matchedBeforeEvidenceFilter": null,
"unresolvable": {
"reason": "noEnvironmentColumns",
"message": "text",
"columns": [
"text"
]
}
}
}Returns the version's fixed subgraph: relationships (edges pinned as present) and antiRelationships (edges forbidden). Empty arrays when nothing is fixed.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Unauthorized
Forbidden
Not Found
Too Many Requests; the response carries Retry-After
Internal Server Error
GET /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/graph/fixed HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": "text"
}Applies incremental domain knowledge to the fixed subgraph. Body: addEdges ([{source, target}]) pins edges as present; removeEdges ([{source, target}]) forbids them. Discovery and training respect the fixed subgraph on their next run. Returns the updated fixedSubGraph.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
PATCH /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/graph/fixed HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 98
{
"addEdges": [
{
"source": "text",
"target": "text"
}
],
"removeEdges": [
{
"source": "text",
"target": "text"
}
]
}{
"data": "text"
}Aggregate the causal graph over an environment subset
Panel twins: re-aggregates the causal graph over a subset of environments and returns that subset's adjacency — causalGraph (edges with strength and cross-environment agreement), nodes, envCount, sampleSize, totalEnvCount, and the agreementThreshold used. The subset is given either inline or by reference. Inline, mode picks the rule: environments (exact combos, each {column: value}), columnValues (allowed values per environment column), or statFilters (select environments by per-environment aggregates). By reference, send {groupId} naming a saved environment group on this twin (see GET .../environment-groups) and, optionally, an agreementThreshold that overrides the one stored on the group for this call. agreementThreshold (0-1, default 0.5) sets the share of environments an edge must hold in to survive. Computed from stored causal-discovery evidence — no retraining, read-only. 422 when the subset matches no environments with evidence; POST .../environment-groups/resolve answers the same question without the 422 when you only want the membership. List the environments first via GET .../environments.
An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one.
Path parameter: wsId
123Path parameter: id
123Path parameter: vId
123Successful response
Payload not declared in this repo
Bad Request
Unauthorized
Forbidden
Not Found
Unprocessable Entity
Too Many Requests; the response carries Retry-After
Internal Server Error
POST /api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/graph/slice HTTP/1.1
Host: sandbox.rootcause.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 203
{
"mode": "columnValues",
"columnValues": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"environments": [
{
"ANY_ADDITIONAL_PROPERTY": "text"
}
],
"statFilters": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"agreementThreshold": 1
}{
"data": "text"
}Last updated