{ "openapi": "3.1.0", "info": { "title": "RootCause Public API", "version": "1.0.0", "description": "Public REST API for the RootCause platform. Manage sources, datasets, ontology, digital twins, simulations, connectors, and reports.", "contact": { "name": "RootCause", "url": "https://rootcause.ai" } }, "servers": [ { "url": "https://sandbox.rootcause.ai", "description": "Sandbox" }, { "url": "https://platform.rootcause.ai", "description": "Production" }, { "url": "http://localhost:3000", "description": "Local development" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "An API key (pk_...) created on the Organisation API page, or an OAuth access token. Every operation requires one." } }, "schemas": { "ActionabilityEnum": { "type": "string", "enum": [ "actionable", "observable", "latent", "external" ] }, "AdjustProbabilitySpecSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "adjust_probability" }, "category": { "type": [ "string", "number", "boolean" ], "description": "The target category value whose probability will be adjusted." }, "delta": { "type": "number", "description": "Percentage-point shift (e.g. 10 means +10pp, -5 means -5pp)." } }, "required": [ "type", "category", "delta" ] }, "AggregateFunctionEnum": { "type": "string", "enum": [ "sum", "avg", "min", "max", "count", "countDistinct", "first", "last", "categoryShare" ] }, "AggregateModeEnum": { "type": "string", "enum": [ "sum", "avg", "min", "max" ] }, "AggregationFunctionSchema": { "type": "object", "properties": { "column": { "type": "string" }, "function": { "$ref": "#/components/schemas/AggregateFunctionEnum" }, "alias": { "type": [ "string", "null" ] }, "filter": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/FilterSchema" }, { "$ref": "#/components/schemas/FilterGroupSchema" } ] }, { "type": "null" } ] } }, "required": [ "column", "function" ] }, "AlertTypeEnum": { "type": "string", "enum": [ "spike", "worsening", "improving", "sustained", "normal" ] }, "AnchorLocationTypeEnum": { "type": "string", "enum": [ "latitude", "longitude", "coordinate", "country", "region", "city", "postal_code", "address", "continent", "airport_code", "unlocode" ] }, "anchorSqlCandidateSchema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "concept", "metric", "derived", "source", "dataset", "tag", "grain" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "score": { "type": "number", "default": 0 }, "syntax": { "type": [ "string", "null" ] } }, "required": [ "kind", "id", "name" ] }, "anchorSqlEnrichmentProgressSchema": { "type": "object", "properties": { "datasetId": { "type": "string" }, "datasetName": { "type": "string" }, "conceptId": { "type": "string" }, "conceptName": { "type": "string" }, "status": { "type": "string" }, "distinctTotal": { "type": [ "number", "null" ] }, "matchedCount": { "type": [ "number", "null" ] }, "unmatchedCount": { "type": [ "number", "null" ] } }, "required": [ "datasetId", "datasetName", "conceptId", "conceptName", "status" ] }, "anchorSqlErrorCodeSchema": { "type": "string", "minLength": 1 }, "anchorSqlErrorResponseSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "error": { "$ref": "#/components/schemas/anchorSqlStructuredErrorSchema" } }, "required": [ "ok", "error" ] }, "anchorSqlInvolvedConceptSchema": { "type": "object", "properties": { "conceptId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "referenced", "related", "anchor", "geo" ] } }, "required": [ "conceptId", "name", "role" ] }, "anchorSqlJoinPlanStepSchema": { "type": "object", "properties": { "sourceDatasetId": { "type": "string" }, "targetDatasetId": { "type": "string" }, "conceptName": { "type": "string" }, "strategy": { "type": "string", "minLength": 1 }, "fanout": { "type": [ "number", "null" ] } }, "required": [ "sourceDatasetId", "targetDatasetId", "conceptName", "strategy" ] }, "anchorSqlMetadataResponseSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "kind": { "type": "string", "const": "metadata" }, "command": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "rowCount": { "type": [ "number", "null" ] }, "totalRowCount": { "type": [ "number", "null" ] }, "truncated": { "type": "boolean", "default": false }, "nextStartKey": { "type": [ "number", "null" ] } }, "required": [ "ok", "kind", "command", "columns", "rows" ] }, "anchorSqlPerSourceDiagnosticSchema": { "type": "object", "properties": { "datasetId": { "type": "string" }, "datasetName": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "datasetId", "datasetName", "reason" ] }, "anchorSqlPlanChipSchema": { "type": "object", "properties": { "kind": { "type": "string", "minLength": 1 }, "label": { "type": "string" }, "detail": { "type": [ "string", "null" ] } }, "required": [ "kind", "label" ] }, "anchorSqlPlanSchema": { "type": "object", "properties": { "chips": { "type": "array", "items": { "$ref": "#/components/schemas/anchorSqlPlanChipSchema" }, "default": [] }, "joinPlan": { "type": "array", "items": { "$ref": "#/components/schemas/anchorSqlJoinPlanStepSchema" }, "default": [] }, "strategy": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } } }, "AnchorSqlResponseEnvelope": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/anchorSqlRowsResponseSchema" }, { "$ref": "#/components/schemas/anchorSqlMetadataResponseSchema" }, { "$ref": "#/components/schemas/anchorSqlValidatedResponseSchema" }, { "$ref": "#/components/schemas/anchorSqlErrorResponseSchema" } ], "description": "Anchor SQL result union, discriminated by `ok` and `kind`: rows (materialised result with nextStartKey paging), metadata (SHOW/DESCRIBE), validated (compile-only), or a structured compile error" } }, "required": [ "data" ] }, "anchorSqlRowsResponseSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "kind": { "type": "string", "const": "rows" }, "sql": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "rowCount": { "type": [ "number", "null" ] }, "totalRowCount": { "type": [ "number", "null" ] }, "truncated": { "type": "boolean", "default": false }, "nextStartKey": { "type": [ "number", "null" ] }, "schemaEntries": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "default": [] }, "units": { "type": "object", "additionalProperties": { "type": "string" }, "default": {} }, "plan": { "$ref": "#/components/schemas/anchorSqlPlanSchema", "default": {} }, "warnings": { "type": "array", "items": { "type": "string" }, "default": [] }, "dataViewId": { "type": [ "string", "null" ] }, "relatedColumns": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "involvedConcepts": { "type": "array", "items": { "$ref": "#/components/schemas/anchorSqlInvolvedConceptSchema" }, "default": [] } }, "required": [ "ok", "kind", "sql", "columns", "rows" ] }, "anchorSqlStructuredErrorSchema": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/anchorSqlErrorCodeSchema" }, "message": { "type": "string" }, "span": { "anyOf": [ { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] }, { "type": "null" } ] }, "perSource": { "type": "array", "items": { "$ref": "#/components/schemas/anchorSqlPerSourceDiagnosticSchema" }, "default": [] }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/anchorSqlCandidateSchema" }, "default": [] }, "suggestedQuery": { "type": [ "string", "null" ] }, "enrichmentProgress": { "type": "array", "items": { "$ref": "#/components/schemas/anchorSqlEnrichmentProgressSchema" }, "default": [] } }, "required": [ "code", "message" ] }, "anchorSqlValidatedResponseSchema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "kind": { "type": "string", "const": "validated" }, "sql": { "type": "string" }, "plan": { "$ref": "#/components/schemas/anchorSqlPlanSchema", "default": {} }, "warnings": { "type": "array", "items": { "type": "string" }, "default": [] }, "involvedConcepts": { "type": "array", "items": { "$ref": "#/components/schemas/anchorSqlInvolvedConceptSchema" }, "default": [] } }, "required": [ "ok", "kind", "sql" ] }, "AnomalyDetectionRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "anomaly_detection" }, "samples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ] }, "samplesRef": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" }, { "type": "null" } ] }, "targetFpr": { "type": "number", "minimum": 0.0001, "maximum": 0.1, "default": 0.005 }, "parentToleranceSigma": { "type": "number", "default": 0.5 }, "autoRca": { "type": "boolean", "default": true } }, "required": [ "type" ] }, "AnomalyDetectionResultSchema": { "type": "object", "properties": { "calibratedThresholds": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] }, "targetFpr": { "type": [ "number", "null" ] }, "totalSamplesScanned": { "type": "number" }, "samples": { "type": "array", "items": { "$ref": "#/components/schemas/SampleAnomalyScanResultSchema" }, "default": [] }, "executionTime": { "type": "number", "default": 0 } }, "required": [ "totalSamplesScanned" ] }, "AnomalyFlagResultSchema": { "type": "object", "properties": { "variable": { "type": "string" }, "conditionalZ": { "type": "number" }, "marginalZ": { "type": "number" }, "isRootNode": { "type": "boolean" }, "confidence": { "type": "number" }, "graphDepth": { "type": "number" }, "variableThreshold": { "type": [ "number", "null" ] } }, "required": [ "variable", "conditionalZ", "marginalZ", "isRootNode", "confidence", "graphDepth" ] }, "Application": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": [ "string", "null" ] }, "organisationId": { "type": "string" }, "name": { "type": "string" }, "date": { "type": [ "string", "null" ] }, "lastSaved": { "type": [ "string", "null" ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "description": { "type": [ "string", "null" ] }, "access": { "anyOf": [ { "type": "string", "enum": [ "public", "private", "restricted", "organisation" ] }, { "type": "null" } ] }, "parentId": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] }, "deployedAt": { "type": [ "string", "null" ] }, "building": { "type": [ "boolean", "null" ] }, "status": { "type": "string", "enum": [ "Running", "Idle", "Failed" ] }, "isLive": { "type": [ "boolean", "null" ] }, "type": { "anyOf": [ { "type": "string", "enum": [ "dashboard", "api", "automation", "ai" ] }, { "type": "null" } ] }, "kind": { "anyOf": [ { "type": "string", "enum": [ "user", "system" ] }, { "type": "null" } ] }, "slug": { "type": [ "string", "null" ] }, "lifecycleStatus": { "anyOf": [ { "type": "string", "enum": [ "draft", "published", "archived" ] }, { "type": "null" } ] }, "publish": { "anyOf": [ { "type": "object", "properties": { "slug": { "type": [ "string", "null" ] }, "publishedAt": { "type": [ "string", "null" ] }, "publishedVersion": { "type": [ "string", "null" ] }, "surfaces": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "rest", "ui", "agent", "schedule", "webhook", "subapp" ] } }, { "type": "null" } ] }, "consumerAccess": { "anyOf": [ { "type": "string", "enum": [ "private", "workspace", "organisation", "public" ] }, { "type": "null" } ] }, "embedOrigins": { "type": "array", "items": { "type": "string" } }, "notes": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "settings": { "anyOf": [ { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "exposedTerminals": { "type": "array", "items": { "type": "object", "properties": { "moduleId": { "type": [ "string", "null" ] }, "portId": { "type": [ "string", "null" ] }, "widgetId": { "type": "string" }, "direction": { "type": "string", "enum": [ "in", "out" ] }, "kind": { "type": "string", "enum": [ "dataframe", "scalar", "json", "text", "document", "image", "binary", "signal", "event" ] }, "label": { "type": "string" } }, "required": [ "widgetId", "direction", "kind", "label" ] } }, "embeddablePages": { "type": "array", "items": { "type": "string" } }, "emittedEvents": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "payloadSchema": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "description": { "type": "string", "default": "" } }, "required": [ "name" ] } }, "agent": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "instructions": { "type": "string", "default": "" }, "tools": { "type": "array", "items": { "type": "string", "enum": [ "app_describe", "app_read_terminal", "app_query_indicator", "app_list_flows", "app_run_status", "app_read_contract_object", "app_read_state", "app_list_links", "app_explain_module", "app_press_button", "app_set_control", "app_open_page" ] }, "default": [ "app_describe", "app_read_terminal", "app_query_indicator", "app_list_flows", "app_run_status", "app_read_contract_object", "app_read_state", "app_list_links", "app_explain_module", "app_press_button", "app_set_control", "app_open_page" ] }, "canPress": { "type": "array", "items": { "type": "string" }, "default": [] }, "knowledge": { "type": "array", "items": { "type": "string" }, "default": [] }, "model": { "type": [ "string", "null" ], "default": null } } } } }, { "type": "null" } ] } }, "required": [ "id", "organisationId", "name", "status" ] }, "ApplicationEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Application" } }, "required": [ "data" ] }, "ApplicationListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Pass back as ?cursor= to fetch the next page" }, "hasMore": { "type": "boolean", "description": "Whether a further page exists" }, "total": { "type": "number", "description": "Total matching rows, when the query can count them" } }, "required": [ "hasMore" ] } }, "required": [ "data", "pagination" ] }, "ArrayAggregationKindEnum": { "type": "string", "enum": [ "mean", "sum", "min", "max", "median", "count" ] }, "ArrayDecomposeModeEnum": { "type": "string", "enum": [ "position", "one_hot" ] }, "ArraySizeDistributionSchema": { "type": "object", "properties": { "empty": { "type": "number", "default": 0 }, "oneToThree": { "type": "number", "default": 0 }, "fourToTen": { "type": "number", "default": 0 }, "elevenToFifty": { "type": "number", "default": 0 }, "fiftyPlus": { "type": "number", "default": 0 } } }, "AsOfDirectionEnum": { "type": "string", "enum": [ "backward", "forward", "nearest" ] }, "AsyncJobAccepted": { "type": "object", "properties": { "data": { "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "description": "pending until the job reaches a terminal status" }, "createdAt": { "type": "string" }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "Poll this until the status is terminal" }, "cancel": { "type": "string" } }, "required": [ "self" ] } }, "required": [ "jobId", "status", "links" ], "description": "Envelope for asynchronous pipeline work. Poll links.self until the job reaches a terminal status." } }, "required": [ "data" ] }, "AsyncRunAccepted": { "type": "object", "properties": { "data": { "type": "object", "properties": { "runId": { "type": "string" }, "status": { "type": "string", "description": "pending until the run reaches a terminal status" }, "createdAt": { "type": "string" }, "links": { "type": "object", "properties": { "self": { "type": "string", "description": "Poll this until the status is terminal" }, "results": { "type": "string", "description": "Fetch when the run completes" } }, "required": [ "self" ] } }, "required": [ "runId", "status", "links" ], "description": "Envelope for asynchronous simulation runs. Poll links.self; fetch links.results when complete." } }, "required": [ "data" ] }, "AutoUpdateSettingsSchema": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "mode": { "type": "string", "enum": [ "assimilate_only", "assimilate_or_retrain" ], "default": "assimilate_only" } } }, "BinaryUpload": { "description": "Raw file bytes" }, "BindingSourceEnum": { "type": "string", "enum": [ "ingest", "statistical", "llm", "user", "install" ] }, "BindingStatusEnum": { "type": "string", "enum": [ "confirmed", "suggested" ] }, "BrokenDataViewDependencySchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DATASET", "DATA_VIEW" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "type", "id", "name" ] }, "CategoricalPredictionRecordSchema": { "type": "object", "properties": { "timestamp": { "type": [ "number", "null" ], "description": "Timestamp of the prediction" }, "prediction": { "description": "Predicted class (most likely) in decoded format" }, "probabilities": { "type": "array", "items": { "type": "number" }, "description": "Raw predicted probabilities for each class" }, "lowerBound": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ], "description": "Lower bounds of confidence intervals for probabilities" }, "upperBound": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ], "description": "Upper bounds of confidence intervals for probabilities" }, "confidenceLevel": { "type": [ "number", "null" ], "description": "Confidence level for bounds" } }, "required": [ "probabilities" ] }, "CategoricalSeasonalPeriodSchema": { "type": "object", "properties": { "periodSeconds": { "type": "number" }, "cycleLabel": { "type": [ "string", "null" ] }, "nPhaseBins": { "type": "number" }, "cramersV": { "type": "number" }, "chi2PerDof": { "type": [ "number", "null" ] }, "phaseDistribution": { "anyOf": [ { "type": "array", "items": { "type": "array", "items": { "type": "number" } } }, { "type": "null" } ] }, "levels": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "periodSeconds", "nPhaseBins", "cramersV" ] }, "CausalAlertEntryResultSchema": { "type": "object", "properties": { "variable": { "type": "string" }, "causalDepth": { "type": "number" }, "firstAlertStep": { "type": "number" }, "alertType": { "$ref": "#/components/schemas/AlertTypeEnum" }, "ewmaZ": { "type": "number" } }, "required": [ "variable", "causalDepth", "firstAlertStep", "alertType", "ewmaZ" ] }, "CausalEdgeResultSchema": { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" } }, "required": [ "source", "target" ] }, "CausalGraphChangeSchema": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ChangeTypeEnum" }, "relationship": { "$ref": "#/components/schemas/CausalRelationshipSchema" }, "oldRelationship": { "anyOf": [ { "$ref": "#/components/schemas/CausalRelationshipSchema" }, { "type": "null" } ] } }, "required": [ "type", "relationship" ] }, "CausalHealthMonitorRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "causal_health_monitor" }, "dataSource": { "$ref": "#/components/schemas/ChmDataSourceSchema", "default": "observed" }, "samples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ] }, "samplesRef": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" }, { "type": "null" } ] }, "forecastHorizon": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "startStep": { "type": [ "number", "null" ] }, "endStep": { "type": [ "number", "null" ] }, "targetFpr": { "type": "number", "minimum": 0.0001, "maximum": 0.1, "default": 0.005 }, "parentToleranceSigma": { "type": "number", "default": 0.5 }, "autoRca": { "type": "boolean", "default": true } }, "required": [ "type" ] }, "CausalHealthMonitorResultSchema": { "type": "object", "properties": { "dataSource": { "$ref": "#/components/schemas/ChmDataSourceSchema", "default": "observed" }, "totalTimestepsScanned": { "type": "number" }, "startTimestampMs": { "type": [ "number", "null" ] }, "granularityMs": { "type": [ "number", "null" ] }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/ConditionScanTimestepResultSchema" } }, "nodeSummaries": { "type": "array", "items": { "$ref": "#/components/schemas/NodeConditionStatusResultSchema" } }, "causalAlertOrdering": { "type": "array", "items": { "$ref": "#/components/schemas/CausalAlertEntryResultSchema" }, "default": [] }, "autoRca": { "anyOf": [ { "$ref": "#/components/schemas/SampleRcaResultSchema" }, { "type": "null" } ] }, "calibratedThresholds": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] }, "targetFpr": { "type": [ "number", "null" ] }, "eventLog": { "type": "array", "items": { "$ref": "#/components/schemas/EventLogEntryResultSchema" }, "default": [] }, "leadLag": { "type": "array", "items": { "$ref": "#/components/schemas/LeadLagEntryResultSchema" }, "default": [] }, "edgePropagation": { "type": "array", "items": { "$ref": "#/components/schemas/EdgePropagationSeriesResultSchema" }, "default": [] }, "forecastedSamples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ] }, "causalEdges": { "type": "array", "items": { "$ref": "#/components/schemas/CausalEdgeResultSchema" }, "default": [] }, "executionTime": { "type": "number", "default": 0 } }, "required": [ "totalTimestepsScanned", "timeline", "nodeSummaries" ] }, "CausalNodeSchema": { "type": "object", "properties": { "name": { "type": "string" }, "nodeType": { "$ref": "#/components/schemas/NodeTypeEnum", "default": "observed" }, "type": { "$ref": "#/components/schemas/SchemaMainTypeEnum" }, "categories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "latentClusterId": { "type": [ "number", "null" ] }, "environmentColumns": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "isDerived": { "type": "boolean", "default": false }, "symbolicEquation": { "anyOf": [ { "$ref": "#/components/schemas/SymbolicEquationSchema" }, { "type": "null" } ] }, "derivedInfo": { "anyOf": [ { "$ref": "#/components/schemas/DtDerivedColumnInfoSchema" }, { "type": "null" } ] }, "parentImpacts": { "anyOf": [ { "$ref": "#/components/schemas/NodeParentImpactsSchema" }, { "type": "null" } ], "description": "Model-based driver contribution shares computed after training" } }, "required": [ "name", "type" ] }, "CausalRelationshipAnalysisSchema": { "type": "object", "properties": { "causeVar": { "type": "string", "description": "The cause variable" }, "effectVar": { "type": "string", "description": "The effect variable" }, "overallEffect": { "type": "object", "properties": { "effectSize": { "type": "number", "description": "Average causal effect size" }, "effectRange": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ], "description": "Min and max effect across tested values" }, "confidenceInterval": { "type": "array", "items": { "type": "number" }, "description": "95% confidence interval for the effect" }, "statisticalSignificance": { "type": "number", "description": "P-value for statistical significance" }, "categoryEffects": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "Effects by category (for categorical causes)" }, "targetEffects": { "type": "array", "items": { "$ref": "#/components/schemas/TargetEffectSchema" }, "description": "Effects for specific target values" }, "baselineOutcomeProbs": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "Baseline outcome probabilities" }, "targetOutcomeDeltas": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "number" } } }, { "type": "null" } ], "description": "Changes in outcome probabilities" }, "contrast": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "numeric", "categorical" ] }, "causeRef": { "anyOf": [ { "type": [ "string", "number" ] }, { "type": "null" } ] }, "causeTarget": { "anyOf": [ { "type": [ "string", "number" ] }, { "type": "null" } ] }, "contrastType": { "type": "string" } }, "required": [ "type", "contrastType" ], "description": "Contrast specification" }, "nReplicates": { "type": "number", "description": "Number of replicates" }, "effectiveSampleSize": { "type": "number", "description": "Effective sample size" }, "summaryMethod": { "type": "string", "description": "Method used to summarize effects" } }, "required": [ "effectSize", "confidenceInterval", "statisticalSignificance", "targetEffects", "contrast", "nReplicates", "effectiveSampleSize", "summaryMethod" ], "description": "Overall causal effect analysis" }, "doseResponse": { "anyOf": [ { "$ref": "#/components/schemas/DoseResponseAnalysisSchema" }, { "type": "null" } ], "description": "Dose-response curve (for continuous causes)" }, "segmentEffects": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentExplanationEffectSchema" }, "description": "Effects by segment" }, "pathwayEffects": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "qualitative", "additive" ], "description": "Analysis mode" }, "directEffect": { "type": [ "number", "null" ], "description": "Direct effect if variables are connected" }, "indirectEffects": { "type": "array", "items": { "$ref": "#/components/schemas/PathwayEffectSchema" }, "description": "Effects through indirect pathways" }, "totalEffect": { "type": [ "number", "null" ], "description": "Sum of all pathway effects" }, "sumToOverall": { "type": "boolean", "description": "Whether pathway effects sum to overall effect" } }, "required": [ "mode", "indirectEffects", "sumToOverall" ], "description": "Analysis of causal pathways" }, "units": { "type": "string", "enum": [ "probability", "value" ], "description": "Units of the effect measurement" }, "summaryMethod": { "type": "string", "description": "Method used to summarize the analysis" } }, "required": [ "causeVar", "effectVar", "overallEffect", "segmentEffects", "pathwayEffects", "units", "summaryMethod" ] }, "CausalRelationshipSchema": { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" }, "strength": { "type": "number" }, "strengthStatus": { "anyOf": [ { "type": "string", "enum": [ "measured", "not_measured" ] }, { "type": "null" } ] }, "timeLagEffects": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "lag": { "type": "number" }, "strength": { "type": "number" }, "granularity": { "type": [ "string", "null" ] } }, "required": [ "lag", "strength" ] } }, { "type": "null" } ] }, "cyclicalEffects": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "frequency": { "type": "string" }, "strength": { "type": "number" } }, "required": [ "frequency", "strength" ] } }, { "type": "null" } ] }, "confidence": { "type": [ "number", "null" ] }, "agreementRate": { "type": [ "number", "null" ] }, "isEnvironmentGated": { "type": "boolean", "default": false } }, "required": [ "source", "target", "strength" ] }, "ChangeLogSchema": { "type": "object", "properties": { "temporalDependenciesDiffs": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TemporalDependencyChangeSchema" } }, { "type": "null" } ] }, "fixedSubGraphDiffs": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/FixedSubGraphChangeSchema" } }, { "type": "null" } ] }, "causalGraphDiffs": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CausalGraphChangeSchema" } }, { "type": "null" } ] }, "nodesDiffs": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/NodeChangeSchema" } }, { "type": "null" } ] }, "evaluationDiffs": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/EvaluationChangeSchema" } }, { "type": "null" } ] } } }, "ChangeTypeEnum": { "type": "string", "enum": [ "added", "removed", "modified" ] }, "ChmDataSourceSchema": { "type": "string", "enum": [ "observed", "forecast" ] }, "ColumnMetadataSchema": { "type": "object", "properties": { "dtype": { "type": [ "string", "null" ] }, "categoryOccurences": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] }, "distribution": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] }, "rangeFrom": { "anyOf": [ { "type": [ "string", "number" ] }, { "type": "null" } ] }, "rangeTo": { "anyOf": [ { "type": [ "string", "number" ] }, { "type": "null" } ] }, "mean": { "type": [ "number", "null" ] }, "stringPattern": { "type": [ "string", "null" ] }, "jsonObjectFraction": { "type": [ "number", "null" ] }, "cardinality": { "type": [ "number", "null" ] }, "nullFraction": { "type": [ "number", "null" ] }, "unparsedFormat": { "type": [ "string", "null" ] }, "processing": { "type": [ "boolean", "null" ] }, "metadataStatus": { "anyOf": [ { "$ref": "#/components/schemas/MetadataStatusEnum" }, { "type": "null" } ] }, "elementType": { "anyOf": [ { "$ref": "#/components/schemas/SchemaMainTypeEnum" }, { "type": "null" } ] }, "minSize": { "type": [ "number", "null" ] }, "maxSize": { "type": [ "number", "null" ] }, "avgSize": { "type": [ "number", "null" ] }, "medianSize": { "type": [ "number", "null" ] }, "p95Size": { "type": [ "number", "null" ] }, "nullCount": { "type": [ "number", "null" ] }, "emptyCount": { "type": [ "number", "null" ] }, "totalElementCount": { "type": [ "number", "null" ] }, "sizeDistribution": { "anyOf": [ { "$ref": "#/components/schemas/ArraySizeDistributionSchema" }, { "type": "null" } ] }, "uniqueElementCount": { "type": [ "number", "null" ] }, "avgUniquePerRow": { "type": [ "number", "null" ] }, "elementOccurences": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] }, "elementMin": { "type": [ "number", "null" ] }, "elementMax": { "type": [ "number", "null" ] }, "elementMean": { "type": [ "number", "null" ] }, "elementSum": { "type": [ "number", "null" ] }, "elementStddev": { "type": [ "number", "null" ] } } }, "ColumnWindowProfileSchema": { "type": "object", "properties": { "count": { "type": [ "number", "null" ] }, "distinct": { "type": [ "number", "null" ] }, "min": { "type": [ "string", "null" ] }, "max": { "type": [ "string", "null" ] } } }, "ComparisonOperatorEnum": { "type": "string", "enum": [ "Equal to", "Not Equal to", "Contains", "Does not contain", "Starts with", "Ends with", "Is Empty", "Is not Empty", "Less than", "Greater than", "Less than or equal to", "Greater than or equal to", "Before", "After", "Array contains", "Array contains any", "Array contains all", "Array does not contain", "Array does not contain any", "Array does not contain all", "Array size equal to", "Array size greater than", "Array size less than" ] }, "ConceptClassificationEnum": { "type": "string", "enum": [ "identifier", "location", "time" ] }, "ConceptKindEnum": { "type": "string", "enum": [ "standard", "derived", "metric" ] }, "ConceptMetadataSchema": { "type": "object", "properties": { "categories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "minValue": { "type": [ "number", "null" ] }, "maxValue": { "type": [ "number", "null" ] }, "isMonotonicallyIncreasing": { "type": [ "boolean", "null" ] }, "isMonotonicallyDecreasing": { "type": [ "boolean", "null" ] }, "isUnique": { "type": [ "boolean", "null" ] }, "isCyclic": { "type": [ "boolean", "null" ] }, "isHeterogeneousIdentifier": { "type": [ "boolean", "null" ] }, "compositeScopeConceptId": { "type": [ "string", "null" ] }, "isUniformDistribution": { "type": [ "boolean", "null" ] }, "locationType": { "anyOf": [ { "$ref": "#/components/schemas/AnchorLocationTypeEnum" }, { "type": "null" } ] }, "coordinateFormat": { "anyOf": [ { "$ref": "#/components/schemas/CoordinateFormatEnum" }, { "type": "null" } ] }, "coordinateDatum": { "anyOf": [ { "$ref": "#/components/schemas/CoordinateDatumEnum" }, { "type": "null" } ] }, "coordinatePairConceptId": { "type": [ "string", "null" ] }, "locationDetectionSource": { "anyOf": [ { "$ref": "#/components/schemas/LocationDetectionSourceEnum" }, { "type": "null" } ] }, "latitudeInRangeFraction": { "type": [ "number", "null" ] }, "longitudeInRangeFraction": { "type": [ "number", "null" ] }, "fractionalPartFraction": { "type": [ "number", "null" ] }, "coordinatePairFraction": { "type": [ "number", "null" ] }, "dmsCoordinateFraction": { "type": [ "number", "null" ] }, "postalCodeFraction": { "type": [ "number", "null" ] }, "addressShapeFraction": { "type": [ "number", "null" ] }, "enrichments": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/EnrichmentRecordSchema" } }, { "type": "null" } ] }, "geoEnrichmentStatus": { "anyOf": [ { "$ref": "#/components/schemas/GeoEnrichmentStatusEnum" }, { "type": "null" } ] }, "geoEnrichmentKind": { "anyOf": [ { "$ref": "#/components/schemas/GeoEnrichmentKindEnum" }, { "type": "null" } ] }, "geoEnrichedAt": { "type": [ "string", "null" ] }, "geoEnrichmentVersion": { "type": [ "number", "null" ] }, "geoSidecarKey": { "type": [ "string", "null" ] }, "geoDistinctTotal": { "type": [ "number", "null" ] }, "geoMatchedCount": { "type": [ "number", "null" ] }, "geoUnmatchedCount": { "type": [ "number", "null" ] }, "geoTruncated": { "type": [ "boolean", "null" ] }, "geoEnrichmentError": { "type": [ "string", "null" ] }, "nanFillStrategy": { "anyOf": [ { "$ref": "#/components/schemas/NanFillStrategyEnum" }, { "type": "null" } ] }, "changeRate": { "type": [ "number", "null" ] }, "dateTimeFormat": { "type": [ "string", "null" ] }, "displayFormat": { "type": [ "string", "null" ] }, "averageInterval": { "type": [ "number", "null" ] }, "isConsistentInterval": { "type": [ "boolean", "null" ] }, "unit": { "type": [ "string", "null" ] }, "unitModifier": { "type": [ "number", "null" ] }, "higherIsBetter": { "type": [ "boolean", "null" ] }, "isEqualInterval": { "type": [ "boolean", "null" ] }, "intervalSize": { "type": [ "number", "null" ] }, "valueClass": { "anyOf": [ { "$ref": "#/components/schemas/ValueClassEnum" }, { "type": "null" } ] }, "fracZero": { "type": [ "number", "null" ] }, "zeroRunLengthP95": { "type": [ "number", "null" ] }, "nonZeroRunLengthP95": { "type": [ "number", "null" ] }, "trendSlopePerSecond": { "type": [ "number", "null" ] }, "trendR2": { "type": [ "number", "null" ] }, "emailFraction": { "type": [ "number", "null" ] }, "medianLength": { "type": [ "number", "null" ] }, "distinctLengthCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "tsGranularity": { "type": [ "string", "null" ] }, "tsValidGranularities": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tsTypicalDeltaSeconds": { "type": [ "number", "null" ] }, "tsSelectedGrid": { "type": [ "string", "null" ] }, "tsGapProfile": { "anyOf": [ { "$ref": "#/components/schemas/GapProfileSchema" }, { "type": "null" } ] }, "tsSeasonalPeriods": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SeasonalPeriodSchema" } }, { "type": "null" } ] }, "tsCategoricalSeasonality": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CategoricalSeasonalPeriodSchema" } }, { "type": "null" } ] }, "tsMissingPatterns": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CyclicPatternSchema" } }, { "type": "null" } ] }, "tsActiveWindows": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CyclicPatternSchema" } }, { "type": "null" } ] }, "tsPerEnvProfiles": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TimeSeriesEnvProfileSchema" } }, { "type": "null" } ] }, "tsAnalyzerVersion": { "type": [ "string", "null" ] }, "tsAnalyzedAt": { "type": [ "string", "null" ] }, "elementSchemaType": { "anyOf": [ { "$ref": "#/components/schemas/SchemaMainTypeEnum" }, { "type": "null" } ] }, "elementCategories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "sizeStatistics": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] } }, "additionalProperties": true }, "ConceptValueMappingSchema": { "type": "object", "properties": { "canonicalValue": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "canonicalValue" ] }, "ConditionalAllowedValuesSchema": { "type": "object", "properties": { "condition": { "type": "object", "properties": { "variable": { "type": "string" }, "operator": { "type": "string", "enum": [ "eq", "ne", "gt", "lt", "ge", "le", "in", "not_in" ] }, "value": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "boolean" }, { "type": "array", "items": { "type": [ "number", "string", "boolean" ] } } ] } }, "required": [ "variable", "operator", "value" ], "description": "The condition that must be met for this constraint to apply" }, "allowedValues": { "anyOf": [ { "type": "array", "items": { "type": [ "string", "number", "boolean" ] } }, { "type": "null" } ], "description": "Values allowed when condition is met (used for categorical/boolean variables)" }, "minValue": { "type": [ "number", "null" ], "description": "Minimum allowed value when condition is met (used for numeric variables)" }, "maxValue": { "type": [ "number", "null" ], "description": "Maximum allowed value when condition is met (used for numeric variables)" } }, "required": [ "condition" ] }, "ConditionScanTimestepResultSchema": { "type": "object", "properties": { "timestep": { "type": "number" }, "timestampMs": { "type": [ "number", "null" ] }, "systemHealthScore": { "type": "number" }, "nodeStatuses": { "type": "array", "items": { "$ref": "#/components/schemas/NodeConditionStatusResultSchema" } }, "spikeAlerts": { "type": "array", "items": { "$ref": "#/components/schemas/NodeConditionStatusResultSchema" }, "default": [] }, "trendAlerts": { "type": "array", "items": { "$ref": "#/components/schemas/NodeConditionStatusResultSchema" }, "default": [] }, "autoRca": { "anyOf": [ { "$ref": "#/components/schemas/SampleRcaResultSchema" }, { "type": "null" } ] } }, "required": [ "timestep", "systemHealthScore", "nodeStatuses" ] }, "ConditionSchema": { "type": "object", "properties": { "variable": { "type": "string" }, "operator": { "type": "string", "enum": [ "eq", "ne", "gt", "lt", "ge", "le", "in", "not_in" ] }, "value": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "boolean" }, { "type": "array", "items": { "type": [ "number", "string", "boolean" ] } } ] } }, "required": [ "variable", "operator", "value" ] }, "ConformanceReportSchema": { "type": "object", "properties": { "rowsScanned": { "type": "number" }, "nullRate": { "type": "number" }, "allowedValueCoverage": { "type": [ "number", "null" ] }, "unresolvedValues": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "count": { "type": "number" } }, "required": [ "value", "count" ] }, "default": [] }, "inferredGranularity": { "type": [ "string", "null" ] }, "granularityMatch": { "type": [ "boolean", "null" ] }, "duplicateAnchorKeys": { "type": [ "number", "null" ] }, "unitNote": { "type": [ "string", "null" ] }, "verdict": { "$ref": "#/components/schemas/ConformanceVerdictEnum", "default": "pass" } }, "required": [ "rowsScanned", "nullRate" ] }, "ConformanceVerdictEnum": { "type": "string", "enum": [ "pass", "warn", "fail" ] }, "Connector": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "organisationId": { "type": "string" }, "name": { "type": "string" }, "type": { "anyOf": [ { "$ref": "#/components/schemas/connectorTypesEnum" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "status": { "type": "string", "enum": [ "connected", "error", "unconfigured" ], "default": "unconfigured" }, "errorMessage": { "type": [ "string", "null" ] } }, "required": [ "organisationId", "name", "createdAt", "updatedAt" ] }, "ConnectorDirectQueryInput": { "type": "object", "properties": { "workspaceId": { "type": [ "string", "null" ], "description": "Workspace the source lands in. Optional for a workspace-scoped credential, which supplies it; required for an organisation-wide credential, which can reach several" }, "datasetName": { "type": "string", "minLength": 1, "description": "Name for the created source" }, "config": { "type": "object", "additionalProperties": {}, "description": "Connector-specific selection: {table} or {query} plus database/schema/warehouse for SQL connectors, {path} for storage; connectorId, type and the direct-query settings below are filled in from the route. A SQL source names one of the two, never both: {query} is probed as a derived table, so a pivot, a join or an aggregate can be read directly instead of imported, and the source's columns are the statement's own output. Storage sources are read in place as Parquet and take no query: {path} must name a location inside the bucket rather than its root, {formats} may only say parquet, and {recursive} must not be true — the read covers the path and its partition folders, so anything deeper would never be read" }, "orderingColumn": { "type": "string", "minLength": 1, "description": "Column rows are paged by. Required: a directly-queried source has no injected row index, so without a stable sort the same row can appear on two pages or none" }, "relation": { "type": [ "string", "null" ], "description": "Relation to read, when it is not the config's table (SQL connectors) or resolved from the bucket and path (storage)" }, "appendOnly": { "type": [ "boolean", "null" ], "description": "Declare that rows are only ever added, never updated or deleted. Lets a digital twin pin its training window by watermark instead of copying the rows; undeclared sources are copied" }, "statementTimeoutSeconds": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Cap on how long a single remote statement may run" }, "maxRowsScanned": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0 }, { "type": "null" } ], "description": "Cap on how many rows a single remote statement may scan. SQL connectors only — a row cap has no file analogue, so S3, Google Cloud Storage and Azure Data Lake refuse it rather than ignore it" }, "parentId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Folder to create the source under. Must be a folder already in this workspace; omit it to file the source at the workspace root" } }, "required": [ "datasetName", "config", "orderingColumn" ] }, "ConnectorEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Connector" } }, "required": [ "data" ] }, "ConnectorImportInput": { "type": "object", "properties": { "workspaceId": { "type": [ "string", "null" ], "description": "Workspace the imported source lands in. Optional for a workspace-scoped credential, which supplies it; required for an organisation-wide credential, which can reach several" }, "config": { "type": "object", "additionalProperties": {}, "description": "Connector-specific selection: {table} or {query} for SQL connectors, {path} for storage, {object, fields} for CRM connectors; connectorId and type are filled in from the route" }, "datasetName": { "type": [ "string", "null" ], "description": "Name for the created source (defaults to the table/query name)" }, "ontologyMode": { "anyOf": [ { "type": "string", "enum": [ "auto", "manual" ] }, { "type": "null" } ], "description": "Whether ontology analysis runs automatically after import (default auto)" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Optional URL called once when the import completes" } }, "required": [ "config" ] }, "ConnectorListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Connector" } } }, "required": [ "data" ] }, "connectorTypesEnum": { "type": "string", "enum": [ "PostgreSQL", "MySQL", "ClickHouse", "MongoDB", "REST API", "Snowflake", "S3", "Azure Data Lake", "Google Cloud Storage", "Google Drive", "Redshift", "BigQuery", "Databricks", "Azure Synapse", "Salesforce", "Hubspot", "NetSuite", "Kafka" ] }, "ContinuousPredictionRecordSchema": { "type": "object", "properties": { "timestamp": { "type": [ "number", "null" ], "description": "Timestamp of the prediction" }, "prediction": { "type": [ "number", "null" ], "description": "Predicted value in decoded format" }, "std": { "type": [ "number", "null" ], "description": "Standard deviation of prediction in decoded scale" }, "lowerBound": { "type": [ "number", "null" ], "description": "Lower bound of confidence interval in decoded format" }, "upperBound": { "type": [ "number", "null" ], "description": "Upper bound of confidence interval in decoded format" }, "confidenceLevel": { "type": [ "number", "null" ], "description": "Confidence level for bounds" }, "attribution": { "anyOf": [ { "$ref": "#/components/schemas/ForecastComponentAttributionSchema" }, { "type": "null" } ], "description": "Component attribution for this prediction step" } } }, "ContrastSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "numeric", "categorical" ] }, "causeRef": { "anyOf": [ { "type": [ "string", "number" ] }, { "type": "null" } ] }, "causeTarget": { "anyOf": [ { "type": [ "string", "number" ] }, { "type": "null" } ] }, "contrastType": { "type": "string" } }, "required": [ "type", "contrastType" ] }, "CoordinateDatumEnum": { "type": "string", "enum": [ "wgs84", "gcj02", "bd09" ] }, "CoordinateFormatEnum": { "type": "string", "enum": [ "dd", "dms", "ddm" ] }, "CounterfactualExplanationSchema": { "type": "object", "properties": { "originalSample": { "type": "object", "additionalProperties": {}, "description": "Original sample this explanation corresponds to" }, "imputedVariables": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Non-target variables the request left null, with the value the twin filled in from its own marginal before predicting and searching. originalSample already contains these fills." }, "currentPrediction": { "type": "object", "additionalProperties": {}, "description": "Dictionary mapping each requested target variable to its predicted value in the original sample." }, "requestedTargets": { "type": "array", "items": { "$ref": "#/components/schemas/CounterfactualTargetSchema" }, "description": "The list of target conditions requested for this sample." }, "counterfactuals": { "type": "array", "items": { "$ref": "#/components/schemas/CounterfactualSchema" }, "description": "List of counterfactual solutions found (if any)." }, "searchStatus": { "$ref": "#/components/schemas/CounterfactualSearchStatusSchema", "default": "searched", "description": "'searched' means the solver evaluated candidates for this sample; 'failed' means the search could not run, so an empty counterfactual list is not evidence of infeasibility." }, "failureReason": { "type": [ "string", "null" ], "description": "Actionable reason the search could not run for this sample. Set only when searchStatus is 'failed'." } }, "required": [ "originalSample", "currentPrediction", "requestedTargets", "counterfactuals" ] }, "CounterfactualMatchModeSchema": { "type": "string", "enum": [ "tolerance", "orMore", "orLess" ] }, "CounterfactualMatchStatusSchema": { "type": "string", "enum": [ "exact", "withinTolerance", "closest" ] }, "CounterfactualSchema": { "type": "object", "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/VariableChangeSchema" }, "description": "Changes made to variables" }, "predictedOutcomes": { "type": "object", "additionalProperties": {}, "description": "Dictionary mapping each target variable to its predicted value (decoded) under these changes." }, "allTargetsMet": { "type": "boolean", "description": "Indicates if all requested target conditions were met by this counterfactual." }, "certainty": { "type": "number", "default": 0.8, "description": "Confidence or certainty measure of this counterfactual outcome (heuristic)." }, "matchStatus": { "$ref": "#/components/schemas/CounterfactualMatchStatusSchema", "default": "exact", "description": "Why this counterfactual was kept: exact match, within configured tolerance, or closest non-matching fallback." }, "targetDistances": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "Per-target signed distance (predicted - target) for numeric targets, for UI display." } }, "required": [ "changes", "predictedOutcomes", "allTargetsMet" ] }, "CounterfactualSearchStatusSchema": { "type": "string", "enum": [ "searched", "failed" ] }, "CounterfactualTargetSchema": { "type": "object", "properties": { "variable": { "type": "string", "description": "The target variable name" }, "value": { "description": "The desired value for this target variable" }, "matchMode": { "$ref": "#/components/schemas/CounterfactualMatchModeSchema", "default": "tolerance", "description": "How to decide whether a prediction meets this target: tolerance band, >= target, or <= target." }, "toleranceType": { "anyOf": [ { "$ref": "#/components/schemas/CounterfactualToleranceTypeSchema" }, { "type": "null" } ], "description": "When matchMode='tolerance': percentage of |target| or absolute units." }, "toleranceValue": { "type": [ "number", "null" ], "description": "When matchMode='tolerance': width of the tolerance band (>=0). None/0 means exact match." } }, "required": [ "variable" ] }, "CounterfactualToleranceTypeSchema": { "type": "string", "enum": [ "percentage", "absolute" ] }, "CounterfactualVariableConstraintSchema": { "anyOf": [ { "$ref": "#/components/schemas/RangeConstraintSchema" }, { "$ref": "#/components/schemas/SetConstraintSchema" }, { "$ref": "#/components/schemas/FixedConstraintSchema" } ] }, "CreateConceptInput": { "type": "object", "properties": { "name": { "type": "string" }, "schemaFieldName": { "type": "string" }, "schemaType": { "$ref": "#/components/schemas/SchemaMainTypeEnum" }, "schemaSubtype": { "anyOf": [ { "$ref": "#/components/schemas/SchemaSubTypeEnum" }, { "type": "null" } ] }, "metadata": { "$ref": "#/components/schemas/ConceptMetadataSchema" }, "description": { "type": [ "string", "null" ] }, "conceptClassification": { "anyOf": [ { "$ref": "#/components/schemas/ConceptClassificationEnum" }, { "type": "null" } ] }, "anchorConceptLinks": { "type": "array", "items": { "type": "string" }, "default": [] }, "derivedInfo": { "anyOf": [ { "$ref": "#/components/schemas/DerivedConceptInfoSchema" }, { "type": "null" } ] }, "conceptKind": { "$ref": "#/components/schemas/ConceptKindEnum", "default": "standard" }, "metricSql": { "type": [ "string", "null" ] }, "suggestedRole": { "anyOf": [ { "$ref": "#/components/schemas/SuggestedRoleEnum" }, { "type": "null" } ] }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "status": { "$ref": "#/components/schemas/BindingStatusEnum", "default": "confirmed" }, "source": { "$ref": "#/components/schemas/BindingSourceEnum", "default": "ingest" }, "confidence": { "type": [ "number", "null" ] }, "evidence": { "type": [ "string", "null" ] }, "valueMap": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "string" }, { "type": "string" } ] } }, { "allOf": [ {}, { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "string" }, { "type": "string" } ] } } ] } ] }, { "type": "null" } ] }, "canonicalField": { "type": [ "string", "null" ] }, "scopeFields": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "precedence": { "type": [ "number", "null" ] }, "keyRole": { "anyOf": [ { "$ref": "#/components/schemas/KeyRoleEnum" }, { "type": "null" } ] }, "conformance": { "anyOf": [ { "$ref": "#/components/schemas/ConformanceReportSchema" }, { "type": "null" } ] }, "decidedBy": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ] }, "sourceId": { "type": "string" } }, "required": [ "field", "sourceId" ] }, "default": [] } }, "required": [ "name", "schemaFieldName", "schemaType", "metadata" ] }, "CreateConnectorInput": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "credentials": { "type": [ "object", "null" ], "additionalProperties": {} } }, "required": [ "name", "type" ] }, "CreateDatasetInput": { "type": "object", "properties": { "name": { "type": "string" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/DataViewMutationSourceSchema" } }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/OperationSchema" } }, "description": { "type": [ "string", "null" ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "anchorConceptId": { "type": [ "string", "null" ] } }, "required": [ "name", "sources", "operations" ] }, "CreateEnvironmentGroupInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Display name; unique per twin" }, "definition": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "columnValues", "environments", "statFilters" ] }, "columnValues": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, { "type": "null" } ] }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, { "type": "null" } ] }, "statFilters": { "anyOf": [ { "$ref": "#/components/schemas/EnvStatFilterGroupSchema" }, { "type": "null" } ] }, "agreementThreshold": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] } }, "required": [ "mode" ], "description": "The declarative membership rule: mode columnValues (allowed values per environment column), environments (exact combos), or statFilters (per-environment aggregates over any twin column)" } }, "required": [ "name", "definition" ] }, "CreateReportInput": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "required": [ "title" ] }, "CreateSourceFromDataSchema": { "type": "object", "properties": { "name": { "type": "string", "description": "Source name" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "minItems": 1, "description": "Array of records; keys become columns, types are inferred during ingest" }, "description": { "type": [ "string", "null" ] }, "parentSourceId": { "type": [ "string", "null" ], "description": "Optional parent folder source to group under" } }, "required": [ "name", "data" ] }, "CreateSourceSchema": { "type": "object", "properties": { "name": { "type": "string" }, "dataFormat": { "type": "string", "enum": [ "Tabular", "Folder", "Text", "PDF", "Image", "Audio", "Video" ], "default": "Tabular" }, "description": { "type": [ "string", "null" ] }, "parentSourceId": { "type": [ "string", "null" ] } }, "required": [ "name", "dataFormat" ] }, "CreateTwinInput": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "static", "temporal", "multi-environment-temporal", "multi-environment-static" ], "default": "static" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "datasetId": { "type": [ "string", "null" ] }, "sourceId": { "type": [ "string", "null" ] }, "selectedTimeColumnName": { "type": [ "string", "null" ] }, "environmentColumns": { "type": [ "array", "null" ], "items": { "type": "string" } }, "shardCount": { "type": [ "integer", "null" ], "minimum": 1 } }, "required": [ "name", "type" ] }, "CreateVersionInput": { "type": "object", "properties": { "bump": { "type": "string", "enum": [ "major", "minor", "patch" ], "default": "patch", "description": "Which version component to bump (default patch)" }, "baseVersionId": { "type": [ "string", "null" ], "description": "Version to derive from; the latest version when omitted" }, "datasetId": { "type": [ "string", "null" ], "description": "Point the new version at a different dataset" } } }, "CreateWorkspaceSchema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 } }, "required": [ "name" ] }, "CredentialEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "userId": { "type": "string" }, "organisationId": { "type": "string" }, "workspaceId": { "type": [ "string", "null" ], "description": "The workspace the credential is pinned to, or null for org-wide" }, "scopes": { "type": "array", "items": { "type": "string" } }, "authType": { "type": "string", "enum": [ "apiKey", "oauth" ] }, "rateLimit": { "type": [ "number", "null" ], "description": "Requests per minute; null for OAuth, which shares the fixed OAuth limit" } }, "required": [ "userId", "organisationId", "workspaceId", "scopes", "authType", "rateLimit" ] } }, "required": [ "data" ] }, "CrossEnvironmentStatsSchema": { "type": "object", "properties": { "scope": { "type": [ "string", "null" ] }, "environmentCount": { "type": [ "number", "null" ] }, "totalEnvironments": { "type": [ "number", "null" ] }, "environmentsWithoutEffect": { "type": [ "number", "null" ] }, "environmentsMissingResult": { "type": [ "number", "null" ] }, "metrics": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/PanelAggregateMetricStatsSchema" } }, { "type": "null" } ] } } }, "CycleNameEnum": { "type": "string", "enum": [ "hour_of_day", "day_of_week", "day_of_month", "month_of_year", "week_of_year" ] }, "CyclicComponentEnum": { "type": "string", "enum": [ "second_in_minute", "minute_in_hour", "hour_of_day", "day_of_week", "day_of_month", "week_of_year", "month_of_year", "quarter_of_year" ] }, "CyclicPatternSchema": { "type": "object", "properties": { "cycle": { "$ref": "#/components/schemas/CycleNameEnum" }, "activeIndices": { "type": "array", "items": { "type": "number" }, "default": [] }, "inactiveIndices": { "type": "array", "items": { "type": "number" }, "default": [] }, "densityByIndex": { "type": "object", "additionalProperties": { "type": "number" }, "default": {} }, "aggByIndex": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] } }, "required": [ "cycle" ] }, "datasetFormatsEnum": { "type": "string", "enum": [ "Folder", "Tabular", "Text", "Workbook", "PDF", "DOCX", "PPTX", "Image", "Audio", "Video" ] }, "DataSourceTypeEnum": { "type": "string", "enum": [ "Local Upload", "API Upload", "Web Research", "Document Extraction", "Workbook Extraction", "PostgreSQL", "MySQL", "ClickHouse", "MongoDB", "REST API", "Snowflake", "S3", "Azure Data Lake", "Google Cloud Storage", "Google Drive", "Redshift", "BigQuery", "Databricks", "Azure Synapse", "Salesforce", "Hubspot", "NetSuite", "Kafka" ] }, "DataViewCreatedByEnum": { "type": "string", "enum": [ "manual", "ontology_query", "ai", "recommended" ] }, "DataViewMutationSourceSchema": { "$ref": "#/components/schemas/SourceSchema" }, "DataViewSchema": { "type": "object", "properties": { "_id": { "type": "string" }, "organisationId": { "type": "string" }, "workspaceId": { "type": "string" }, "ownerId": { "type": "string" }, "name": { "type": "string" }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "description": { "type": [ "string", "null" ] }, "rowCount": { "type": [ "number", "null" ] }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceSchema" } }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/OperationSchema" } }, "anchorConceptId": { "type": [ "string", "null" ] }, "createdBy": { "anyOf": [ { "$ref": "#/components/schemas/DataViewCreatedByEnum" }, { "type": "null" } ] }, "sourceQuery": { "anyOf": [ { "$ref": "#/components/schemas/DataViewSourceQuerySchema" }, { "type": "null" } ] }, "sourceQueryDetached": { "type": [ "boolean", "null" ] }, "chartWidgets": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "layout": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "w": { "type": "number" }, "h": { "type": "number" } }, "required": [ "x", "y", "w", "h" ] }, "widget": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "layout", "widget" ] } }, { "type": "null" } ] }, "conceptOverrides": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ViewConceptOverrideEntrySchema" } }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "ok", "broken" ] }, { "type": "null" } ] }, "brokenReasons": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "source_removed", "ontology_reset" ] } }, { "type": "null" } ] }, "brokenDependencies": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/BrokenDataViewDependencySchema" } }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "_id", "organisationId", "workspaceId", "ownerId", "name", "sources", "operations" ] }, "DataViewSourceQuerySchema": { "type": "object", "properties": { "queryRequest": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "reconciliationColumnSides": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ReconciliationColumnSideEnum" } }, { "type": "null" } ] }, "reconciliationColumnGroups": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationColumnGroupSchema" } }, { "type": "null" } ] }, "reconciliationSecondaries": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ReconciliationSecondaryMetaSchema" } }, { "type": "null" } ] }, "reconciliationAlignKeyLabels": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "additionalProperties": true }, "DateDiffSignEnum": { "type": "string", "enum": [ "signed", "absolute" ] }, "DateDiffUnitEnum": { "type": "string", "enum": [ "seconds", "minutes", "hours", "days", "weeks" ] }, "DatetimeFormatSchema": { "type": "string", "minLength": 1 }, "DerivedConceptInfoSchema": { "type": "object", "properties": { "formula": { "type": [ "string", "null" ] }, "formulaBlocks": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "nodeId": { "type": "string" }, "kind": { "type": "string", "const": "template" }, "blockType": { "type": "string", "minLength": 1 }, "values": { "type": "object", "additionalProperties": {} } }, "required": [ "nodeId", "kind", "blockType" ] }, { "type": "object", "properties": { "nodeId": { "type": "string" }, "kind": { "type": "string", "const": "structural" }, "blockType": { "type": "string", "enum": [ "binary", "ifElse" ] }, "values": { "type": "object", "additionalProperties": {} }, "children": { "type": "object", "additionalProperties": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "nodeId": { "type": "string" }, "kind": { "type": "string", "const": "template" }, "blockType": { "type": "string", "minLength": 1 }, "values": { "type": "object", "additionalProperties": {} } }, "required": [ "nodeId", "kind", "blockType" ] }, { "type": "object", "properties": { "nodeId": { "type": "string" }, "kind": { "type": "string", "const": "structural" }, "blockType": { "type": "string", "enum": [ "binary", "ifElse" ] }, "values": { "type": "object", "additionalProperties": {} }, "children": { "type": "object", "additionalProperties": { "anyOf": [ {}, { "type": "null" } ] } } }, "required": [ "nodeId", "kind", "blockType", "children" ] } ], "discriminator": { "propertyName": "kind" } }, { "type": "null" } ] } } }, "required": [ "nodeId", "kind", "blockType", "children" ] } ], "discriminator": { "propertyName": "kind" } }, { "type": "null" } ] }, "derivedType": { "$ref": "#/components/schemas/DerivedTypeEnum", "default": "manual" }, "kind": { "anyOf": [ { "$ref": "#/components/schemas/DerivedInfoKindEnum" }, { "type": "null" } ] }, "source": { "anyOf": [ { "$ref": "#/components/schemas/DerivedSourceEnum" }, { "type": "null" } ] }, "sourceColumns": { "type": "array", "items": { "type": "string" }, "default": [] }, "expression": { "type": [ "string", "null" ] }, "r2": { "type": [ "number", "null" ] }, "isDeterministic": { "type": [ "boolean", "null" ] }, "lag": { "type": [ "number", "null" ] }, "cumulativeDirection": { "type": [ "string", "null" ] }, "sourceDataViewId": { "type": [ "string", "null" ] }, "operationLineage": { "anyOf": [ { "$ref": "#/components/schemas/OperationLineageSchema" }, { "type": "null" } ] }, "viewSnapshot": { "anyOf": [ { "$ref": "#/components/schemas/ViewSnapshotSchema" }, { "type": "null" } ] }, "lineageHash": { "type": [ "string", "null" ] }, "sourceJoinConfig": { "anyOf": [ { "$ref": "#/components/schemas/SourceJoinConfigSchema" }, { "type": "null" } ] } } }, "DerivedInfoKindEnum": { "type": "string", "enum": [ "op", "formula", "detected", "join" ] }, "DerivedSourceEnum": { "type": "string", "enum": [ "user", "detected", "discovered" ] }, "DerivedTypeEnum": { "type": "string", "enum": [ "manual", "datetime_component", "lag", "cumulative", "step_change", "algebraic_identity", "complement", "ratio", "view_operation" ] }, "DerivedViaEnum": { "type": "string", "enum": [ "document_tables", "document_homogenisation", "document_entities", "workbook_sql" ] }, "DetectedConceptStructureSchema": { "type": "object", "properties": { "temporalPrerequisites": { "type": "array", "items": { "type": "string" }, "default": [] }, "suggestedRole": { "anyOf": [ { "$ref": "#/components/schemas/SuggestedRoleEnum" }, { "type": "null" } ] } } }, "DigitalTwinCreatedEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "organisationId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "normalizedName": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/DigitalTwinTypeEnum" }, "canonicalInputSchema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SchemaEntryModelSchema" } }, { "type": "null" } ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/StatusTypeEnum", "default": "active" }, "createdAt": { "type": "string" }, "suggestedSimulations": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SuggestedSimulationSchema" } }, { "type": "null" } ] }, "suggestionsGeneratedAt": { "type": [ "string", "null" ] }, "environmentGroups": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/EnvironmentGroupSchema" } }, { "type": "null" } ] }, "autoUpdate": { "anyOf": [ { "$ref": "#/components/schemas/AutoUpdateSettingsSchema" }, { "type": "null" } ] }, "maintainedBy": { "type": "array", "items": { "type": "object", "properties": { "applicationId": { "type": "string" }, "version": { "type": "string" }, "flowId": { "type": "string" } }, "required": [ "applicationId", "version", "flowId" ] } }, "versionId": { "type": "string", "description": "The version created alongside the twin" } }, "required": [ "id", "organisationId", "workspaceId", "name", "type", "versionId" ] } }, "required": [ "data" ] }, "DigitalTwinEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DigitalTwin" } }, "required": [ "data" ] }, "DigitalTwinListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DigitalTwin" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Pass back as ?cursor= to fetch the next page" }, "hasMore": { "type": "boolean", "description": "Whether a further page exists" }, "total": { "type": "number", "description": "Total matching rows, when the query can count them" } }, "required": [ "hasMore" ] } }, "required": [ "data", "pagination" ] }, "DigitalTwinPredictionResultSchema": { "type": "object", "properties": { "results": { "type": "object", "additionalProperties": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/CategoricalPredictionRecordSchema" }, { "$ref": "#/components/schemas/ContinuousPredictionRecordSchema" } ] } } }, "changepoints": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/ForecastChangepointSchema" } } }, { "type": "null" } ], "description": "Detected changepoints per variable" }, "history": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ForecastHistorySeriesSchema" } }, { "type": "null" } ], "description": "Per-variable trailing observed history from the model's stored training series" } }, "required": [ "results" ] }, "DigitalTwinScenarioSchema": { "anyOf": [ { "$ref": "#/components/schemas/OptimisationScenarioSchema" }, { "$ref": "#/components/schemas/StaticInterventionSpecSchema" }, { "$ref": "#/components/schemas/TimeSeriesInterventionSpecSchema" }, { "$ref": "#/components/schemas/MultiCounterfactualRequestSchema" }, { "$ref": "#/components/schemas/PredictionWithUncertaintyRequestSchema" }, { "$ref": "#/components/schemas/ExplanationRequestSchema" }, { "$ref": "#/components/schemas/ParentImpactRequestSchema" }, { "$ref": "#/components/schemas/ForecastWithUncertaintyRequestSchema" }, { "$ref": "#/components/schemas/TemporalExplanationRequestSchema" }, { "$ref": "#/components/schemas/TemporalCounterfactualRequestSchema" }, { "$ref": "#/components/schemas/TemporalOptimisationScenarioSchema" }, { "$ref": "#/components/schemas/PanelForecastRequestSchema" }, { "$ref": "#/components/schemas/PanelInterventionSpecSchema" }, { "$ref": "#/components/schemas/PanelExplanationRequestSchema" }, { "$ref": "#/components/schemas/PanelCounterfactualRequestSchema" }, { "$ref": "#/components/schemas/PanelOptimisationScenarioSchema" }, { "$ref": "#/components/schemas/PanelParentImpactRequestSchema" }, { "$ref": "#/components/schemas/RootCauseAnalysisRequestSchema" }, { "$ref": "#/components/schemas/TemporalRootCauseAnalysisRequestSchema" }, { "$ref": "#/components/schemas/PanelRootCauseAnalysisRequestSchema" }, { "$ref": "#/components/schemas/StaticPanelRootCauseAnalysisRequestSchema" }, { "$ref": "#/components/schemas/AnomalyDetectionRequestSchema" }, { "$ref": "#/components/schemas/TemporalAnomalyDetectionRequestSchema" }, { "$ref": "#/components/schemas/PanelAnomalyDetectionRequestSchema" }, { "$ref": "#/components/schemas/StaticPanelAnomalyDetectionRequestSchema" }, { "$ref": "#/components/schemas/CausalHealthMonitorRequestSchema" }, { "$ref": "#/components/schemas/PanelCausalHealthMonitorRequestSchema" } ] }, "DigitalTwinTypeEnum": { "type": "string", "enum": [ "static", "temporal", "multi-environment-temporal", "multi-environment-static" ] }, "DigitalTwinVersionEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DigitalTwinVersion" } }, "required": [ "data" ] }, "DigitalTwinVersionListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DigitalTwinVersion" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Pass back as ?cursor= to fetch the next page" }, "hasMore": { "type": "boolean", "description": "Whether a further page exists" }, "total": { "type": "number", "description": "Total matching rows, when the query can count them" } }, "required": [ "hasMore" ] } }, "required": [ "data", "pagination" ] }, "directQuerySettingsSchema": { "type": "object", "properties": { "orderingColumn": { "type": [ "string", "null" ], "description": "Column the source's rows are paged by" }, "appendOnly": { "type": [ "boolean", "null" ], "description": "Declared: the rows are only ever added, never updated or deleted" }, "statementTimeoutSeconds": { "type": [ "number", "null" ], "description": "Cap on how long one remote statement may run" }, "maxRowsScanned": { "type": [ "number", "null" ], "description": "Cap on how many rows one remote statement may scan" } }, "description": "How a direct_query source is read. Null on a snapshot source, where none of it applies. The relation itself is not reported: on a storage source it is resolved against the bucket inside the connector's encrypted credentials, which the connector routes strip" }, "DirectQuerySourceEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "sourceId": { "type": "string", "description": "Id of the created source" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "droppedColumns": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "type": { "type": "string", "description": "The source's own type name, which the platform has no column type for" } }, "required": [ "field", "type" ] }, "description": "Columns the source has that its schema here does not. An object store leaves out columns whose type the platform cannot represent, and a source silently short a column is what the caller has to be able to see" } }, "required": [ "sourceId", "workspaceId", "name", "droppedColumns" ], "description": "A source created over a connector and read at query time. Creation is synchronous — the schema is probed from the remote catalogue, not scanned — but ontology analysis is queued and its results appear later" } }, "required": [ "data" ] }, "DoseResponseAnalysisSchema": { "type": "object", "properties": { "points": { "type": "array", "items": { "$ref": "#/components/schemas/DoseResponsePointSchema" }, "description": "Points along the dose-response curve" }, "isLinear": { "type": "boolean", "description": "Whether the relationship appears linear" }, "inflectionPoints": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ], "description": "Values where effect direction changes" }, "referenceValue": { "type": "number", "description": "Reference value for dose-response analysis" } }, "required": [ "points", "isLinear", "referenceValue" ] }, "DoseResponsePointSchema": { "type": "object", "properties": { "causeValue": { "type": "number", "description": "Value of the cause variable" }, "effectMean": { "type": "number", "description": "Mean effect at this cause value" }, "effectStd": { "type": "number", "description": "Standard deviation of effect" }, "confidenceInterval": { "type": "array", "items": { "type": "number" }, "description": "Confidence interval for effect" }, "deltaVector": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "Change in probability distribution" } }, "required": [ "causeValue", "effectMean", "effectStd", "confidenceInterval" ] }, "DriverRankingSchema": { "type": "object", "properties": { "targetVariable": { "type": "string", "description": "The outcome variable being explained" }, "drivers": { "type": "array", "items": { "$ref": "#/components/schemas/CausalRelationshipAnalysisSchema" }, "description": "Causal drivers ranked by effect size" } }, "required": [ "targetVariable", "drivers" ] }, "DtDerivedColumnInfoSchema": { "type": "object", "properties": { "derivedType": { "type": "string" }, "targetColumn": { "type": "string" }, "sourceColumns": { "type": "array", "items": { "type": "string" } }, "expression": { "type": "string" }, "r2": { "type": [ "number", "null" ] }, "isDeterministic": { "type": "boolean" }, "implausibilityReason": { "type": [ "string", "null" ] }, "lag": { "type": [ "number", "null" ] }, "cumulativeDirection": { "type": [ "string", "null" ] }, "seasonalTerms": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SeasonalTermSchema" } }, { "type": "null" } ] }, "isMonotonicallyIncreasing": { "type": [ "boolean", "null" ] }, "isMonotonicallyDecreasing": { "type": [ "boolean", "null" ] } }, "required": [ "derivedType", "targetColumn", "sourceColumns", "expression", "isDeterministic" ] }, "EdgePropagationSeriesResultSchema": { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" }, "scores": { "type": "array", "items": { "type": "number" } } }, "required": [ "source", "target", "scores" ] }, "EnrichmentRecordSchema": { "type": "object", "properties": { "status": { "anyOf": [ { "$ref": "#/components/schemas/GeoEnrichmentStatusEnum" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "$ref": "#/components/schemas/GeoEnrichmentKindEnum" }, { "type": "null" } ] }, "enrichedAt": { "type": [ "string", "null" ] }, "enricherVersion": { "type": [ "string", "null" ] }, "dataVersion": { "type": [ "string", "null" ] }, "version": { "type": [ "number", "null" ] }, "sidecarKey": { "type": [ "string", "null" ] }, "keyFields": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "hintFields": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "corroborationFields": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "latLonPrecision": { "type": [ "number", "null" ] }, "distinctTotal": { "type": [ "number", "null" ] }, "matchedCount": { "type": [ "number", "null" ] }, "unmatchedCount": { "type": [ "number", "null" ] }, "truncated": { "type": [ "boolean", "null" ] }, "error": { "type": [ "string", "null" ] }, "appliedDatum": { "type": [ "string", "null" ] } } }, "EnvironmentCoverageSchema": { "type": "object", "properties": { "requested": { "type": "number" }, "forecast": { "type": "number" }, "failed": { "type": "array", "items": { "$ref": "#/components/schemas/EnvironmentForecastFailureSchema" }, "default": [] }, "omittedFailures": { "type": "number", "default": 0 } }, "required": [ "requested", "forecast" ] }, "EnvironmentForecastFailureSchema": { "type": "object", "properties": { "environment": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "environment", "reason" ] }, "EnvironmentGroupDefinitionSchema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "columnValues", "environments", "statFilters" ] }, "columnValues": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, { "type": "null" } ] }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, { "type": "null" } ] }, "statFilters": { "anyOf": [ { "$ref": "#/components/schemas/EnvStatFilterGroupSchema" }, { "type": "null" } ] }, "agreementThreshold": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] } }, "required": [ "mode" ] }, "EnvironmentGroupEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EnvironmentGroupSchema" } }, "required": [ "data" ] }, "EnvironmentGroupListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EnvironmentGroupSchema" } } }, "required": [ "data" ] }, "EnvironmentGroupSchema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "definition": { "$ref": "#/components/schemas/EnvironmentGroupDefinitionSchema" }, "createdAt": { "type": "string" }, "createdBy": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] }, "splitColumn": { "type": [ "string", "null" ] }, "splitValue": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "definition", "createdAt" ] }, "EnvironmentGroupSnapshotSchema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "envKeys": { "type": "array", "items": { "type": "string" } }, "droppedEnvKeys": { "type": "array", "items": { "type": "string" }, "default": [] }, "notice": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "envKeys" ] }, "EnvironmentSelectionSchema": { "type": "object", "properties": { "baseline": { "type": "string", "enum": [ "all", "none" ] }, "exceptions": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } } }, "required": [ "baseline", "exceptions" ] }, "EnvStatFilterGroupSchema": { "type": "object", "properties": { "booleanOperator": { "type": "string", "enum": [ "AND", "OR" ] }, "filters": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/EnvStatFilterSchema" }, { "$ref": "#/components/schemas/EnvStatFilterGroupSchema" } ] } } }, "required": [ "booleanOperator", "filters" ] }, "EnvStatFilterSchema": { "type": "object", "properties": { "column": { "type": "string" }, "comparisonOperator": { "type": "string" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": [ "string", "number", "boolean" ] } } ] }, "reduce": { "anyOf": [ { "$ref": "#/components/schemas/EnvStatReduceEnum" }, { "type": "null" } ] } }, "required": [ "column", "comparisonOperator", "value" ] }, "EnvStatReduceEnum": { "type": "string", "enum": [ "value", "mean", "min", "max", "any" ] }, "EvalHorizonSchema": { "type": "object", "properties": { "count": { "type": "integer", "exclusiveMinimum": 0 }, "unit": { "$ref": "#/components/schemas/HorizonUnitEnum" } }, "required": [ "count", "unit" ] }, "EvaluationChangeSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "improvement", "worsening" ] }, "metric": { "type": "string" }, "oldValue": { "type": [ "number", "null" ] }, "newValue": { "type": "number" }, "percentChange": { "type": [ "number", "null" ] } }, "required": [ "type", "metric", "newValue" ] }, "EvaluationResultSchema": { "type": "object", "properties": { "modelType": { "type": "string", "enum": [ "cbn", "tcbn" ], "description": "Type of the model" }, "nodeMetrics": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/NodeMetricsSchema" }, "description": "Metrics for each node" }, "globalMetrics": { "type": "object", "properties": { "logLikelihood": { "type": [ "number", "null" ], "description": "Overall log-likelihood" }, "averageMse": { "type": [ "number", "null" ], "description": "Overall mean squared error" }, "averageMae": { "type": [ "number", "null" ], "description": "Overall mean absolute error" }, "averageAccuracy": { "type": [ "number", "null" ], "description": "Overall accuracy" }, "averageMape": { "type": [ "number", "null" ], "description": "Overall mean absolute percentage error" } }, "description": "Global metrics" }, "skippedReason": { "anyOf": [ { "type": "string", "enum": [ "insufficient_data" ] }, { "type": "null" } ], "description": "Set when evaluation was deliberately skipped" }, "skipReasons": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "User-facing explanation of why evaluation was skipped" }, "nEvalPoints": { "type": [ "number", "null" ], "description": "Number of holdout time steps evaluation used (or would have used)" } }, "required": [ "modelType", "nodeMetrics", "globalMetrics" ] }, "EventLogEntryResultSchema": { "type": "object", "properties": { "at": { "type": "number" }, "atTimestampMs": { "type": [ "number", "null" ] }, "kind": { "type": "string", "enum": [ "first_alert", "cascade", "rca_verdict", "recovered" ] }, "variable": { "type": [ "string", "null" ] }, "alertType": { "type": [ "string", "null" ] }, "ewmaZ": { "type": "number", "default": 0 }, "signedCurrentZ": { "type": "number", "default": 0 }, "sourceSignedZ": { "type": "number", "default": 0 }, "targetSignedZ": { "type": "number", "default": 0 }, "sentence": { "type": "string", "default": "" }, "fromVar": { "type": [ "string", "null" ] }, "toVar": { "type": [ "string", "null" ] }, "lagSteps": { "type": [ "number", "null" ] }, "correlation": { "type": [ "number", "null" ] }, "target": { "type": [ "string", "null" ] }, "rootCause": { "type": [ "string", "null" ] } }, "required": [ "at", "kind" ] }, "ExecuteSimulationInput": { "type": "object", "properties": { "digitalTwinId": { "type": "string", "description": "Id of the digital twin to simulate" }, "digitalTwinVersionId": { "type": "string", "description": "Id of the trained version to run against" }, "scenario": { "type": "object", "additionalProperties": {}, "description": "Scenario configuration: the same object the platform's New Simulation wizard produces. `type` is the discriminator naming the family, and the rest of the fields are that family's inputs. The spelling depends on the twin's kind: prediction (`prediction`: sample, targetVars), forecast (`forecast` / `panel_forecast`: forecastH, targetVars), intervention (`intervention` / `temporal_intervention` / `panel_intervention`: interventions, metrics), optimisation (`optimisation` / `temporal_optimisation` / `panel_optimisation`: objectives, decisionVars), best action (`counterfactual` and variants: samples, targets), explanation (`explanation` and variants: explanationMode, causeVariable, effectVariable), root cause analysis and anomaly detection (targetVariable, samples). Note `scenarioType` is the filter on GET /simulations, not a field of this object. Worked bodies for every family: https://docs.rootcause.ai/api/rest-running-simulations. POST to the version's scenario-from-query endpoint to have the platform build one from a plain-English question." }, "environmentGroupIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Multi-environment (panel) twins: saved environment groups to scope the run to. The server resolves each group's membership against the version at submit time and narrows the run to it: when the scenario also names environments the two are intersected, never unioned, so a group can only ever shrink a scenario. An empty intersection is a 400. What it resolved is frozen onto the run as environmentGroupSnapshots. Ignored by single-environment twins." }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Optional URL called when the run completes" } }, "required": [ "digitalTwinId", "digitalTwinVersionId", "scenario" ] }, "ExplanationModeSchema": { "type": "string", "enum": [ "directional", "discovery", "impact" ] }, "ExplanationRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "explanation" }, "explanationMode": { "anyOf": [ { "$ref": "#/components/schemas/ExplanationModeSchema" }, { "type": "null" } ], "description": "Explicit explanation mode selection" }, "causeVariable": { "type": [ "string", "null" ], "description": "The cause variable to explain" }, "effectVariable": { "type": [ "string", "null" ], "description": "The effect variable to explain" }, "segments": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDefinitionSchema" } }, { "type": "null" } ], "description": "The segments to explain" } }, "required": [ "type" ] }, "ExplanationResultSchema": { "type": "object", "properties": { "explanationType": { "type": "string", "enum": [ "directional", "discovery", "impact" ], "description": "Type of explanation performed" }, "causalRelationships": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CausalRelationshipAnalysisSchema" } }, { "type": "null" } ], "description": "For directional explanations" }, "driverRanking": { "anyOf": [ { "$ref": "#/components/schemas/DriverRankingSchema" }, { "type": "null" } ], "description": "For discovery explanations" }, "impactAnalysis": { "anyOf": [ { "$ref": "#/components/schemas/ImpactAnalysisSchema" }, { "type": "null" } ], "description": "For impact explanations" }, "executionTime": { "type": "number", "description": "Time taken to generate explanation" }, "sampleSize": { "type": "number", "description": "Number of samples used in analysis" } }, "required": [ "explanationType", "executionTime", "sampleSize" ] }, "ExportTwinInput": { "type": "object", "properties": { "includeRuns": { "type": "boolean", "description": "Include simulation run artifacts in the export (default false)" }, "versions": { "type": "array", "items": { "type": "string" }, "description": "Version ids to export; all versions when omitted" }, "environments": { "type": "array", "items": { "type": "string" }, "description": "Panel twins: environment keys to export; all environments when omitted" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Optional URL called once when the export completes" } } }, "ExtractionRecipeSchema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "schema", "entities" ] }, "sourceDocumentIds": { "type": "array", "items": { "type": "string" } }, "columns": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "dtype": { "anyOf": [ { "type": "string", "enum": [ "number", "category", "boolean", "text" ] }, { "type": "null" } ] }, "categories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "trueSynonyms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "falseSynonyms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "unit": { "type": [ "string", "null" ] }, "examples": { "anyOf": [ { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "string" }, { "type": "string" } ] } }, { "type": "null" } ] }, "conceptId": { "type": [ "string", "null" ] } }, "required": [ "name" ], "additionalProperties": true } }, { "type": "null" } ] }, "entityTypes": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "dtype": { "anyOf": [ { "type": "string", "enum": [ "number", "category", "boolean", "text" ] }, { "type": "null" } ] }, "categories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "trueSynonyms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "falseSynonyms": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "unit": { "type": [ "string", "null" ] }, "examples": { "anyOf": [ { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "string" }, { "type": "string" } ] } }, { "type": "null" } ] }, "conceptId": { "type": [ "string", "null" ] } }, "required": [ "name" ], "additionalProperties": true }, "default": [] } }, "required": [ "name" ], "additionalProperties": true } }, { "type": "null" } ] }, "targetName": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "lastAppendedAt": { "type": [ "string", "null" ] } }, "required": [ "mode", "sourceDocumentIds" ], "additionalProperties": true }, "ExtractionStatusEnum": { "type": "string", "enum": [ "pending", "extracting", "completed", "failed" ] }, "FailureContextSchema": { "type": "object", "properties": { "error": { "type": "string" }, "failedAtStage": { "type": "string", "enum": [ "causal_discovery", "model_training" ] }, "retryable": { "type": "boolean", "default": true }, "userFacing": { "type": "boolean", "default": false } }, "required": [ "error", "failedAtStage" ] }, "FilterGroupSchema": { "type": "object", "properties": { "booleanOperator": { "$ref": "#/components/schemas/LogicalOperatorEnum" }, "filters": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/FilterSchema" }, { "$ref": "#/components/schemas/FilterGroupSchema" } ] } } }, "required": [ "booleanOperator", "filters" ] }, "FilterSchema": { "type": "object", "properties": { "column": { "type": "string" }, "comparisonOperator": { "$ref": "#/components/schemas/ComparisonOperatorEnum" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": [ "string", "number", "boolean" ] } } ] }, "correctType": { "type": "boolean" } }, "required": [ "column", "comparisonOperator", "value", "correctType" ] }, "FixedConstraintSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" } }, "required": [ "type" ] }, "FixedSubGraphChangeSchema": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ChangeTypeEnum" }, "changeTarget": { "type": "string", "enum": [ "relationships", "antiRelationships" ] }, "relationship": { "$ref": "#/components/schemas/CausalRelationshipSchema" } }, "required": [ "type", "changeTarget", "relationship" ] }, "FixedSubGraphSchema": { "type": "object", "properties": { "relationships": { "type": "array", "items": { "$ref": "#/components/schemas/CausalRelationshipSchema" } }, "antiRelationships": { "type": "array", "items": { "$ref": "#/components/schemas/CausalRelationshipSchema" } } }, "required": [ "relationships", "antiRelationships" ] }, "ForecastChangepointSchema": { "type": "object", "properties": { "stepIndex": { "type": "number", "description": "Step index where changepoint occurs" }, "timestamp": { "type": "number", "description": "Timestamp of the changepoint" }, "direction": { "type": "string", "enum": [ "up", "down", "inflection" ], "description": "Direction of the change" }, "magnitude": { "type": "number", "description": "Magnitude of the change" }, "primaryDriver": { "type": "string", "description": "Primary driver of the change" }, "driverContribution": { "type": "number", "description": "Contribution of the primary driver" } }, "required": [ "stepIndex", "timestamp", "direction", "magnitude", "primaryDriver", "driverContribution" ] }, "ForecastComponentAttributionSchema": { "type": "object", "properties": { "trend": { "type": [ "number", "null" ], "description": "Adaptive trend contribution" }, "seasonal": { "type": [ "number", "null" ], "description": "Seasonal component contribution" }, "parents": { "type": [ "number", "null" ], "description": "Total parent causal effect" }, "delta": { "type": [ "number", "null" ], "description": "Level/drift contribution" }, "parentBreakdown": { "anyOf": [ { "type": "object", "additionalProperties": { "anyOf": [ { "not": {} }, { "type": [ "number", "null" ] } ] } }, { "type": "null" } ], "description": "Per-parent contribution breakdown" } } }, "ForecastHistorySeriesSchema": { "type": "object", "properties": { "timestamps": { "type": "array", "items": { "type": "number" }, "description": "Trailing observed-history timestamps in ms, ending at the model's last training step" }, "values": { "type": "array", "items": { "type": [ "number", "null" ] }, "description": "Observed values aligned with timestamps; null entries mark missing source rows" } }, "required": [ "timestamps", "values" ] }, "ForecastWithUncertaintyRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "forecast" }, "forecastFrom": { "type": [ "number", "null" ], "description": "Timestamp of the forecast start" }, "forecastH": { "type": "number", "description": "Number of steps to forecast" }, "targetVars": { "type": "array", "items": { "type": "string" }, "description": "Target variables to forecast" }, "confidenceLevel": { "type": [ "number", "null" ], "default": 0.95, "description": "Confidence level for intervals" }, "originTimestamp": { "type": [ "number", "null" ], "description": "Forecast as-of timestamp (ms epoch). Overrides forecastFrom when set." } }, "required": [ "type", "forecastH", "targetVars" ] }, "FrequencyMethodEnum": { "type": "string", "enum": [ "fft", "welch" ] }, "FrequencyOutputFormatEnum": { "type": "string", "enum": [ "spectrogram", "time_frequency_long" ] }, "FrequencyUnitEnum": { "type": "string", "enum": [ "hz", "per_minute", "per_hour", "per_day", "per_week", "per_month", "per_year" ] }, "FrequencyWindowFunctionEnum": { "type": "string", "enum": [ "hann", "hamming", "blackman", "rectangular" ] }, "GapProfileSchema": { "type": "object", "properties": { "expectedIntervalSeconds": { "type": [ "number", "null" ] }, "p50GapSeconds": { "type": [ "number", "null" ] }, "p95GapSeconds": { "type": [ "number", "null" ] }, "p99GapSeconds": { "type": [ "number", "null" ] }, "maxGapSeconds": { "type": [ "number", "null" ] }, "gapCount": { "type": [ "number", "null" ] }, "largestGapStart": { "type": [ "string", "null" ] } } }, "GeoEnrichmentKindEnum": { "type": "string", "enum": [ "forward", "reverse" ] }, "GeoEnrichmentStatusEnum": { "type": "string", "enum": [ "running", "completed", "partial", "failed" ] }, "GraphRecommendationsSchema": { "type": "object", "properties": { "x": { "type": "string" }, "y": { "type": "string" }, "direction": { "type": "string", "enum": [ "forward", "backward" ] }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "x", "y", "direction", "reasons" ] }, "GraphSliceInput": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "columnValues", "environments", "statFilters" ], "description": "How the environment subset is defined" }, "columnValues": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, { "type": "null" } ], "description": "columnValues mode: allowed values per environment column; an unconstrained column admits all values" }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, { "type": "null" } ], "description": "environments mode: exact environment combos, each {column: value}" }, "statFilters": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "statFilters mode: select environments by per-environment aggregates over any twin column" }, "agreementThreshold": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ], "description": "Share of environments (0-1) a relationship must hold in to keep an edge (default 0.5)" } }, "required": [ "mode" ] }, { "type": "object", "properties": { "groupId": { "type": "string", "description": "Id of a saved environment group on this twin; its stored definition supplies the subset" }, "agreementThreshold": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ], "description": "Overrides the agreementThreshold stored on the group for this call only" } }, "required": [ "groupId" ] } ] }, "GroupUnresolvableSchema": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "noEnvironmentColumns", "unknownEnvironmentColumn", "shapeMismatch", "unknownFilterColumn", "filterQueryFailed", "noEvidence" ] }, "message": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "reason", "message" ] }, "HarmonicFitSchema": { "type": "object", "properties": { "periodsWithHarmonics": { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] } }, "sinCosCoefficients": { "type": "array", "items": { "type": "number" } }, "productPairs": { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] } }, "productCoefficients": { "type": "array", "items": { "type": "number" } } }, "required": [ "periodsWithHarmonics", "sinCosCoefficients", "productPairs", "productCoefficients" ] }, "HistoryDiffSchema": { "type": "object", "properties": { "changedColumns": { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "string" }, "stored": { "anyOf": [ { "$ref": "#/components/schemas/ColumnWindowProfileSchema" }, { "type": "null" } ] }, "current": { "anyOf": [ { "$ref": "#/components/schemas/ColumnWindowProfileSchema" }, { "type": "null" } ] } }, "required": [ "column" ] }, "default": [] }, "deltaOperations": { "type": "array", "items": { "type": "object", "properties": { "datasetId": { "type": "string" }, "version": { "type": "integer" }, "operation": { "type": "string" }, "timestampMs": { "type": [ "number", "null" ] } }, "required": [ "datasetId", "version", "operation" ] }, "default": [] }, "rewrittenDatasets": { "type": "array", "items": { "type": "string" }, "default": [] } } }, "HorizonUnitEnum": { "type": "string", "enum": [ "S", "T", "H", "D", "W", "ME", "Y" ] }, "ImpactAnalysisSchema": { "type": "object", "properties": { "sourceVariable": { "type": "string", "description": "The variable whose impacts are analyzed" }, "impacts": { "type": "array", "items": { "$ref": "#/components/schemas/CausalRelationshipAnalysisSchema" }, "description": "Variables impacted by the source" } }, "required": [ "sourceVariable", "impacts" ] }, "ImputeMethodEnum": { "type": "string", "enum": [ "mean", "median", "mode", "constant" ] }, "InterpolateTimeMethodEnum": { "type": "string", "enum": [ "linear", "time", "index" ] }, "InterventionCountConfigSchema": { "type": "object", "properties": { "maxInterventions": { "anyOf": [ { "type": "number", "minimum": 1 }, { "type": "null" } ], "description": "Maximum number of changes per plan. None means no limit." }, "optimizeCount": { "type": "boolean", "default": true, "description": "Whether to treat intervention count as an implicit minimization objective" } } }, "InterventionResultSchema": { "type": "object", "properties": { "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricResultSchema" }, "description": "Intervention metrics" }, "sampleSize": { "type": "number", "description": "Number of samples used" }, "causalPaths": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "Causal paths from intervention to target" }, "causalPathsByMetric": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "description": "Causal paths per metric name" }, "segmentAnalysis": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentEffectSchema" }, "description": "Segment-specific effects" }, "uncertainty": { "type": "object", "properties": { "meanEffect": { "type": "number", "description": "Mean effect" }, "stdEffect": { "type": "number", "description": "Standard deviation of effect" }, "confidenceInterval": { "type": "array", "items": { "type": "number" }, "description": "Confidence interval" }, "confidenceLevel": { "type": "number", "description": "Confidence level" }, "pValue": { "type": "number", "description": "P-value testing null hypothesis of no effect" }, "significant": { "type": "boolean", "description": "Whether the effect is statistically significant" }, "robustnessValue": { "type": [ "number", "null" ], "description": "Cinelli-Hazlett robustness value: share of residual variance an unmeasured confounder must explain in both treatment and outcome to move the estimate to the null (0..1)" }, "eValue": { "type": [ "number", "null" ], "description": "E-value on the risk-ratio scale; only present for binary-rate metrics" }, "eValueCiLimit": { "type": [ "number", "null" ], "description": "E-value for the confidence-interval limit closest to the null" }, "baselineInterval": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ], "description": "Percentile interval of the resampled baseline reading, on the metric's scale, at confidenceLevel" } }, "required": [ "meanEffect", "stdEffect", "confidenceInterval", "confidenceLevel", "pValue", "significant" ], "description": "Uncertainty quantification" }, "uncertainties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/InterventionUncertaintySchema" }, "description": "Per-metric bootstrap uncertainties" }, "mediatorShifts": { "$ref": "#/components/schemas/MediatorShiftsSchema", "description": "Per-metric mediator shifts: {metricName: {mediators: [...], paths: {...}}}" }, "robustness": { "$ref": "#/components/schemas/InterventionRobustnessScoreInlineSchema", "description": "Robustness score for panel data interventions" }, "interventionValues": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ], "description": "Pre/post value per intervened variable: {variable: {baseline, intervention}}" }, "sweptVariable": { "type": [ "string", "null" ], "description": "Variable swept by a `range` intervention, when the scenario carried one" }, "sweptMode": { "anyOf": [ { "type": "string", "enum": [ "absolute", "percentage" ] }, { "type": "null" } ], "description": "Units of the sweep grid — percentage grids apply relative changes and share units with percent dials" }, "doseResponse": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DoseResponseAnalysisSchema" } }, { "type": "null" } ], "description": "Per-metric sweep curve keyed by metric name, present only for range scenarios" }, "executionTime": { "type": "number", "description": "Execution time in seconds" } }, "required": [ "metrics", "sampleSize", "uncertainty", "executionTime" ] }, "InterventionRobustnessScoreInlineSchema": { "type": "object", "properties": { "overallScore": { "type": "number" }, "edgeStabilityScore": { "type": "number" }, "coefficientStabilityScore": { "type": [ "number", "null" ] }, "environmentCoverageScore": { "type": [ "number", "null" ] }, "warnings": { "type": "array", "items": { "type": "string" }, "default": [] }, "recommendation": { "type": "string" } }, "required": [ "overallScore", "edgeStabilityScore", "recommendation" ] }, "InterventionSchema": { "type": "object", "properties": { "variable": { "type": "string", "description": "The variable to intervene on" }, "valueSpec": { "anyOf": [ { "$ref": "#/components/schemas/SetValueSpecSchema" }, { "$ref": "#/components/schemas/RelativeChangeSpecSchema" }, { "$ref": "#/components/schemas/SetProbabilitySpecSchema" }, { "$ref": "#/components/schemas/AdjustProbabilitySpecSchema" }, { "$ref": "#/components/schemas/SetMembersSpecSchema" }, { "$ref": "#/components/schemas/RangeValueSpecSchema" } ], "description": "Specification of how to modify the variable." }, "conditions": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ConditionSchema" } }, { "type": "null" } ], "description": "Optional conditions defining the subpopulation for intervention." }, "detachFormula": { "type": [ "boolean", "null" ], "description": "Allow this intervention on a computed value. Its formula is switched off for the run: the variable takes the intervened value instead of being recomputed from its inputs, and its inputs do not move to match." } }, "required": [ "variable", "valueSpec" ] }, "InterventionUncertaintySchema": { "type": "object", "properties": { "meanEffect": { "type": "number", "description": "Mean effect" }, "stdEffect": { "type": "number", "description": "Standard deviation of effect" }, "confidenceInterval": { "type": "array", "items": { "type": "number" }, "description": "Confidence interval" }, "confidenceLevel": { "type": "number", "description": "Confidence level" }, "pValue": { "type": "number", "description": "P-value testing null hypothesis of no effect" }, "significant": { "type": "boolean", "description": "Whether the effect is statistically significant" }, "robustnessValue": { "type": [ "number", "null" ], "description": "Cinelli-Hazlett robustness value: share of residual variance an unmeasured confounder must explain in both treatment and outcome to move the estimate to the null (0..1)" }, "eValue": { "type": [ "number", "null" ], "description": "E-value on the risk-ratio scale; only present for binary-rate metrics" }, "eValueCiLimit": { "type": [ "number", "null" ], "description": "E-value for the confidence-interval limit closest to the null" }, "baselineInterval": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ], "description": "Percentile interval of the resampled baseline reading, on the metric's scale, at confidenceLevel" } }, "required": [ "meanEffect", "stdEffect", "confidenceInterval", "confidenceLevel", "pValue", "significant" ] }, "JoinColumnPairSchema": { "type": "object", "properties": { "leftField": { "type": "string" }, "rightField": { "type": "string" } }, "required": [ "leftField", "rightField" ] }, "JoinConflictResolutionEnum": { "type": "string", "enum": [ "keep_left", "keep_right", "prefix" ] }, "JoinTypeEnum": { "type": "string", "enum": [ "inner", "left", "right", "full" ] }, "JsonRpcRequest": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "method": { "type": "string" }, "params": { "type": [ "object", "null" ], "additionalProperties": {} }, "id": { "anyOf": [ { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] } }, "required": [ "jsonrpc", "method" ] }, "KeepEnum": { "type": "string", "enum": [ "first", "last" ] }, "KeyRoleEnum": { "type": "string", "enum": [ "primary", "foreign" ] }, "LatentClusterInfoSchema": { "type": "object", "properties": { "clusterId": { "type": "number" }, "affectedNodes": { "type": "array", "items": { "type": "string" } }, "estimatedDim": { "type": "number", "default": 1 }, "dicSatisfied": { "type": "boolean", "default": true }, "interColumnNames": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "intraColumnNames": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "modelStatus": { "anyOf": [ { "$ref": "#/components/schemas/LatentModelStatusEnum" }, { "type": "null" } ] }, "modelFailureReason": { "anyOf": [ { "$ref": "#/components/schemas/LatentFitFailureReasonEnum" }, { "type": "null" } ] }, "modelFailureDetail": { "type": [ "string", "null" ] }, "avgLcScore": { "type": [ "number", "null" ] }, "reconstructionError": { "type": [ "number", "null" ] }, "envPredictability": { "type": [ "number", "null" ] }, "memberLatentShare": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] }, "seasonalStrength": { "type": [ "number", "null" ] } }, "required": [ "clusterId", "affectedNodes" ] }, "LatentDiscoveryConfigSchema": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true }, "residualCorrelationThreshold": { "type": "number", "default": 0.3 }, "ciTestAlpha": { "type": "number", "default": 0.05 }, "minClusterSize": { "type": "number", "default": 2 }, "maxLatentDim": { "type": "number", "default": 5 } } }, "LatentFitFailureReasonEnum": { "type": "string", "enum": [ "tooFewMembers", "noNumericMembers", "noExternalParents", "allParentColumnsEmpty", "insufficientCleanRows", "fitError" ] }, "LatentModelStatusEnum": { "type": "string", "enum": [ "modelled", "detectedOnly" ] }, "LeadLagEntryResultSchema": { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" }, "lagSteps": { "type": "number" }, "correlation": { "type": "number" } }, "required": [ "source", "target", "lagSteps", "correlation" ] }, "LifecycleStateEnum": { "type": "string", "enum": [ "created", "discovering", "resolved", "training", "trained", "failed", "cancelled" ] }, "LinkSchema": { "type": "object", "properties": { "sourceIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "parentSourceId": { "type": [ "string", "null" ] } }, "required": [ "sourceIds" ] }, "LocationDetectionSourceEnum": { "type": "string", "enum": [ "values", "column_name", "user" ] }, "LogicalOperatorEnum": { "type": "string", "enum": [ "AND", "OR" ] }, "MediatorCategoricalShiftSchema": { "type": "object", "properties": { "variable": { "type": "string" }, "type": { "type": "string", "const": "categorical" }, "baselineProbs": { "type": "object", "additionalProperties": { "type": "number" } }, "interventionProbs": { "type": "object", "additionalProperties": { "type": "number" } }, "deltaProbs": { "type": "object", "additionalProperties": { "type": "number" } }, "tv": { "type": "number" }, "scope": { "type": "string", "enum": [ "cohort", "population" ], "description": "Which rows the before/after covers: 'cohort' is the rows a conditioned intervention touched; absent or 'population' is every row, which is what runs stored before cohort scoping existed" } }, "required": [ "variable", "type", "baselineProbs", "interventionProbs", "deltaProbs", "tv" ] }, "MediatorNumericShiftSchema": { "type": "object", "properties": { "variable": { "type": "string" }, "type": { "type": "string", "const": "numeric" }, "baselineMean": { "type": "number" }, "interventionMean": { "type": "number" }, "deltaMean": { "type": "number" }, "baselineStd": { "type": "number" }, "interventionStd": { "type": "number" }, "scope": { "type": "string", "enum": [ "cohort", "population" ], "description": "Which rows the before/after covers: 'cohort' is the rows a conditioned intervention touched; absent or 'population' is every row, which is what runs stored before cohort scoping existed" } }, "required": [ "variable", "type", "baselineMean", "interventionMean", "deltaMean" ] }, "MediatorShiftSchema": { "anyOf": [ { "$ref": "#/components/schemas/MediatorNumericShiftSchema" }, { "$ref": "#/components/schemas/MediatorCategoricalShiftSchema" } ] }, "MediatorShiftsForMetricSchema": { "type": "object", "properties": { "mediators": { "type": "array", "items": { "$ref": "#/components/schemas/MediatorShiftSchema" } }, "paths": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } } }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/MediatorShiftSchema" }, "description": "Before/after distributions for the path endpoints — intervened variables and metric-source columns; absent on runs stored before it existed" } }, "required": [ "mediators" ] }, "MediatorShiftsSchema": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MediatorShiftsForMetricSchema" } }, "MergeInput": { "type": "object", "properties": { "sourceConceptId": { "type": "string" }, "sourceConceptIds": { "type": "array", "items": { "type": "string" } }, "targetConceptId": { "type": "string" } }, "required": [ "sourceConceptIds", "targetConceptId" ] }, "MetadataStatusEnum": { "type": "string", "enum": [ "complete", "partial_skipped_expensive", "in_progress" ] }, "MetricConstraintSchema": { "type": "object", "properties": { "metricName": { "type": "string", "description": "Name of the metric being constrained" }, "sqlQuery": { "type": "string", "description": "SQL query to calculate the metric" }, "constraintType": { "type": "string", "enum": [ "min_value", "max_value", "max_decrease_percent", "max_increase_percent", "fixed_boolean" ], "description": "Type of constraint" }, "value": { "type": [ "number", "null" ], "description": "Constraint value (absolute for min/max, percentage for percent types)" }, "booleanValue": { "type": [ "boolean", "null" ], "description": "Boolean value for fixed_boolean constraint type" }, "temporal": { "anyOf": [ { "$ref": "#/components/schemas/TemporalMetricSpecSchema" }, { "type": "null" } ], "description": "Window the constraint is evaluated over on a temporal twin. Null means the whole forecast horizon from the first forecast step." } }, "required": [ "metricName", "sqlQuery", "constraintType" ] }, "MetricResultSchema": { "type": "object", "properties": { "name": { "type": "string" }, "baseline": { "type": [ "number", "null" ], "description": "Metric value for the baseline segment; null when the metric window produced no evaluable result" }, "intervention": { "type": [ "number", "null" ], "description": "Metric value for the intervention segment; null when the metric window produced no evaluable result" }, "windowStartMs": { "type": [ "number", "null" ], "description": "First forecast grid timestamp (ms, inclusive) the metric SQL was evaluated over; temporal twins only" }, "windowEndMs": { "type": [ "number", "null" ], "description": "Last forecast grid timestamp (ms, inclusive) the metric SQL was evaluated over; temporal twins only" } }, "required": [ "name" ] }, "MetricScaleBasisSchema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "intensive", "extensive", "unknown" ], "description": "Whether the metric's level scales with the sampled table's row count" }, "sampleRows": { "type": "number", "description": "Rows in the sampled table the metric was computed over" }, "sourceRows": { "type": [ "number", "null" ], "description": "Rows in the twin's source data; the rescale target for extensive metrics" }, "rescaled": { "type": "boolean", "default": false, "description": "Whether absolute values for this metric were rescaled" }, "rescaledTo": { "anyOf": [ { "type": "string", "enum": [ "source_rows", "single_path" ] }, { "type": "null" } ], "description": "What an extensive metric was rescaled to: the source data's row count (static) or one simulated future path (temporal)" } }, "required": [ "kind", "sampleRows" ] }, "MetricSchema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the metric" }, "sqlQuery": { "type": "string", "description": "The SQL query to calculate the metric" }, "unit": { "allOf": [ { "anyOf": [ { "not": {} }, { "type": [ "string", "null" ] } ] }, { "type": [ "string", "null" ] } ], "description": "Canonical unit id (legacy keys coerced on read)" }, "higherIsBetter": { "type": "boolean", "default": true, "description": "Whether a higher value is better for this metric" }, "temporal": { "anyOf": [ { "$ref": "#/components/schemas/TemporalMetricSpecSchema" }, { "type": "null" } ], "description": "Temporal evaluation window for time-aware metrics. Null means the whole forecast horizon from the first forecast step. Ignored by non-temporal twins." }, "conceptId": { "type": [ "string", "null" ], "description": "Ontology metric concept this SQL was materialised from, when picked from the ontology" }, "conceptEditVersion": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "editVersion of the source concept at materialisation time; drift is detected against the live concept" } }, "required": [ "name", "sqlQuery" ] }, "MultiCounterfactualExplanationSchema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CounterfactualExplanationSchema" }, "description": "List of counterfactual results, one per input sample" } }, "required": [ "results" ] }, "MultiCounterfactualRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "counterfactual" }, "samples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ], "description": "List of initial samples" }, "samplesRef": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" }, { "type": "null" } ], "description": "Datalake reference replacing inline samples" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/CounterfactualTargetSchema" }, "description": "Target variables to change for all samples" }, "constraints": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CounterfactualVariableConstraintSchema" } }, { "type": "null" } ], "description": "Constraints defining the search space (applied individually per sample). Variables not mentioned or without a FixedConstraint are implicitly changeable." }, "maxChanges": { "type": "number", "default": 3, "description": "Maximum number of variables to change per sample" } }, "required": [ "type", "targets" ] }, "MultiMatchStrategyEnum": { "type": "string", "enum": [ "first", "last", "aggregate" ] }, "NanFillStrategyEnum": { "type": "string", "enum": [ "forward", "interpolate", "zero", "drop", "undefined" ] }, "NewColumnDefinitionSchema": { "type": "object", "properties": { "name": { "type": "string" }, "pattern": { "type": [ "string", "null" ] } }, "required": [ "name" ] }, "NodeChangeSchema": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ChangeTypeEnum" }, "node": { "$ref": "#/components/schemas/CausalNodeSchema" }, "oldNode": { "anyOf": [ { "$ref": "#/components/schemas/CausalNodeSchema" }, { "type": "null" } ] } }, "required": [ "type", "node" ] }, "NodeConditionStatusResultSchema": { "type": "object", "properties": { "variable": { "type": "string" }, "alertType": { "$ref": "#/components/schemas/AlertTypeEnum" }, "currentZ": { "type": "number" }, "ewmaZ": { "type": "number" }, "trendSlope": { "type": "number" }, "cusum": { "type": "number" }, "stepsElevated": { "type": "number" }, "isRootNode": { "type": "boolean" }, "graphDepth": { "type": "number" }, "confidence": { "type": "number" }, "causalDepth": { "type": "number", "default": 0 }, "variableThreshold": { "type": [ "number", "null" ] }, "marginalZScore": { "type": "number", "default": 0 }, "explainedFraction": { "type": "number", "default": 0 }, "rootCauseScore": { "type": "number", "default": 0 }, "recovered": { "type": "boolean", "default": false } }, "required": [ "variable", "alertType", "currentZ", "ewmaZ", "trendSlope", "cusum", "stepsElevated", "isRootNode", "graphDepth", "confidence" ] }, "NodeMetricsSchema": { "type": "object", "properties": { "accuracy": { "type": [ "number", "null" ], "description": "Classification accuracy" }, "accuracyPerClass": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "Classification accuracy per class" }, "weightedAccuracy": { "type": [ "number", "null" ], "description": "Weighted classification accuracy" }, "falsePositiveRate": { "type": [ "number", "null" ], "description": "False positive rate" }, "falseNegativeRate": { "type": [ "number", "null" ], "description": "False negative rate" }, "truePositiveRate": { "type": [ "number", "null" ], "description": "True positive rate" }, "trueNegativeRate": { "type": [ "number", "null" ], "description": "True negative rate" }, "precision": { "type": [ "number", "null" ], "description": "Precision, macro-averaged across classes" }, "recall": { "type": [ "number", "null" ], "description": "Recall, macro-averaged across classes" }, "f1Score": { "type": [ "number", "null" ], "description": "F1 score, macro-averaged across classes" }, "precisionPerClass": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "Precision per class" }, "recallPerClass": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "Recall per class" }, "f1ScorePerClass": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "F1 score per class" }, "positiveClassLabel": { "type": [ "string", "null" ], "description": "Decoded label of encoded class 1, the anchor for TPR/FPR/TNR/FNR" }, "mse": { "type": [ "number", "null" ], "description": "Mean squared error" }, "r2": { "type": [ "number", "null" ], "description": "R-squared" }, "logLikelihood": { "type": [ "number", "null" ], "description": "Log-likelihood" }, "auc": { "type": [ "number", "null" ], "description": "Area under ROC curve" }, "brierScore": { "type": [ "number", "null" ], "description": "Brier score" }, "mae": { "type": [ "number", "null" ], "description": "Mean absolute error" }, "mape": { "anyOf": [ { "type": "object", "additionalProperties": { "type": [ "number", "null" ] } }, { "type": "null" } ], "description": "Mean absolute percentage error per horizon" } } }, "NodeParentImpactsSchema": { "type": "object", "properties": { "node": { "type": "string" }, "method": { "type": "string", "enum": [ "forecast_attribution", "fwl_betas", "gaamt_betas", "cat_logit_betas", "do_contrast" ] }, "parents": { "type": "array", "items": { "$ref": "#/components/schemas/ParentImpactEntrySchema" } }, "exogenous": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ParentImpactEntrySchema" } }, { "type": "null" } ], "description": "Trend/seasonal/level drivers on the same 0-100 scale as parents" }, "nonParentShare": { "type": [ "number", "null" ] } }, "required": [ "node", "method", "parents" ] }, "NodeSurpriseResultSchema": { "type": "object", "properties": { "variable": { "type": "string" }, "observedValue": { "type": "number" }, "expectedMean": { "type": "number" }, "expectedStd": { "type": "number" }, "zScore": { "type": "number" }, "conditionalPercentile": { "type": "number" }, "marginalZScore": { "type": "number", "default": 0 }, "graphDepth": { "type": "number", "default": 0 }, "isRootNode": { "type": "boolean", "default": false }, "explainedFraction": { "type": "number", "default": 0 }, "rootCauseScore": { "type": "number", "default": 0 }, "confidence": { "type": "number", "default": 1 }, "nConditionalSamples": { "type": "number", "default": 0 }, "isLatent": { "type": "boolean", "default": false }, "actionability": { "$ref": "#/components/schemas/ActionabilityEnum", "default": "observable" }, "variableThreshold": { "type": [ "number", "null" ] } }, "required": [ "variable", "observedValue", "expectedMean", "expectedStd", "zScore", "conditionalPercentile" ] }, "NodeTypeEnum": { "type": "string", "enum": [ "observed", "latent", "latent_inter", "latent_intra", "environment" ] }, "NormalizeNumericMethodEnum": { "type": "string", "enum": [ "min_max", "z_score" ] }, "objectiveUnitReadSchema": { "allOf": [ { "anyOf": [ { "not": {} }, { "type": [ "string", "null" ] } ] }, { "type": [ "string", "null" ] } ] }, "OntologyConceptEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/OntologyConcept" } }, "required": [ "data" ] }, "OntologyConceptListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OntologyConcept" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Pass back as ?cursor= to fetch the next page" }, "hasMore": { "type": "boolean", "description": "Whether a further page exists" }, "total": { "type": "number", "description": "Total matching rows, when the query can count them" } }, "required": [ "hasMore" ] } }, "required": [ "data", "pagination" ] }, "OntologyModeEnum": { "type": "string", "enum": [ "auto", "manual" ] }, "OntologyQueryInput": { "type": "object", "properties": { "anchorSql": { "type": "string", "minLength": 1, "description": "Anchor SQL statement over ontology concepts. Reference concepts by name — the ontology plans the joins, time alignment and location matching; most queries need no FROM clause (scope explicitly with FROM source:\"name\", dataset:\"name\" or tag:\"name\" when needed). SHOW/DESCRIBE metadata commands are also accepted. Workspace and organisation ids are injected from the auth context." }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Rows per page (default 1000). Page through the full result with startKey; an Anchor SQL LIMIT still caps the statement itself." }, "startKey": { "type": "integer", "minimum": 0, "description": "Resume paging from a rows response's nextStartKey" }, "validateOnly": { "type": "boolean", "description": "Compile and plan without executing; the response is the validated arm carrying the plan and warnings" }, "projectionMode": { "type": "string", "enum": [ "related", "minimal" ], "description": "related adds ontology-linked context columns; minimal returns only the selected concepts and their anchors" } }, "required": [ "anchorSql" ] }, "OntologyStatusEnum": { "type": "string", "enum": [ "pending", "extracting", "consolidation_queued", "consolidating", "detecting_derived", "analyzing_dependencies", "profiling_time_series", "completed", "extraction_failed", "consolidation_failed", "derived_detection_failed", "relationship_detection_failed", "cross_relationship_detection_failed", "dependency_analysis_failed", "time_series_profiling_failed", "cancelled", "manual_pending" ] }, "OntologyValueMapEntriesSchema": { "type": "array", "items": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" } ], "items": false, "minItems": 2, "maxItems": 2 } }, "OntologyValueMapSchema": { "anyOf": [ { "$ref": "#/components/schemas/OntologyValueMapEntriesSchema" }, { "$ref": "#/components/schemas/OntologyValueMapEntriesSchema" } ] }, "OperationConfigSchema": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "FILTER" }, "filterGroup": { "anyOf": [ { "$ref": "#/components/schemas/FilterSchema" }, { "$ref": "#/components/schemas/FilterGroupSchema" } ] } }, "required": [ "type", "filterGroup" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "AGGREGATE" }, "groupByColumns": { "type": "array", "items": { "type": "string" } }, "aggregations": { "type": "array", "items": { "$ref": "#/components/schemas/AggregationFunctionSchema" } } }, "required": [ "type", "groupByColumns", "aggregations" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "JOIN" }, "joinType": { "$ref": "#/components/schemas/JoinTypeEnum" }, "columnPairs": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/JoinColumnPairSchema" } }, { "type": "null" } ] }, "leftField": { "type": [ "string", "null" ] }, "rightField": { "type": [ "string", "null" ] }, "conflictResolution": { "$ref": "#/components/schemas/JoinConflictResolutionEnum" }, "leftPrefix": { "type": [ "string", "null" ] }, "rightPrefix": { "type": [ "string", "null" ] } }, "required": [ "type", "joinType", "conflictResolution" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "CONCATENATE" }, "topSource": { "type": [ "string", "null" ] }, "bottomSource": { "type": [ "string", "null" ] }, "sources": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "columnMapping": { "type": "object", "additionalProperties": { "type": "string" } }, "unmatchedRule": { "$ref": "#/components/schemas/UnmatchedRuleEnum" }, "discriminatorColumn": { "type": [ "string", "null" ] }, "discriminatorValues": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "type", "columnMapping", "unmatchedRule" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "SORT" }, "sortColumns": { "type": "array", "items": { "$ref": "#/components/schemas/SortColumnSchema" } } }, "required": [ "type", "sortColumns" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "SQL_QUERY" }, "query": { "type": "string" }, "columnSourceAliases": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "type", "query" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "SPLIT_COLUMN" }, "columnToSplit": { "type": "string" }, "splitType": { "$ref": "#/components/schemas/SplitTypeEnum" }, "delimiter": { "type": [ "string", "null" ] }, "columns": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/NewColumnDefinitionSchema" } }, { "type": "null" } ] } }, "required": [ "type", "columnToSplit", "splitType" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "DROP_COLUMNS" }, "columns": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "columns" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "REMOVE_DUPLICATES" }, "column": { "type": [ "string", "null" ] }, "keep": { "$ref": "#/components/schemas/KeepEnum", "default": "first" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "IMPUTE_NULLS" }, "method": { "$ref": "#/components/schemas/ImputeMethodEnum", "default": "constant" }, "column": { "type": [ "string", "null" ] }, "fillValue": { "anyOf": [ { "type": [ "string", "number", "boolean" ] }, { "type": "null" } ] }, "imputations": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "string" }, "method": { "$ref": "#/components/schemas/ImputeMethodEnum", "default": "constant" }, "fillValue": { "anyOf": [ { "type": [ "string", "number", "boolean" ] }, { "type": "null" } ] } }, "required": [ "column" ] } }, { "type": "null" } ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "DROP_NULLS" }, "axis": { "type": "string", "enum": [ "rows", "empty_columns" ], "default": "rows" }, "column": { "type": [ "string", "null" ] }, "columns": { "type": "array", "items": { "type": "string" }, "default": [] }, "nullThresholdPercent": { "type": "number", "default": 100 } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "REPLACE_VALUES" }, "column": { "type": "string" }, "mapping": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } } }, "required": [ "type", "column", "mapping" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "REPLACE_TYPE" }, "changes": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "string" }, "toType": { "$ref": "#/components/schemas/SchemaMainTypeEnum" }, "toSubType": { "anyOf": [ { "$ref": "#/components/schemas/SchemaSubTypeEnum" }, { "type": "null" } ] }, "dateFormat": { "type": [ "string", "null" ] } }, "required": [ "column", "toType" ] } }, { "type": "null" } ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "INTERPOLATE_TIME" }, "column": { "type": "string" }, "frequency": { "type": "string" }, "method": { "$ref": "#/components/schemas/InterpolateTimeMethodEnum" } }, "required": [ "type", "column", "frequency", "method" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "CLIP_OUTLIERS" }, "column": { "type": "string" }, "lowerQuantile": { "type": "number", "default": 0.05 }, "upperQuantile": { "type": "number", "default": 0.95 } }, "required": [ "type", "column" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "NORMALIZE_NUMERIC" }, "column": { "type": "string" }, "method": { "$ref": "#/components/schemas/NormalizeNumericMethodEnum", "default": "z_score" } }, "required": [ "type", "column" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "MAP_CATEGORIES" }, "column": { "type": "string" }, "mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "defaultValue": { "type": [ "string", "null" ] } }, "required": [ "type", "column", "mapping" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "TIME_SERIES_AGGREGATE" }, "timeColumn": { "type": "string" }, "granularity": { "type": "string", "enum": [ "nanosecond", "microsecond", "millisecond", "second", "minute", "hour", "day", "week", "month", "quarter", "year" ] }, "aggregations": { "type": "array", "items": { "$ref": "#/components/schemas/AggregationFunctionSchema" } }, "dateFormat": { "anyOf": [ { "$ref": "#/components/schemas/DatetimeFormatSchema" }, { "type": "null" } ] } }, "required": [ "type", "timeColumn", "granularity", "aggregations" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "TIME_SERIES_JOIN" }, "joinType": { "$ref": "#/components/schemas/JoinTypeEnum" }, "leftTimeColumn": { "type": "string" }, "rightTimeColumn": { "type": "string" }, "rightSource": { "type": "string" }, "strategy": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "exact" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "granularity" }, "granularity": { "type": "string", "enum": [ "nanosecond", "microsecond", "millisecond", "second", "minute", "hour", "day", "week", "month", "quarter", "year" ] } }, "required": [ "type", "granularity" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "asOf" }, "direction": { "$ref": "#/components/schemas/AsOfDirectionEnum" }, "tolerance": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "$ref": "#/components/schemas/ToleranceUnitEnum" } }, "required": [ "value", "unit" ] }, { "type": "null" } ] } }, "required": [ "type", "direction" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "interval" }, "leftEndColumn": { "type": "string" } }, "required": [ "type", "leftEndColumn" ] } ], "discriminator": { "propertyName": "type" } }, "exactMatchKeys": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "leftField": { "type": "string" }, "rightField": { "type": "string" } }, "required": [ "leftField", "rightField" ] } }, { "type": "null" } ] }, "multiMatch": { "$ref": "#/components/schemas/MultiMatchStrategyEnum" }, "multiMatchAggregations": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/AggregationFunctionSchema" } }, { "type": "null" } ] } }, "required": [ "type", "joinType", "leftTimeColumn", "rightTimeColumn", "rightSource", "strategy", "multiMatch" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "TRANSPOSE" }, "timeColumn": { "type": "string" }, "envColumns": { "type": "array", "items": { "type": "string" } }, "valueColumns": { "type": "array", "items": { "type": "string" } }, "columnTemplate": { "type": "string" }, "joinStrategy": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "exact" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "granularity" }, "granularity": { "type": "string", "enum": [ "nanosecond", "microsecond", "millisecond", "second", "minute", "hour", "day", "week", "month", "quarter", "year" ] } }, "required": [ "type", "granularity" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "asOf" }, "direction": { "$ref": "#/components/schemas/AsOfDirectionEnum" }, "tolerance": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "$ref": "#/components/schemas/ToleranceUnitEnum" } }, "required": [ "value", "unit" ] }, { "type": "null" } ] } }, "required": [ "type", "direction" ] } ], "discriminator": { "propertyName": "type" } }, { "type": "null" } ] } }, "required": [ "type", "timeColumn", "envColumns", "valueColumns", "columnTemplate" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "FREQUENCY_ANALYSIS" }, "timeColumn": { "type": "string" }, "valueColumns": { "type": "array", "items": { "type": "string" } }, "method": { "$ref": "#/components/schemas/FrequencyMethodEnum" }, "windowFunction": { "$ref": "#/components/schemas/FrequencyWindowFunctionEnum", "default": "hann" }, "windowSize": { "type": [ "number", "null" ] }, "overlap": { "type": "number", "default": 0.5 }, "samplingRateHz": { "type": [ "number", "null" ] }, "outputFormat": { "$ref": "#/components/schemas/FrequencyOutputFormatEnum" }, "frequencyRange": { "anyOf": [ { "type": "object", "properties": { "minHz": { "type": [ "number", "null" ] }, "maxHz": { "type": [ "number", "null" ] } } }, { "type": "null" } ] }, "frequencyUnit": { "$ref": "#/components/schemas/FrequencyUnitEnum", "default": "hz" } }, "required": [ "type", "timeColumn", "valueColumns", "method", "outputFormat" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "CYCLIC_AGGREGATE" }, "timeColumn": { "type": "string" }, "cycleComponent": { "$ref": "#/components/schemas/CyclicComponentEnum" }, "aggregations": { "type": "array", "items": { "$ref": "#/components/schemas/AggregationFunctionSchema" } } }, "required": [ "type", "timeColumn", "cycleComponent", "aggregations" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "DIFF" }, "timeColumn": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "partitionColumns": { "type": "array", "items": { "type": "string" }, "default": [] }, "outputSuffix": { "type": "string", "default": "_diff" }, "replaceColumns": { "type": "boolean", "default": false } }, "required": [ "type", "timeColumn", "columns" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "DATE_DIFF" }, "startColumn": { "type": "string" }, "endColumn": { "type": "string" }, "unit": { "$ref": "#/components/schemas/DateDiffUnitEnum", "default": "days" }, "sign": { "$ref": "#/components/schemas/DateDiffSignEnum", "default": "signed" }, "outputColumn": { "type": [ "string", "null" ] } }, "required": [ "type", "startColumn", "endColumn" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "CUMULATIVE" }, "timeColumn": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "partitionColumns": { "type": "array", "items": { "type": "string" }, "default": [] }, "outputSuffix": { "type": "string", "default": "_cumsum" }, "replaceColumns": { "type": "boolean", "default": false } }, "required": [ "type", "timeColumn", "columns" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "ARRAY_DECOMPOSE" }, "column": { "type": "string" }, "mode": { "$ref": "#/components/schemas/ArrayDecomposeModeEnum", "default": "position" }, "maxColumns": { "type": "integer", "exclusiveMinimum": 0, "default": 500 }, "outputPrefix": { "type": "string", "default": "_" } }, "required": [ "type", "column" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "ARRAY_CONSOLIDATE" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "outputColumn": { "type": "string" }, "dropSource": { "type": "boolean", "default": true }, "includeNulls": { "type": "boolean", "default": false } }, "required": [ "columns", "outputColumn" ] }, "minItems": 1 } }, "required": [ "type", "groups" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "ARRAY_EXPLODE" }, "column": { "type": "string" }, "outputColumn": { "type": [ "string", "null" ] }, "preserveIndex": { "type": "boolean", "default": false } }, "required": [ "type", "column" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "ARRAY_AGGREGATE" }, "column": { "type": "string" }, "aggregation": { "$ref": "#/components/schemas/ArrayAggregationKindEnum" }, "outputColumn": { "type": [ "string", "null" ] } }, "required": [ "type", "column", "aggregation" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "JSON_FLATTEN" }, "column": { "type": "string" }, "maxColumns": { "type": "integer", "exclusiveMinimum": 0, "default": 500 }, "separator": { "type": "string", "default": "." }, "dropSource": { "type": "boolean", "default": true } }, "required": [ "type", "column" ] } ], "discriminator": { "propertyName": "type" } }, "OperationLineageSchema": { "type": "object", "properties": { "opType": { "$ref": "#/components/schemas/OperationTypeEnum" }, "opId": { "type": "string" }, "parentColumns": { "type": "array", "items": { "type": "string" }, "default": [] }, "parentConceptIds": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "opType", "opId" ] }, "OperationSchema": { "type": "object", "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "config": { "$ref": "#/components/schemas/OperationConfigSchema" } }, "required": [ "id", "sourceId", "config" ] }, "OperationTypeEnum": { "type": "string", "enum": [ "SQL_QUERY", "FILTER", "AGGREGATE", "JOIN", "CONCATENATE", "SORT", "SPLIT_COLUMN", "DROP_COLUMNS", "REMOVE_DUPLICATES", "IMPUTE_NULLS", "DROP_NULLS", "REPLACE_VALUES", "REPLACE_TYPE", "INTERPOLATE_TIME", "CLIP_OUTLIERS", "NORMALIZE_NUMERIC", "MAP_CATEGORIES", "TIME_SERIES_AGGREGATE", "TIME_SERIES_JOIN", "TRANSPOSE", "FREQUENCY_ANALYSIS", "CYCLIC_AGGREGATE", "DIFF", "DATE_DIFF", "CUMULATIVE", "ARRAY_DECOMPOSE", "ARRAY_CONSOLIDATE", "ARRAY_EXPLODE", "ARRAY_AGGREGATE", "JSON_FLATTEN" ] }, "OptimisationObjectiveSchema": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "maximise", "minimise" ], "description": "The direction of the optimization" }, "variable": { "type": "string", "description": "A descriptive name for this objective/metric (e.g., 'Total Revenue', 'Customer Churn Rate'). Used as a label, not necessarily a variable in the causal graph." }, "metricSqlQuery": { "type": "string", "description": "SQL query to calculate the metric" }, "unit": { "$ref": "#/components/schemas/objectiveUnitReadSchema", "description": "Canonical unit id (legacy keys coerced on read). Omit for objectives without a meaningful unit." }, "weight": { "type": "number", "default": 1, "description": "Weight of this objective in multi-objective optimization" }, "variablesRelevantToMetric": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Variables causally relevant to the metric" }, "target": { "anyOf": [ { "$ref": "#/components/schemas/OptimisationTargetSchema" }, { "type": "null" } ], "description": "Optional target specification (absolute value or percentage improvement)" }, "conceptId": { "type": [ "string", "null" ], "description": "Ontology metric concept this SQL was materialised from, when picked from the ontology" }, "conceptEditVersion": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "editVersion of the source concept at materialisation time; drift is detected against the live concept" } }, "required": [ "direction", "variable", "metricSqlQuery" ] }, "OptimisationScenarioSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "optimisation" }, "objectives": { "type": "array", "items": { "$ref": "#/components/schemas/OptimisationObjectiveSchema" }, "description": "The objectives to optimize" }, "conditions": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ConditionSchema" } }, { "type": "null" } ], "description": "Dead field, ignored by the optimizer: subpopulation scoping goes through segmentDefinitions + enableSegmentInterventions. Kept so stored scenarios still parse." }, "decisionVars": { "type": "array", "items": { "type": "string" }, "description": "Variables that can be manipulated during optimization" }, "variableConstraints": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/VariableConstraintSchema" } }, { "type": "null" } ], "description": "Constraints on variable values and changes" }, "metricConstraints": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/MetricConstraintSchema" } }, { "type": "null" } ], "description": "Constraints on metric values" }, "segmentDefinitions": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDefinitionSchema" } }, { "type": "null" } ], "description": "Segment definitions for segment-aware interventions and per-segment results" }, "enableSegmentInterventions": { "type": "boolean", "default": false, "description": "Whether to explore segment-specific interventions" }, "interventionTypes": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ], "description": "Map of variable name to intervention type: 'set_value', 'relative_percentage', 'relative_absolute', 'set_probability'" }, "interventionCountConfig": { "anyOf": [ { "$ref": "#/components/schemas/InterventionCountConfigSchema" }, { "type": "null" } ], "description": "Configuration for intervention count optimization" } }, "required": [ "type", "objectives", "decisionVars" ] }, "OptimisationTargetSchema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "absolute", "percentage" ], "default": "percentage", "description": "Whether target is an absolute value or percentage change from baseline" }, "value": { "type": [ "number", "null" ], "description": "Target value. None means just optimize in the specified direction without a specific target." } } }, "OptimizationResultSchema": { "type": "object", "properties": { "paretoFront": { "type": "array", "items": { "$ref": "#/components/schemas/ParetoDominantSolutionSchema" }, "description": "Pareto-optimal solutions" }, "optimizationTrace": { "type": "array", "items": { "$ref": "#/components/schemas/OptimizationTraceSchema" }, "description": "Record of optimization progress" }, "baselineMetrics": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Baseline metrics for objectives" }, "constraintBaselineMetrics": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "Baseline metrics for constraint metrics" }, "balancedSolution": { "anyOf": [ { "$ref": "#/components/schemas/ParetoDominantSolutionSchema" }, { "type": "null" } ], "description": "Balanced solution closest to ideal point (for multi-objective)" }, "bestPerObjective": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ParetoDominantSolutionSchema" } }, { "type": "null" } ], "description": "Best solution for each individual objective" }, "allConstraintsSatisfiable": { "type": "boolean", "default": true, "description": "Whether any solution satisfying all constraints was found" }, "executionTime": { "type": "number", "default": 0, "description": "Execution time in seconds" }, "metricScaleBases": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MetricScaleBasisSchema" } }, { "type": "null" } ], "description": "Per-metric scale basis: intensive metrics read directly from the simulation, extensive ones are rescaled to the source data's row count" } }, "required": [ "paretoFront", "optimizationTrace", "baselineMetrics" ] }, "OptimizationTraceSchema": { "type": "object", "properties": { "iteration": { "type": "number", "description": "Iteration number" }, "bestObjectiveValues": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Best objective values found" }, "populationDiversity": { "type": "number", "description": "Diversity of the population" } }, "required": [ "iteration", "bestObjectiveValues", "populationDiversity" ] }, "OrgSourceEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": [ "string", "null" ] }, "organisationId": { "type": "string" }, "name": { "type": "string" }, "parentSourceId": { "type": [ "string", "null" ] }, "dataSource": { "anyOf": [ { "$ref": "#/components/schemas/DataSourceTypeEnum" }, { "type": "null" } ] }, "dataFormat": { "$ref": "#/components/schemas/datasetFormatsEnum" }, "description": { "type": [ "string", "null" ] }, "maintainedBy": { "type": "array", "items": { "type": "object", "properties": { "applicationId": { "type": "string" }, "version": { "type": "string" }, "flowId": { "type": "string" } }, "required": [ "applicationId", "version", "flowId" ] } }, "richDescription": { "anyOf": [ { "$ref": "#/components/schemas/RichDescriptionSchema" }, { "type": "null" } ] }, "schemaEntries": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SchemaEntryModelSchema" } }, { "type": "null" } ] }, "importWarnings": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "ontologyMode": { "$ref": "#/components/schemas/OntologyModeEnum", "default": "auto" }, "documentCount": { "type": [ "number", "null" ] }, "columnMetadata": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ColumnMetadataSchema" } }, { "type": "null" } ] }, "extension": { "type": [ "string", "null" ] }, "totalSize": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "lastSaved": { "type": [ "string", "null" ] }, "virtual": { "type": [ "boolean", "null" ] }, "ontologyStatus": { "anyOf": [ { "$ref": "#/components/schemas/OntologyStatusEnum" }, { "type": "null" } ] }, "ontologyError": { "type": [ "string", "null" ] }, "extractionStatus": { "anyOf": [ { "$ref": "#/components/schemas/ExtractionStatusEnum" }, { "type": "null" } ] }, "extractionError": { "type": [ "string", "null" ] }, "pageCount": { "type": [ "number", "null" ] }, "derivedFromDatasetIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "derivedVia": { "anyOf": [ { "$ref": "#/components/schemas/DerivedViaEnum" }, { "type": "null" } ] }, "extractionRecipe": { "anyOf": [ { "$ref": "#/components/schemas/ExtractionRecipeSchema" }, { "type": "null" } ] }, "pendingAnnotationCount": { "type": [ "number", "null" ] }, "ontologyExcludedFields": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string", "enum": [ "auto", "user", "suggestion" ] } }, "required": [ "field", "reason", "source" ] } }, { "type": "null" } ] }, "batchRanges": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "hash": { "type": "string" }, "fileName": { "type": "string" }, "uploadedAt": { "type": "string" }, "rowStart": { "type": "number" }, "rowEnd": { "type": "number" } }, "required": [ "hash", "fileName", "uploadedAt", "rowStart", "rowEnd" ] } }, { "type": "null" } ] }, "currentVersionId": { "type": [ "string", "null" ] }, "latestVersionOrdinal": { "type": [ "number", "null" ] }, "staging": { "type": [ "boolean", "null" ] }, "readMode": { "type": "string", "enum": [ "direct_query", "snapshot" ], "description": "How this source is read. direct_query runs every read against the origin database — live, but subject to its statement timeout, and no row count is recorded; snapshot reads a stored copy, which changes only when it is synced" }, "directQuery": { "anyOf": [ { "$ref": "#/components/schemas/directQuerySettingsSchema" }, { "type": "null" } ], "description": "How a direct_query source is read. Null on a snapshot source, where none of it applies. The relation itself is not reported: on a storage source it is resolved against the bucket inside the connector's encrypted credentials, which the connector routes strip" }, "linkedWorkspaceIds": { "type": "array", "items": { "type": "string" }, "description": "Workspaces this source is linked into" } }, "required": [ "id", "organisationId", "name", "dataFormat", "readMode", "directQuery", "linkedWorkspaceIds" ] } }, "required": [ "data" ] }, "PaginatedEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": {}, "description": "Payload not declared in this repo" }, "pagination": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Pass back as ?cursor= to fetch the next page" }, "hasMore": { "type": "boolean", "description": "Whether a further page exists" }, "total": { "type": "number", "description": "Total matching rows, when the query can count them" } }, "required": [ "hasMore" ] } }, "required": [ "data", "pagination" ] }, "PanelAggregateMetricStatsSchema": { "type": "object", "properties": { "environmentCount": { "type": [ "number", "null" ] }, "environmentsWithoutEffect": { "type": [ "number", "null" ] }, "meanEffect": { "type": [ "number", "null" ] }, "medianEffect": { "type": [ "number", "null" ] }, "p10Effect": { "type": [ "number", "null" ] }, "p90Effect": { "type": [ "number", "null" ] }, "shareNegative": { "type": [ "number", "null" ] }, "sharePositive": { "type": [ "number", "null" ] }, "baselineMean": { "type": [ "number", "null" ] }, "interventionMean": { "type": [ "number", "null" ] }, "medianRelativeEffect": { "type": [ "number", "null" ] }, "shareSignificant": { "type": [ "number", "null" ] } } }, "PanelAnomalyDetectionRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "panel_anomaly_detection" }, "samples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ] }, "samplesRef": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" }, { "type": "null" } ] }, "startStep": { "type": [ "number", "null" ] }, "endStep": { "type": [ "number", "null" ] }, "targetFpr": { "type": "number", "minimum": 0.0001, "maximum": 0.1, "default": 0.005 }, "parentToleranceSigma": { "type": "number", "default": 0.5 }, "autoRcaTopK": { "type": "integer", "minimum": 0, "default": 1 }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "panelSamples": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, { "type": "null" } ] }, "panelSamplesRef": { "anyOf": [ { "$ref": "#/components/schemas/PanelScenarioSamplesRefSchema" }, { "type": "null" } ] } }, "required": [ "type" ] }, "PanelAnomalyDetectionResultSchema": { "type": "object", "properties": { "environmentResults": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TemporalAnomalyDetectionResultSchema" } } }, "required": [ "environmentResults" ] }, "PanelCausalHealthMonitorRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "panel_causal_health_monitor" }, "dataSource": { "$ref": "#/components/schemas/ChmDataSourceSchema", "default": "observed" }, "samples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ] }, "samplesRef": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" }, { "type": "null" } ] }, "forecastHorizon": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "startStep": { "type": [ "number", "null" ] }, "endStep": { "type": [ "number", "null" ] }, "targetFpr": { "type": "number", "minimum": 0.0001, "maximum": 0.1, "default": 0.005 }, "parentToleranceSigma": { "type": "number", "default": 0.5 }, "autoRca": { "type": "boolean", "default": true }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "panelSamples": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, { "type": "null" } ] }, "panelSamplesRef": { "anyOf": [ { "$ref": "#/components/schemas/PanelScenarioSamplesRefSchema" }, { "type": "null" } ] } }, "required": [ "type" ] }, "PanelCausalHealthMonitorResultSchema": { "type": "object", "properties": { "environmentResults": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CausalHealthMonitorResultSchema" } } }, "required": [ "environmentResults" ] }, "PanelCounterfactualRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "panel_counterfactual" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/TemporalCounterfactualTargetSchema" } }, "constraints": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CounterfactualVariableConstraintSchema" } }, { "type": "null" } ] }, "maxChanges": { "type": "number", "default": 3 }, "forecastHorizon": { "type": [ "number", "null" ] }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Specific environments for counterfactual. None = all environments" }, "samples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ], "description": "Multi-environment static panels only: baseline states to improve, applied in every environment in scope. Temporal panels solve from the twin's own trajectory and ignore this." } }, "required": [ "type", "targets" ] }, "PanelCounterfactualResultSchema": { "type": "object", "properties": { "environmentResults": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TemporalCounterfactualExplanationSchema" }, "description": "Counterfactual results per environment" } }, "required": [ "environmentResults" ] }, "PanelExplanationRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "panel_explanation" }, "explanationMode": { "anyOf": [ { "$ref": "#/components/schemas/ExplanationModeSchema" }, { "type": "null" } ], "description": "Explicit explanation mode selection" }, "causeVariable": { "type": [ "string", "null" ] }, "effectVariable": { "type": [ "string", "null" ] }, "segments": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDefinitionSchema" } }, { "type": "null" } ] }, "forecastHorizonOverride": { "type": [ "number", "null" ] }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Specific environments for explanation. None = all environments" } }, "required": [ "type" ] }, "PanelExplanationResultSchema": { "type": "object", "properties": { "environmentResults": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TemporalExplanationResultSchema" }, "description": "Explanation results per environment" } }, "required": [ "environmentResults" ] }, "PanelForecastRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "panel_forecast" }, "forecastH": { "type": "number", "description": "Number of steps to forecast" }, "targetVars": { "type": "array", "items": { "type": "string" }, "description": "Target variables to forecast" }, "confidenceLevel": { "type": [ "number", "null" ], "default": 0.95, "description": "Confidence level for intervals" }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Specific environments to forecast. None = all environments" }, "aggregateMode": { "anyOf": [ { "$ref": "#/components/schemas/AggregateModeEnum" }, { "type": "null" } ], "description": "How to aggregate across environments. Unset defaults to avg at execution — every panel forecast stores an aggregate" }, "originTimestamp": { "type": [ "number", "null" ], "description": "Forecast as-of timestamp (ms epoch). Overrides forecastFrom per environment." } }, "required": [ "type", "forecastH", "targetVars" ] }, "PanelForecastResultSchema": { "type": "object", "properties": { "environmentResults": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DigitalTwinPredictionResultSchema" }, "description": "Forecast results per environment" }, "aggregateResult": { "anyOf": [ { "$ref": "#/components/schemas/DigitalTwinPredictionResultSchema" }, { "type": "null" } ], "description": "Aggregated forecast result across environments" }, "environmentCoverage": { "anyOf": [ { "$ref": "#/components/schemas/EnvironmentCoverageSchema" }, { "type": "null" } ], "description": "Requested-vs-forecast environment coverage; absent on runs that predate tracking and read as full" } }, "required": [ "environmentResults" ] }, "PanelInterventionAggregateSchema": { "type": "object", "properties": { "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricResultSchema" }, "description": "Intervention metrics" }, "sampleSize": { "type": "number", "description": "Number of samples used" }, "causalPaths": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "Causal paths from intervention to target" }, "causalPathsByMetric": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "description": "Causal paths per metric name" }, "segmentAnalysis": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentEffectSchema" }, "description": "Segment-specific effects" }, "uncertainty": { "type": "object", "properties": { "meanEffect": { "type": "number", "description": "Mean effect" }, "stdEffect": { "type": "number", "description": "Standard deviation of effect" }, "confidenceInterval": { "type": "array", "items": { "type": "number" }, "description": "Confidence interval" }, "confidenceLevel": { "type": "number", "description": "Confidence level" }, "pValue": { "type": "number", "description": "P-value testing null hypothesis of no effect" }, "significant": { "type": "boolean", "description": "Whether the effect is statistically significant" }, "robustnessValue": { "type": [ "number", "null" ], "description": "Cinelli-Hazlett robustness value: share of residual variance an unmeasured confounder must explain in both treatment and outcome to move the estimate to the null (0..1)" }, "eValue": { "type": [ "number", "null" ], "description": "E-value on the risk-ratio scale; only present for binary-rate metrics" }, "eValueCiLimit": { "type": [ "number", "null" ], "description": "E-value for the confidence-interval limit closest to the null" }, "baselineInterval": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ], "description": "Percentile interval of the resampled baseline reading, on the metric's scale, at confidenceLevel" } }, "required": [ "meanEffect", "stdEffect", "confidenceInterval", "confidenceLevel", "pValue", "significant" ], "description": "Uncertainty quantification" }, "uncertainties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/InterventionUncertaintySchema" }, "description": "Per-metric bootstrap uncertainties" }, "mediatorShifts": { "$ref": "#/components/schemas/MediatorShiftsSchema", "description": "Per-metric mediator shifts: {metricName: {mediators: [...], paths: {...}}}" }, "robustness": { "$ref": "#/components/schemas/InterventionRobustnessScoreInlineSchema", "description": "Robustness score for panel data interventions" }, "interventionValues": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ], "description": "Pre/post value per intervened variable: {variable: {baseline, intervention}}" }, "sweptVariable": { "type": [ "string", "null" ], "description": "Variable swept by a `range` intervention, when the scenario carried one" }, "sweptMode": { "anyOf": [ { "type": "string", "enum": [ "absolute", "percentage" ] }, { "type": "null" } ], "description": "Units of the sweep grid — percentage grids apply relative changes and share units with percent dials" }, "doseResponse": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DoseResponseAnalysisSchema" } }, { "type": "null" } ], "description": "Per-metric sweep curve keyed by metric name, present only for range scenarios" }, "executionTime": { "type": "number", "description": "Execution time in seconds" }, "originalInterventions": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/TimeSeriesInterventionSchema" }, { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesInterventionSchema" } } ] } }, { "type": "null" } ], "description": "Original intervention spec as provided by user (preserves sequences and ramps)" }, "expandedInterventions": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesInterventionSchema" } }, "description": "Mapping from timestamp to the concrete interventions applied at that time" }, "forecastData": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TimeSeriesForecastSchema" }, "description": "Time series forecasts for intervened variables, mediators, and outcomes" }, "forecastStartMs": { "type": [ "number", "null" ], "description": "First forecast grid timestamp (ms): the step after the training data ends" }, "forecastEndMs": { "type": [ "number", "null" ], "description": "Last forecast grid timestamp (ms, inclusive)" }, "crossEnvironment": { "anyOf": [ { "$ref": "#/components/schemas/CrossEnvironmentStatsSchema" }, { "type": "null" } ], "description": "Distribution of per-environment effects, which the mean result cannot express" } }, "required": [ "metrics", "sampleSize", "uncertainty", "executionTime" ] }, "PanelInterventionResultSchema": { "type": "object", "properties": { "environmentResults": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TimeSeriesInterventionResultSchema" }, "description": "Intervention results per environment" }, "aggregateResult": { "anyOf": [ { "$ref": "#/components/schemas/PanelInterventionAggregateSchema" }, { "type": "null" } ], "description": "All-environments aggregate shaped like a per-environment result" } }, "required": [ "environmentResults" ] }, "PanelInterventionSpecSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "panel_intervention" }, "interventions": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/TimeSeriesInterventionSchema" }, { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesInterventionSchema" } } ] }, "description": "A list of interventions or sequences" }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the metric" }, "sqlQuery": { "type": "string", "description": "The SQL query to calculate the metric" }, "unit": { "allOf": [ { "anyOf": [ { "not": {} }, { "type": [ "string", "null" ] } ] }, { "type": [ "string", "null" ] } ], "description": "Canonical unit id (legacy keys coerced on read)" }, "higherIsBetter": { "type": "boolean", "default": true, "description": "Whether a higher value is better for this metric" }, "temporal": { "anyOf": [ { "$ref": "#/components/schemas/TemporalMetricSpecSchema" }, { "type": "null" } ], "description": "Temporal evaluation spec for time-aware metrics. Null for static panel models." }, "conceptId": { "type": [ "string", "null" ], "description": "Ontology metric concept this SQL was materialised from, when picked from the ontology" }, "conceptEditVersion": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "editVersion of the source concept at materialisation time; drift is detected against the live concept" } }, "required": [ "name", "sqlQuery" ] }, "description": "SQL queries to calculate the metrics of interest." }, "variablesRelevantToMetric": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Variables causally relevant to the metric." }, "segmentDefinitions": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDefinitionSchema" } }, { "type": "null" } ], "description": "Optional list of segment definitions" }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Specific environments for intervention. None = all environments" } }, "required": [ "type", "interventions", "metrics" ] }, "PanelOptimisationScenarioSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "panel_optimisation" }, "objectives": { "type": "array", "items": { "$ref": "#/components/schemas/TemporalOptimisationObjectiveSchema" } }, "decisionVars": { "type": "array", "items": { "type": "string" } }, "variableConstraints": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/VariableConstraintSchema" } }, { "type": "null" } ] }, "metricConstraints": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/MetricConstraintSchema" } }, { "type": "null" } ] }, "interventionTiming": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TemporalInterventionTimingSchema" } }, { "type": "null" } ] }, "forecastHorizon": { "type": [ "number", "null" ] }, "interventionCountConfig": { "anyOf": [ { "$ref": "#/components/schemas/InterventionCountConfigSchema" }, { "type": "null" } ] }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Specific environments for optimisation. None = all environments" } }, "required": [ "type", "objectives", "decisionVars" ] }, "PanelOptimizationResultSchema": { "type": "object", "properties": { "environmentResults": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TemporalOptimizationResultSchema" }, "description": "Optimization results per environment" } }, "required": [ "environmentResults" ] }, "PanelParentImpactRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "panel_parent_impact" }, "nodes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Nodes to analyze. None = all non-latent nodes with parents" }, "nSamples": { "type": "number", "default": 500, "description": "Samples per do() contrast (static twins only)" }, "horizonOverride": { "type": [ "number", "null" ], "description": "Attribution forecast window override (temporal twins only)" }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Specific environments for parent impact. None = all environments" } }, "required": [ "type" ] }, "PanelParentImpactResultSchema": { "type": "object", "properties": { "environmentResults": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ParentImpactResultSchema" }, "description": "Parent impact results per environment" } }, "required": [ "environmentResults" ] }, "PanelRootCauseAnalysisRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "panel_root_cause_analysis" }, "targetVariable": { "type": "string" }, "samples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ] }, "samplesRef": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" }, { "type": "null" } ] }, "anomalyTimestep": { "type": [ "number", "null" ] }, "targetFpr": { "type": "number", "minimum": 0.0001, "maximum": 0.1, "default": 0.005 }, "parentToleranceSigma": { "type": "number", "default": 0.5 }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "panelSamples": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, { "type": "null" } ] }, "panelSamplesRef": { "anyOf": [ { "$ref": "#/components/schemas/PanelScenarioSamplesRefSchema" }, { "type": "null" } ] } }, "required": [ "type", "targetVariable" ] }, "PanelRootCauseAnalysisResultSchema": { "type": "object", "properties": { "environmentResults": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/RootCauseAnalysisResultSchema" } } }, "required": [ "environmentResults" ] }, "PanelScenarioSamplesRefSchema": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" } }, "ParentImpactEntrySchema": { "type": "object", "properties": { "parent": { "type": "string" }, "impactPct": { "type": "number", "description": "Share of total driver influence on the node, 0-100" }, "signedEffect": { "type": "number" }, "lagBreakdown": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] } }, "required": [ "parent", "impactPct", "signedEffect" ] }, "ParentImpactRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "parent_impact" }, "nodes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Nodes to analyze. None = all non-latent nodes with parents" }, "nSamples": { "type": "number", "default": 500, "description": "Samples per do() contrast (static twins only)" }, "horizonOverride": { "type": [ "number", "null" ], "description": "Attribution forecast window override (temporal twins only)" } }, "required": [ "type" ] }, "ParentImpactResultSchema": { "type": "object", "properties": { "nodeImpacts": { "type": "array", "items": { "$ref": "#/components/schemas/NodeParentImpactsSchema" } }, "executionTime": { "type": "number" }, "sampleSize": { "type": [ "number", "null" ] } }, "required": [ "nodeImpacts", "executionTime" ] }, "ParetoDominantSolutionSchema": { "type": "object", "properties": { "interventions": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Interventions in this solution" }, "interventionCount": { "type": "number", "default": 0, "description": "Number of interventions in this solution" }, "objectiveValues": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Values of the objectives" }, "implementationDifficulty": { "type": [ "number", "null" ], "description": "Difficulty of implementing this solution" }, "expectedOutcomes": { "type": "object", "additionalProperties": {}, "description": "Expected outcomes of the solution" }, "uncertainty": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": {} }, "description": "Uncertainty in objective values" }, "improvementOverBaseline": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Improvements over baseline" }, "constraintsSatisfied": { "type": "boolean", "default": true, "description": "Whether all constraints were satisfied by this solution" }, "constraintViolations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Descriptions of constraint violations if any" }, "targetsAchieved": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "boolean" } }, { "type": "null" } ], "description": "Whether each objective's target was achieved" }, "segmentResults": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "number" } } }, { "type": "null" } ], "description": "Per-segment objective values: {segment_id: {objective_name: value}}" }, "segmentSampleSizes": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "Per-segment sample sizes: {segment_id: sample_count}" }, "segmentInterventions": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ], "description": "Segment-specific interventions with conditions" }, "totalSampleCount": { "type": [ "number", "null" ] }, "affectedSampleCount": { "type": [ "number", "null" ] }, "affectedPercentage": { "type": [ "number", "null" ] }, "appliedInterventions": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/InterventionSchema" } }, { "type": "null" } ], "description": "The exact intervention rows the evaluator ran for this plan, after scoping and relative-mode conversion" }, "interventionResult": { "anyOf": [ { "anyOf": [ { "$ref": "#/components/schemas/TimeSeriesInterventionResultSchema" }, { "$ref": "#/components/schemas/InterventionResultSchema" } ] }, { "type": "null" } ], "description": "The plan re-run as an intervention scenario; null on older runs, panel temporal runs, and when the plan's run failed" } }, "required": [ "interventions", "objectiveValues", "expectedOutcomes", "uncertainty", "improvementOverBaseline" ] }, "PatchFixedGraphInput": { "type": "object", "properties": { "addEdges": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" } }, "required": [ "source", "target" ] } }, "removeEdges": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" } }, "required": [ "source", "target" ] } } }, "required": [ "addEdges", "removeEdges" ] }, "PathwayEffectSchema": { "type": "object", "properties": { "pathway": { "type": "array", "items": { "type": "string" }, "description": "Variables in the causal pathway" }, "effectContribution": { "type": [ "number", "null" ], "description": "Contribution of this pathway to total effect" }, "percentageOfTotal": { "type": [ "number", "null" ], "description": "Percentage of total effect through this pathway" }, "note": { "type": [ "string", "null" ], "description": "Additional notes about the pathway" } }, "required": [ "pathway" ] }, "PredictionWithUncertaintyRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "prediction" }, "sample": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ], "description": "Samples to predict for" }, "sampleRef": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" }, { "type": "null" } ], "description": "Datalake reference replacing inline sample" }, "targetVars": { "type": "array", "items": { "type": "string" }, "description": "Target variables to predict" }, "confidenceLevel": { "type": [ "number", "null" ], "default": 0.95, "description": "Confidence level for intervals" } }, "required": [ "type", "targetVars" ] }, "PreviewQueryInput": { "type": "object", "properties": { "config": { "type": "object", "additionalProperties": {}, "description": "Connector-specific selection: {table} plus database/schema/warehouse for SQL connectors, {database, collection} for MongoDB, {path} for storage, or {query} to preview custom SQL instead; connectorId and type are filled in from the route" }, "limit": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000 }, { "type": "null" } ], "description": "Row cap for the preview (default 50, max 1000)" } }, "required": [ "config" ] }, "PublicConceptUpdateInput": { "type": "object", "properties": { "_id": { "type": "string" }, "ownerId": { "type": "string", "default": "system" }, "organisationId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "conceptClassification": { "anyOf": [ { "$ref": "#/components/schemas/ConceptClassificationEnum" }, { "type": "null" } ] }, "anchorConceptLinks": { "type": "array", "items": { "type": "string" }, "default": [] }, "schemaFieldName": { "type": "string" }, "schemaType": { "$ref": "#/components/schemas/SchemaMainTypeEnum" }, "schemaSubtype": { "anyOf": [ { "$ref": "#/components/schemas/SchemaSubTypeEnum" }, { "type": "null" } ] }, "metadata": { "$ref": "#/components/schemas/ConceptMetadataSchema" }, "lockedMetadataFields": { "type": "array", "items": { "type": "string" } }, "detectedMetadata": { "anyOf": [ { "$ref": "#/components/schemas/ConceptMetadataSchema" }, { "type": "null" } ] }, "derivedInfo": { "anyOf": [ { "$ref": "#/components/schemas/DerivedConceptInfoSchema" }, { "type": "null" } ] }, "conceptKind": { "$ref": "#/components/schemas/ConceptKindEnum", "default": "standard" }, "metricSql": { "type": [ "string", "null" ] }, "relationshipRules": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipRuleSchema" }, "default": [] }, "temporalPrerequisites": { "type": "array", "items": { "type": "string" }, "default": [] }, "suggestedRole": { "anyOf": [ { "$ref": "#/components/schemas/SuggestedRoleEnum" }, { "type": "null" } ] }, "trustTier": { "anyOf": [ { "type": "string", "enum": [ "exploratory", "curated_pending", "curated" ] }, { "type": "null" } ] }, "ontologyRef": { "anyOf": [ { "type": "object", "properties": { "ontologyId": { "type": "string" }, "ontologyVersion": { "type": "string" }, "canonicalId": { "type": "string" }, "installScope": { "anyOf": [ { "type": "object", "properties": { "conceptCanonicalIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "filters": { "type": "array", "items": { "type": "object", "properties": { "conceptRef": { "type": "string" }, "values": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ] } }, "required": [ "conceptRef" ] }, "default": [] } } }, { "type": "null" } ] } }, "required": [ "ontologyId", "ontologyVersion", "canonicalId" ] }, { "type": "null" } ] }, "layerIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "valueMappings": { "type": "array", "items": { "$ref": "#/components/schemas/ConceptValueMappingSchema" }, "default": [] }, "lockedConceptFields": { "type": "array", "items": { "type": "string" } }, "detectedConceptStructure": { "anyOf": [ { "$ref": "#/components/schemas/DetectedConceptStructureSchema" }, { "type": "null" } ] }, "lastEditedBy": { "type": [ "string", "null" ] }, "lastEditedAt": { "type": [ "string", "null" ] }, "lineageDrift": { "type": [ "boolean", "null" ] }, "editVersion": { "type": "integer", "minimum": 0, "default": 0 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "status": { "$ref": "#/components/schemas/BindingStatusEnum", "default": "confirmed" }, "source": { "$ref": "#/components/schemas/BindingSourceEnum", "default": "ingest" }, "confidence": { "type": [ "number", "null" ] }, "evidence": { "type": [ "string", "null" ] }, "valueMap": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "string" }, { "type": "string" } ] } }, { "allOf": [ {}, { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "string" }, { "type": "string" } ] } } ] } ] }, { "type": "null" } ] }, "canonicalField": { "type": [ "string", "null" ] }, "scopeFields": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "precedence": { "type": [ "number", "null" ] }, "keyRole": { "anyOf": [ { "$ref": "#/components/schemas/KeyRoleEnum" }, { "type": "null" } ] }, "conformance": { "anyOf": [ { "$ref": "#/components/schemas/ConformanceReportSchema" }, { "type": "null" } ] }, "decidedBy": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ] }, "sourceId": { "type": "string" } }, "required": [ "field", "sourceId" ] } } }, "required": [ "_id" ] }, "PublicFieldMappingSchema": { "type": "object", "properties": { "datasetId": { "type": "string" }, "field": { "type": "string" }, "status": { "$ref": "#/components/schemas/BindingStatusEnum", "default": "confirmed" }, "source": { "$ref": "#/components/schemas/BindingSourceEnum", "default": "ingest" }, "confidence": { "type": [ "number", "null" ] }, "evidence": { "type": [ "string", "null" ] }, "valueMap": { "anyOf": [ { "$ref": "#/components/schemas/OntologyValueMapSchema" }, { "type": "null" } ] }, "canonicalField": { "type": [ "string", "null" ] }, "scopeFields": { "type": [ "array", "null" ], "items": { "type": "string" } }, "precedence": { "type": [ "number", "null" ] }, "keyRole": { "anyOf": [ { "$ref": "#/components/schemas/KeyRoleEnum" }, { "type": "null" } ] }, "conformance": { "anyOf": [ { "$ref": "#/components/schemas/ConformanceReportSchema" }, { "type": "null" } ] }, "decidedBy": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ] }, "sourceId": { "type": "string" } }, "required": [ "datasetId", "field", "status", "source", "sourceId" ] }, "PutGraphInput": { "type": "object", "properties": { "relationships": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" }, "strength": { "type": "number" } }, "required": [ "source", "target" ] } }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "nodeType": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "nodeType", "type" ] } } }, "required": [ "relationships", "nodes" ] }, "RangeConstraintSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "range" }, "minValue": { "type": [ "number", "null" ], "description": "Minimum allowed value (inclusive)" }, "maxValue": { "type": [ "number", "null" ], "description": "Maximum allowed value (inclusive)" } }, "required": [ "type" ] }, "RangeValueSpecSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "range" }, "from": { "type": [ "number", "null" ], "description": "First value of the grid, in the variable's original domain. Omit to start at the low end of the observed range." }, "to": { "type": [ "number", "null" ], "description": "Last value of the grid, in the variable's original domain. Omit to end at the high end of the observed range." }, "steps": { "anyOf": [ { "type": "integer", "minimum": 2, "maximum": 50 }, { "type": "null" } ], "description": "Number of evenly spaced grid points, inclusive of both bounds (2-50). Omit to let the twin family pick — 20 for a static sweep, fewer for temporal families where one point is a whole forecast." } }, "required": [ "type" ] }, "ReconciliationColumnGroupSchema": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "fieldIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "label", "fieldIds" ] }, "ReconciliationColumnSideEnum": { "type": "string", "enum": [ "primary", "secondary", "system", "context" ] }, "ReconciliationSecondaryMetaSchema": { "type": "object", "properties": { "secondaryKey": { "type": "string" }, "secondaryName": { "type": "string" }, "presenceCol": { "type": [ "string", "null" ] }, "mismatchCol": { "type": [ "string", "null" ] }, "statusCol": { "type": [ "string", "null" ] } }, "required": [ "secondaryKey", "secondaryName" ] }, "RelationshipRuleSchema": { "type": "object", "properties": { "ruleType": { "$ref": "#/components/schemas/RelationshipRuleTypeEnum" }, "sourceVariable": { "type": "string" }, "condition": { "anyOf": [ { "$ref": "#/components/schemas/ConditionSchema" }, { "type": "null" } ] }, "allowedValues": { "anyOf": [ { "type": "array", "items": { "type": [ "string", "number", "boolean" ] } }, { "type": "null" } ] }, "minValue": { "type": [ "number", "null" ] }, "maxValue": { "type": [ "number", "null" ] }, "confidence": { "type": "number", "default": 1 }, "support": { "type": "number", "default": 0 }, "strength": { "anyOf": [ { "$ref": "#/components/schemas/RuleStrengthEnum" }, { "type": "null" } ] }, "violationRate": { "type": [ "number", "null" ] }, "source": { "type": [ "string", "null" ] }, "cycle": { "type": [ "string", "null" ] } }, "required": [ "ruleType", "sourceVariable" ] }, "RelationshipRuleTypeEnum": { "type": "string", "enum": [ "conditional_values", "range", "set", "cyclic_active_window", "cyclic_missing" ] }, "RelativeChangeSpecSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "relative_change" }, "mode": { "type": "string", "enum": [ "percentage", "absolute" ], "description": "Whether the change is a percentage or an absolute amount." }, "value": { "type": "number", "description": "The amount of change (e.g., 10 for +10%, -5 for -5 units)." } }, "required": [ "type", "mode", "value" ] }, "RenderWidgetInput": { "type": "object", "properties": { "widget": { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "additionalProperties": {}, "description": "A widget payload as emitted by agent/MCP tools (type plus kind-specific fields)" }, "theme": { "type": "string", "enum": [ "light", "dark" ], "description": "Render theme (default light)" } }, "required": [ "widget" ] }, "ReportEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Report" } }, "required": [ "data" ] }, "ReportListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Report" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Pass back as ?cursor= to fetch the next page" }, "hasMore": { "type": "boolean", "description": "Whether a further page exists" }, "total": { "type": "number", "description": "Total matching rows, when the query can count them" } }, "required": [ "hasMore" ] } }, "required": [ "data", "pagination" ] }, "reportPublishSchema": { "type": "object", "properties": { "slug": { "type": [ "string", "null" ] }, "publishedAt": { "type": [ "string", "null" ] }, "consumerAccess": { "anyOf": [ { "type": "string", "enum": [ "private", "workspace", "organisation", "public" ] }, { "type": "null" } ] }, "resolvedInputs": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "datasetId": { "type": "string" }, "versionId": { "type": [ "string", "null" ] }, "deltaVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "datasetId" ] } }, { "type": "null" } ] }, "widgetSnapshot": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ] }, "snapshotAt": { "type": [ "string", "null" ] }, "snapshotStats": { "anyOf": [ { "type": "object", "properties": { "requested": { "type": "number" }, "resolved": { "type": "number" }, "omitted": { "type": "number" }, "timedOut": { "type": "boolean" }, "bytes": { "type": "number" } }, "required": [ "requested", "resolved", "omitted", "timedOut", "bytes" ] }, { "type": "null" } ] } } }, "ReportStatusSchema": { "type": "string", "enum": [ "draft", "ready", "error" ] }, "ResolvedEnvironmentGroupEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ResolvedEnvironmentGroupSchema" } }, "required": [ "data" ] }, "ResolvedEnvironmentGroupSchema": { "type": "object", "properties": { "groupId": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "environmentColumns": { "type": "array", "items": { "type": "string" } }, "environments": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "envKeys": { "type": "array", "items": { "type": "string" } }, "sampleSize": { "type": "number" }, "totalEnvCount": { "type": "number" }, "unresolvedEnvCount": { "type": "number", "default": 0 }, "matchedBeforeEvidenceFilter": { "type": [ "number", "null" ] }, "unresolvable": { "anyOf": [ { "$ref": "#/components/schemas/GroupUnresolvableSchema" }, { "type": "null" } ] } }, "required": [ "environmentColumns", "environments", "envKeys", "sampleSize", "totalEnvCount" ] }, "ResolveEnvironmentGroupInput": { "type": "object", "properties": { "groupId": { "type": "string", "description": "Id of a saved environment group on this twin" }, "definition": { "$ref": "#/components/schemas/EnvironmentGroupDefinitionSchema", "description": "An ad-hoc membership rule to resolve without saving it" } } }, "ResolveEnvironmentsInput": { "type": "object", "properties": { "statFilters": { "type": "object", "additionalProperties": {}, "description": "A filter group: {booleanOperator: AND | OR, filters: [{column, comparisonOperator, value, reduce}]} — reduce is value (constant per environment), mean/min/max (numeric aggregate), or any (at least one matching row); groups nest" } }, "required": [ "statFilters" ] }, "RichDescriptionSchema": { "type": "object", "properties": { "markdown": { "type": "string" }, "widgets": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "chart" }, "explorerConfig": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "dataView": { "anyOf": [ { "$ref": "#/components/schemas/DataViewSchema" }, { "type": "null" } ] }, "operations": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/OperationSchema" } }, { "type": "null" } ] }, "additionalSources": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SourceSchema" } }, { "type": "null" } ] }, "inlineData": { "anyOf": [ { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "None", "String", "Category", "Number", "Boolean", "DateTime", "Array", "Unknown" ] } }, "required": [ "name", "type" ] }, "minItems": 1 }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } }, "default": [] }, "downsampled": { "type": "boolean" }, "totalRows": { "type": [ "number", "null" ] } }, "required": [ "columns" ] }, { "type": "null" } ] }, "series": { "anyOf": [ { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": [ "string", "number" ] }, "default": [] }, "datasets": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "default": [] }, "meta": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "number", "default": 1 }, "xField": { "type": [ "string", "null" ] }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ] }, "default": [] }, "series": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "yField": { "type": [ "string", "null" ] }, "aggregation": { "type": [ "string", "null" ] } }, "required": [ "label" ] }, "default": [] }, "categoriesTotal": { "type": [ "number", "null" ] }, "categoriesShown": { "type": [ "number", "null" ] }, "otherFolded": { "type": [ "boolean", "null" ] }, "sortBy": { "type": [ "string", "null" ] }, "sortType": { "type": [ "string", "null" ] }, "binCount": { "type": [ "number", "null" ] }, "linksTotal": { "type": [ "number", "null" ] }, "linksShown": { "type": [ "number", "null" ] }, "pointsTotal": { "type": [ "number", "null" ] }, "pointsShown": { "type": [ "number", "null" ] }, "rowsScanned": { "type": [ "number", "null" ] }, "rowsWithoutCategory": { "type": [ "number", "null" ] }, "rowsExcluded": { "type": [ "number", "null" ] }, "rowsExcludedBy": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "column": { "type": [ "string", "null" ] }, "rows": { "type": "number" } }, "required": [ "reason", "rows" ] } }, { "type": "null" } ] }, "downsampled": { "type": [ "boolean", "null" ] }, "summary": { "type": "string", "default": "" } }, "additionalProperties": true }, { "type": "null" } ] } } }, { "type": "null" } ] }, "xSelection": { "type": "string" }, "traces": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "default": [] }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "bar" }, "options": { "anyOf": [ { "type": "object", "properties": { "stacked": { "type": "boolean", "default": false }, "aggregation": { "type": "string", "enum": [ "average", "sum", "count", "min", "max" ], "default": "sum" } } }, { "type": "null" } ] } }, "required": [ "id", "name", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "line" }, "options": { "anyOf": [ { "type": "object", "properties": { "aggregation": { "anyOf": [ { "type": "string", "enum": [ "average", "sum", "count", "min", "max" ], "default": "sum" }, { "type": "null" } ] }, "tension": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.4 }, "showPoints": { "type": "boolean", "default": true } } }, { "type": "null" } ] } }, "required": [ "id", "name", "ySelection", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "scatter" }, "options": { "anyOf": [ { "type": "object", "properties": { "showLine": { "type": "boolean", "default": false }, "pointRadius": { "type": "number", "minimum": 1, "maximum": 20, "default": 3 } } }, { "type": "null" } ] } }, "required": [ "id", "name", "ySelection", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "area" }, "options": { "anyOf": [ { "type": "object", "properties": { "aggregation": { "anyOf": [ { "type": "string", "enum": [ "average", "sum", "count", "min", "max" ], "default": "sum" }, { "type": "null" } ] }, "tension": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.4 }, "fillOpacity": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.3 } } }, { "type": "null" } ] } }, "required": [ "id", "name", "ySelection", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "default": [] }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "histogram" }, "options": { "anyOf": [ { "type": "object", "properties": { "bins": { "type": "number", "minimum": 5, "maximum": 100, "default": 20 } } }, { "type": "null" } ] } }, "required": [ "id", "name", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "default": [] }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "pie" }, "options": { "anyOf": [ { "type": "object", "properties": { "aggregation": { "default": "sum", "type": "string", "enum": [ "average", "sum", "count", "min", "max" ] } } }, { "type": "null" } ] } }, "required": [ "id", "name", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "default": [] }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "doughnut" }, "options": { "anyOf": [ { "type": "object", "properties": { "aggregation": { "default": "sum", "type": "string", "enum": [ "average", "sum", "count", "min", "max" ] } } }, { "type": "null" } ] } }, "required": [ "id", "name", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "sankey" } }, "required": [ "id", "name", "ySelection", "chartType" ] } ], "discriminator": { "propertyName": "chartType" } } }, "config": { "type": "object", "properties": { "responsive": { "type": "boolean", "default": true }, "chartTitle": { "type": [ "string", "null" ] }, "dataPoints": { "type": "number", "default": -1 }, "dataDisplayOrder": { "type": "string", "enum": [ "fromStart", "fromEnd" ], "default": "fromStart" }, "sortBy": { "anyOf": [ { "type": "string", "enum": [ "none", "x", "y" ] }, { "type": "null" } ] }, "sortType": { "anyOf": [ { "type": "string", "enum": [ "ascending", "descending", "natural" ] }, { "type": "null" } ] }, "advancedSettings": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] } } } }, "required": [ "id", "xSelection", "traces", "config" ] }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "table" }, "title": { "type": [ "string", "null" ] }, "columns": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "totalRows": { "type": "number" }, "csvExport": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "sql_evidence" }, "rowCount": { "type": "integer", "minimum": 0 }, "queryTruncated": { "type": "boolean" }, "queryTotalRowCount": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "source", "rowCount", "queryTruncated" ] }, { "type": "null" } ] }, "livePaging": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "anchor_sql" }, "sql": { "type": "string" }, "projectionMode": { "type": "string", "enum": [ "related", "minimal" ], "default": "related" } }, "required": [ "source", "sql" ] }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "columns", "rows", "totalRows" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "data_preview" }, "datasetId": { "type": "string" } }, "required": [ "id", "evidenceId", "type", "datasetId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "data_view_preview" }, "dataViewId": { "type": "string" } }, "required": [ "id", "evidenceId", "type", "dataViewId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "kpi_card" }, "title": { "type": "string" }, "value": { "type": [ "string", "number" ] }, "dataBinding": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "sourceType": { "type": "string", "const": "dataset" }, "datasetId": { "type": "string", "minLength": 1 }, "valueField": { "type": "string", "minLength": 1 } }, "required": [ "sourceType", "datasetId", "valueField" ] }, { "type": "object", "properties": { "sourceType": { "type": "string", "const": "dataview" }, "dataViewId": { "type": "string", "minLength": 1 }, "valueField": { "type": "string", "minLength": 1 } }, "required": [ "sourceType", "dataViewId", "valueField" ] } ], "discriminator": { "propertyName": "sourceType" } }, { "type": "null" } ] }, "unit": { "type": [ "string", "null" ] }, "unitId": { "type": [ "string", "null" ] }, "change": { "type": [ "number", "null" ] }, "changePeriod": { "type": [ "string", "null" ] }, "trend": { "anyOf": [ { "type": "string", "enum": [ "up", "down", "neutral" ] }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "title", "value" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "causal_graph" }, "digitalTwinVersionId": { "type": "string" } }, "required": [ "id", "evidenceId", "type", "digitalTwinVersionId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "dataset_search_results" }, "searchQuery": { "type": "string" }, "datasetIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "evidenceId", "type", "searchQuery", "datasetIds" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "data_view_search_results" }, "searchQuery": { "type": "string" }, "dataViewIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "evidenceId", "type", "searchQuery", "dataViewIds" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "digital_twin_result" }, "digitalTwinRunId": { "type": "string" } }, "required": [ "id", "evidenceId", "type", "digitalTwinRunId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "digital_twin_search_results" }, "digitalTwinVersionIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "evidenceId", "type", "digitalTwinVersionIds" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "digital_twin_run_search_results" }, "searchQuery": { "type": "string" }, "runIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "evidenceId", "type", "searchQuery", "runIds" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "ontology_graph" }, "searchQuery": { "type": "string" }, "conceptIds": { "type": "array", "items": { "type": "string" } }, "anchorType": { "type": "string", "enum": [ "dataset", "identifier", "conceptType" ], "default": "dataset" }, "showFullGraph": { "type": "boolean", "default": false } }, "required": [ "id", "evidenceId", "type", "searchQuery", "conceptIds" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "path_analysis_sankey" }, "digitalTwinVersionId": { "type": "string" }, "selectedNode": { "type": [ "string", "null" ] }, "selectedEdge": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" } }, "required": [ "source", "target" ] }, { "type": "null" } ] }, "depthLimit": { "type": "number", "default": 2 } }, "required": [ "id", "evidenceId", "type", "digitalTwinVersionId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "parameter_distribution" }, "digitalTwinVersionId": { "type": "string" }, "selectedNode": { "type": [ "string", "null" ] }, "selectedEdge": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" } }, "required": [ "source", "target" ] }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "digitalTwinVersionId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "causal_diff" }, "version1Id": { "type": "string" }, "version2Id": { "type": "string" } }, "required": [ "id", "evidenceId", "type", "version1Id", "version2Id" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "dose_response" }, "causeVariable": { "type": "string" }, "sweptMode": { "anyOf": [ { "type": "string", "enum": [ "absolute", "percentage" ] }, { "type": "null" } ] }, "metric": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "properties": { "causeValue": { "type": "number" }, "effect": { "type": "number" }, "ciLower": { "type": [ "number", "null" ] }, "ciUpper": { "type": [ "number", "null" ] } }, "required": [ "causeValue", "effect" ] } }, "referenceValue": { "type": [ "number", "null" ] }, "isLinear": { "type": [ "boolean", "null" ] }, "inflectionPoints": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ] }, "digitalTwinRunId": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type", "causeVariable", "metric", "points" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "page_context" }, "section": { "anyOf": [ { "type": "string", "enum": [ "Organisation Home", "Workspace Home", "Dataset Selection", "Dataset Page", "Data View Selection", "Data View Page", "Digital Twin Selection", "Digital Twin Page", "Report Selection", "Report Page", "Settings" ] }, { "type": "null" } ] }, "summary": { "type": "string" }, "entityName": { "type": [ "string", "null" ] }, "entityType": { "anyOf": [ { "type": "string", "enum": [ "dataset", "data_view", "digital_twin", "report" ] }, { "type": "null" } ] }, "itemCount": { "type": [ "number", "null" ] } }, "required": [ "id", "evidenceId", "type", "summary" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "dag_review" }, "digitalTwinVersionId": { "type": "string" }, "digitalTwinName": { "type": "string" }, "nodeCount": { "type": "number" }, "edgeCount": { "type": "number" }, "overallHealth": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "severity": { "type": "string", "enum": [ "high", "medium", "low" ] }, "suggestedFix": { "type": [ "string", "null" ] }, "affectedNodes": { "type": "array", "items": { "type": "string" }, "default": [] }, "affectedEdges": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" } }, "required": [ "source", "target" ] }, "default": [] } }, "required": [ "type", "description", "severity" ] }, "default": [] }, "recommendations": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "id", "evidenceId", "type", "digitalTwinVersionId", "digitalTwinName", "nodeCount", "edgeCount", "overallHealth" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "causal_context" }, "outcomeVariable": { "type": "string" }, "relatedConcepts": { "type": "array", "items": { "type": "object", "properties": { "concept": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "sourceName": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] }, "isIdentifier": { "type": "boolean", "default": false } }, "required": [ "concept" ] }, "default": [] }, "datasetSourceCount": { "type": "number", "default": 0 }, "recommendation": { "type": [ "string", "null" ] }, "existingDataViewId": { "type": [ "string", "null" ] }, "existingDataViewName": { "type": [ "string", "null" ] }, "existingDigitalTwinId": { "type": [ "string", "null" ] }, "existingDigitalTwinName": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type", "outcomeVariable" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "graph_query_result" }, "queryType": { "type": "string" }, "digitalTwinVersionId": { "type": "string" }, "queriedNode": { "type": [ "string", "null" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "node": { "type": "string" }, "edgeLabel": { "type": [ "string", "null" ] }, "strength": { "type": [ "number", "null" ] }, "depth": { "type": [ "number", "null" ] }, "type": { "type": [ "string", "null" ] } }, "required": [ "node" ] }, "default": [] }, "path": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "queryType", "digitalTwinVersionId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "ontology_data" }, "columns": { "type": "array", "items": { "type": "string" }, "default": [] }, "rowCount": { "type": "number", "default": 0 }, "sampleRows": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "default": [] }, "dataViewId": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "ontology_mutation_preview" }, "operations": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "default": [] }, "successCount": { "type": "number", "default": 0 }, "failureCount": { "type": "number", "default": 0 }, "affectedConceptIds": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "docs_sources" }, "documentReferences": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "path": { "type": "string" }, "pageId": { "type": [ "string", "null" ] } }, "required": [ "title", "path" ] } } }, "required": [ "id", "evidenceId", "type", "documentReferences" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "background_runs" }, "runs": { "type": "array", "items": { "type": "object", "properties": { "runId": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "entityId": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "percentage": { "type": [ "number", "null" ] }, "label": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "runId", "name", "domain", "status" ] } } }, "required": [ "id", "evidenceId", "type", "runs" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "environment_segments" }, "title": { "type": "string" }, "silhouetteScore": { "type": [ "number", "null" ] }, "segments": { "type": "array", "items": { "type": "object", "properties": { "segment": { "type": "number" }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "environments": { "type": "array", "items": { "type": "string" } } }, "required": [ "segment", "label", "environments" ] } }, "points": { "type": "array", "items": { "type": "object", "properties": { "envKey": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "segment": { "type": "number" } }, "required": [ "envKey", "x", "y", "segment" ] } } }, "required": [ "id", "evidenceId", "type", "title", "segments", "points" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "environment_comparison" }, "title": { "type": "string" }, "sliceLabel": { "type": "string" }, "baselineLabel": { "type": "string" }, "sliceEnvCount": { "type": "number" }, "baselineEnvCount": { "type": "number" }, "edges": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" }, "sliceAgreement": { "type": "number" }, "baselineAgreement": { "type": "number" }, "sliceStrength": { "type": [ "number", "null" ] }, "baselineStrength": { "type": [ "number", "null" ] }, "verdict": { "type": "string", "enum": [ "slice-only", "missing-from-slice", "differs", "consistent" ] } }, "required": [ "source", "target", "sliceAgreement", "baselineAgreement", "verdict" ] } } }, "required": [ "id", "evidenceId", "type", "title", "sliceLabel", "baselineLabel", "sliceEnvCount", "baselineEnvCount", "edges" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "environment_coverage" }, "title": { "type": "string" }, "environments": { "type": "array", "items": { "type": "object", "properties": { "envKey": { "type": "string" }, "trainingRows": { "type": [ "number", "null" ] }, "variablesTrained": { "type": [ "number", "null" ] }, "variablesTotal": { "type": [ "number", "null" ] }, "missing": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "name" ] } }, "evaluation": { "type": [ "string", "null" ] } }, "required": [ "envKey", "missing" ] } } }, "required": [ "id", "evidenceId", "type", "title", "environments" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "clarification" }, "toolCallId": { "type": "string" }, "mode": { "type": "string", "enum": [ "multiple_choice", "form" ] }, "question": { "type": "string" }, "why": { "type": [ "string", "null" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" }, "preview": { "type": [ "string", "null" ] } }, "required": [ "label", "value" ] }, "default": [] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "string", "select", "multiselect", "boolean", "source", "dataset", "digitalTwin", "ontologyConcept" ], "default": "string" }, "default": { "anyOf": [ {}, { "type": "null" } ] }, "options": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value" ] } ] } }, { "type": "null" } ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "pattern": { "type": [ "string", "null" ] }, "control": { "type": [ "string", "null" ] }, "placeholder": { "type": [ "string", "null" ] }, "help": { "type": [ "string", "null" ] }, "required": { "type": [ "boolean", "null" ] }, "secret": { "type": [ "boolean", "null" ] }, "urlParam": { "type": [ "string", "null" ] } }, "required": [ "id" ] }, "default": [] }, "selectedValues": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "selectedFieldValues": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "toolCallId", "mode", "question" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "action_confirmation" }, "toolCallId": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "severity": { "type": "string", "enum": [ "mutates_truth", "long_running", "irreversible" ] }, "actionLabel": { "type": "string" }, "estimatedDuration": { "type": [ "string", "null" ] }, "changes": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "before": { "type": [ "string", "null" ] }, "after": { "type": [ "string", "null" ] } }, "required": [ "label" ] } }, { "type": "null" } ] }, "details": { "type": [ "string", "null" ] }, "editableKind": { "anyOf": [ { "type": "string", "enum": [ "extraction_schema" ] }, { "type": "null" } ] }, "editableInputs": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "toolName": { "type": [ "string", "null" ] }, "toolInputs": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "toolCallId", "title", "summary", "severity", "actionLabel" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "navigation" }, "commandId": { "type": "string" }, "label": { "type": "string" }, "subtitle": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "navigate", "create", "action" ], "default": "navigate" }, "entity": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dataset", "dataview", "concept", "digitalTwin", "report", "digitalTwinRun" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "type", "id", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "commandId", "label" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "foundational_ontology_install" }, "ontologyId": { "type": "string" }, "version": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "trustTier": { "type": "string" }, "anchorsSummary": { "type": [ "string", "null" ] }, "conceptCount": { "type": "number" }, "sourceCount": { "type": "number" }, "suggestedScopeNote": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type", "ontologyId", "version", "name", "trustTier", "conceptCount", "sourceCount" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "stat_grid" }, "title": { "type": [ "string", "null" ] }, "stats": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "value": { "type": [ "string", "number" ] }, "unit": { "type": [ "string", "null" ] }, "unitId": { "type": [ "string", "null" ] }, "decimals": { "type": [ "number", "null" ] }, "change": { "type": [ "number", "null" ] }, "changePeriod": { "type": [ "string", "null" ] }, "trend": { "anyOf": [ { "type": "string", "enum": [ "up", "down", "neutral" ] }, { "type": "null" } ] } }, "required": [ "title", "value" ] } }, "gridCols": { "anyOf": [ { "type": "number", "enum": [ 2, 3, 4 ] }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "stats" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "markdown" }, "content": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "heading" }, "text": { "type": [ "string", "null" ] }, "eyebrow": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "divider" }, "style": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "image" }, "src": { "type": [ "string", "null" ] }, "alt": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "iframe" }, "url": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "application" }, "applicationId": { "type": "string" }, "runId": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "moduleCount": { "type": [ "number", "null" ] }, "publicUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type", "applicationId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "report" }, "reportId": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "rev": { "type": [ "number", "null" ] } }, "required": [ "id", "evidenceId", "type", "reportId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "lineage" }, "lineageId": { "type": "string" }, "tool": { "type": "string", "default": "" }, "hops": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string", "default": "" } }, "required": [ "kind", "id" ] }, "status": { "type": "string", "enum": [ "resolved", "denied", "deleted" ] }, "parents": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string", "default": "" } }, "required": [ "kind", "id" ] }, "default": [] }, "pin": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "versionId": { "type": [ "string", "null" ] }, "ordinal": { "type": [ "number", "null" ] }, "deltaVersion": { "type": [ "number", "null" ] }, "label": { "type": [ "string", "null" ] } }, "required": [ "kind", "id" ] }, { "type": "null" } ] }, "detail": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "ref", "status" ] }, "default": [] }, "reading": { "anyOf": [ { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "valueType": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "display": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "request": { "anyOf": [ { "type": "object", "properties": { "sql": { "type": [ "string", "null" ] }, "query": { "type": [ "string", "null" ] } } }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "lineageId" ] } ], "discriminator": { "propertyName": "type" } } } }, "required": [ "markdown", "widgets" ] }, "RootCauseAnalysisRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "root_cause_analysis" }, "targetVariable": { "type": "string" }, "samples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ] }, "samplesRef": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" }, { "type": "null" } ] }, "targetFpr": { "type": "number", "minimum": 0.0001, "maximum": 0.1, "default": 0.005 }, "parentToleranceSigma": { "type": "number", "default": 0.5 } }, "required": [ "type", "targetVariable" ] }, "RootCauseAnalysisResultSchema": { "type": "object", "properties": { "sampleResults": { "type": "array", "items": { "$ref": "#/components/schemas/SampleRcaResultSchema" } }, "calibratedThresholds": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] }, "targetFpr": { "type": [ "number", "null" ] }, "executionTime": { "type": "number", "default": 0 } }, "required": [ "sampleResults" ] }, "RuleStrengthEnum": { "type": "string", "enum": [ "hard", "soft" ] }, "SampleAnomalyScanResultSchema": { "type": "object", "properties": { "sampleIndex": { "type": "number" }, "isAnomalous": { "type": "boolean" }, "systemScore": { "type": "number" }, "flaggedNodes": { "type": "array", "items": { "$ref": "#/components/schemas/AnomalyFlagResultSchema" }, "default": [] }, "allSurprises": { "type": "array", "items": { "$ref": "#/components/schemas/NodeSurpriseResultSchema" }, "default": [] }, "autoRca": { "anyOf": [ { "$ref": "#/components/schemas/SampleRcaResultSchema" }, { "type": "null" } ] } }, "required": [ "sampleIndex", "isAnomalous", "systemScore" ] }, "SampleRcaResultSchema": { "type": "object", "properties": { "sampleIndex": { "type": "number", "default": 0 }, "targetVariable": { "type": "string" }, "observedTarget": { "type": "number" }, "expectedTargetMean": { "type": "number" }, "expectedTargetStd": { "type": "number" }, "targetZScore": { "type": "number" }, "rankedCauses": { "type": "array", "items": { "$ref": "#/components/schemas/NodeSurpriseResultSchema" } }, "rootCauses": { "type": "array", "items": { "$ref": "#/components/schemas/NodeSurpriseResultSchema" } }, "propagationChain": { "type": "array", "items": { "$ref": "#/components/schemas/NodeSurpriseResultSchema" } }, "causalPaths": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "observableAttribution": { "type": "number" }, "latentAttribution": { "type": "number" } }, "required": [ "targetVariable", "observedTarget", "expectedTargetMean", "expectedTargetStd", "targetZScore", "rankedCauses", "rootCauses", "propagationChain", "causalPaths", "observableAttribution", "latentAttribution" ] }, "SampleTwinInput": { "type": "object", "properties": { "spec": { "type": "object", "additionalProperties": {}, "description": "Sampling spec, discriminated by type: intervention (static/temporal twins), time_series_intervention, or panel_intervention (multi-environment twins, optional environments list). Carries interventions with valueSpec (setValue, relativeChange, setProbability, …) and optional per-intervention conditions. Deep validation happens server-side." }, "n": { "type": "integer", "minimum": 1, "maximum": 100000, "description": "Number of joint posterior draws (default 1000)" }, "seed": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Reproducibility seed. Panel twins derive a stable per-environment child seed from it." } }, "required": [ "spec" ] }, "ScenarioFromQueryInput": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1 }, "scenarioType": { "type": [ "string", "null" ] } }, "required": [ "query" ] }, "ScenarioSamplesRefSchema": { "type": "object", "properties": { "key": { "type": "string", "description": "Datalake object key holding the JSON-encoded samples array" }, "format": { "type": "string", "enum": [ "json" ], "default": "json" }, "rowCount": { "type": "integer", "minimum": 0, "description": "Number of rows in the referenced blob" } }, "required": [ "key", "rowCount" ] }, "ScenarioTypeEnum": { "type": "string", "enum": [ "optimisation", "intervention", "temporal_intervention", "prediction", "counterfactual", "explanation", "parent_impact", "forecast", "temporal_explanation", "temporal_counterfactual", "temporal_optimisation", "panel_forecast", "panel_intervention", "panel_explanation", "panel_counterfactual", "panel_optimisation", "panel_parent_impact", "root_cause_analysis", "temporal_root_cause_analysis", "panel_root_cause_analysis", "static_panel_root_cause_analysis", "anomaly_detection", "temporal_anomaly_detection", "panel_anomaly_detection", "static_panel_anomaly_detection", "causal_health_monitor", "panel_causal_health_monitor" ] }, "SchemaEntryModelSchema": { "type": "object", "properties": { "field": { "type": "string" }, "type": { "$ref": "#/components/schemas/SchemaMainTypeEnum" }, "subtype": { "anyOf": [ { "$ref": "#/components/schemas/SchemaSubTypeEnum" }, { "type": "null" } ] }, "availableTypes": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SchemaMainTypeEnum" } }, { "type": "null" } ] }, "isIndex": { "type": [ "boolean", "null" ] }, "categories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "aliases": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "description": { "type": [ "string", "null" ] }, "displayWidth": { "type": [ "number", "null" ] }, "originalFormat": { "type": [ "string", "null" ] }, "displayFormat": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "unitModifier": { "type": [ "number", "null" ] }, "dateOrderAssumed": { "type": [ "boolean", "null" ] } }, "required": [ "field", "type" ] }, "SchemaMainTypeEnum": { "type": "string", "enum": [ "None", "String", "Category", "Number", "Boolean", "DateTime", "Array", "Unknown" ] }, "SchemaSubTypeEnum": { "type": "string", "enum": [ "Integer", "Float", "UnsignedInteger", "UnsignedFloat", "String", "Number", "Category", "Boolean", "DateTime" ] }, "ScoreRowsInput": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "minItems": 1, "maxItems": 500, "description": "Rows to score; keys name twin variables (non-variable columns become row labels)" }, "targets": { "type": "array", "items": { "type": "object", "properties": { "variable": { "type": "string" }, "value": {}, "matchMode": { "type": "string" } }, "required": [ "variable" ], "additionalProperties": {} }, "minItems": 1, "description": "Outcomes each row should reach: [{variable, value, matchMode?}]" }, "maxChanges": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Most changes a counterfactual may make per row (default 3)" }, "constraints": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Per-variable constraints: {variable: {locked?, min?, max?, allowedValues?}}" }, "webhookUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Optional URL called once when the run completes" } }, "required": [ "rows", "targets" ] }, "SeasonalEffectDecompositionSchema": { "type": "object", "properties": { "component": { "type": "string" }, "period": { "type": "number" }, "periodEffects": { "type": "object", "additionalProperties": { "type": "number" } }, "strongestPeriod": { "type": "string" }, "weakestPeriod": { "type": "string" } }, "required": [ "component", "period", "periodEffects", "strongestPeriod", "weakestPeriod" ] }, "SeasonalPeriodSchema": { "type": "object", "properties": { "periodSeconds": { "type": "number" }, "cycleLabel": { "type": [ "string", "null" ] }, "strength": { "type": "number" }, "confidence": { "type": "number" }, "amplitude": { "type": [ "number", "null" ] }, "phase": { "type": [ "number", "null" ] }, "order": { "type": "number", "default": 1 } }, "required": [ "periodSeconds", "strength", "confidence" ] }, "SeasonalTermSchema": { "type": "object", "properties": { "period": { "type": "number" }, "order": { "type": "number", "default": 1 } }, "required": [ "period" ] }, "SegmentDefinitionSchema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the segment (e.g., 'high_spenders')" }, "description": { "type": [ "string", "null" ], "description": "User-friendly description of the segment" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ConditionSchema" }, "description": "List of conditions (ANDed together) defining the segment membership." } }, "required": [ "id", "conditions" ] }, "SegmentEffectSchema": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the segment definition used" }, "description": { "type": "string", "description": "Description of the segment" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ConditionSchema" }, "description": "Conditions defining the segment" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricResultSchema" }, "description": "Calculated metrics for this segment (e.g., baseline, intervention, effect). NaN if calculation failed." }, "baselineSampleSize": { "type": "number", "description": "Number of samples in the baseline segment" }, "interventionSampleSize": { "type": "number", "description": "Number of samples in the intervention segment" }, "mediatorShifts": { "$ref": "#/components/schemas/MediatorShiftsSchema", "description": "Per-metric mediator shifts: {metricName: {mediators: [...], paths: {...}}}" } }, "required": [ "id", "conditions", "metrics", "baselineSampleSize", "interventionSampleSize" ] }, "SegmentExplanationEffectSchema": { "type": "object", "properties": { "segmentId": { "type": "string", "description": "Unique identifier for the segment" }, "segmentDescription": { "type": "string", "description": "Human-readable segment description" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ConditionSchema" }, "description": "Conditions defining the segment" }, "effectSize": { "type": "number", "description": "Causal effect size in this segment" }, "confidenceInterval": { "type": "array", "items": { "type": "number" }, "description": "Confidence interval for the effect" }, "sampleSize": { "type": "number", "description": "Number of samples in this segment" }, "contrast": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "numeric", "categorical" ] }, "causeRef": { "anyOf": [ { "type": [ "string", "number" ] }, { "type": "null" } ] }, "causeTarget": { "anyOf": [ { "type": [ "string", "number" ] }, { "type": "null" } ] }, "contrastType": { "type": "string" } }, "required": [ "type", "contrastType" ], "description": "Contrast specification for this segment" }, "nReplicates": { "type": [ "number", "null" ], "description": "Number of replicates" }, "targetEffects": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TargetEffectSchema" } }, { "type": "null" } ], "description": "Target-specific effects" } }, "required": [ "segmentId", "segmentDescription", "conditions", "effectSize", "confidenceInterval", "sampleSize", "contrast" ] }, "SetConstraintSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "set" }, "allowedValues": { "type": "array", "items": { "type": [ "string", "number", "boolean" ] }, "description": "List of explicitly allowed values." } }, "required": [ "type", "allowedValues" ] }, "SetMembersSpecSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "set_members" }, "include": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Members to include in the set" }, "exclude": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Members to exclude from the set" }, "size": { "type": [ "number", "null" ], "description": "Fix the set size" }, "replace": { "type": "boolean", "description": "If true, zero out all members not in include" } }, "required": [ "type" ] }, "SetProbabilitySpecSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "set_probability" }, "category": { "type": [ "string", "number", "boolean" ], "description": "The target category value (in its original domain) whose probability will be set." }, "probability": { "type": "number", "minimum": 0, "maximum": 1, "description": "The desired probability for the specified category (0.0 to 1.0). Other probabilities will be renormalized." } }, "required": [ "type", "category", "probability" ] }, "SetValueSpecSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "set_value" }, "value": { "type": [ "number", "string", "boolean" ], "description": "The specific value to set the variable to (in its original domain)." } }, "required": [ "type", "value" ] }, "SimulateInput": { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceSchema" } }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/OperationSchema" } } }, "required": [ "sources", "operations" ] }, "SimulationEnvelope": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "organisationId": { "type": "string", "description": "The organisation id" }, "workspaceId": { "type": "string", "description": "The workspace id" }, "digitalTwinId": { "type": "string", "description": "The digital twin id" }, "digitalTwinVersionIds": { "type": "array", "items": { "type": "string" }, "description": "The digital twin version ids that were used to run the simulation" }, "userQuery": { "type": [ "string", "null" ], "description": "The user query that triggered the run" }, "timeStarted": { "type": "string", "description": "The time the run started" }, "timeCompleted": { "type": [ "string", "null" ], "description": "The time the run completed" }, "status": { "type": "string", "enum": [ "pending", "configuring", "configured", "running", "completed", "failed", "cancelled" ], "description": "The status of the run" }, "error": { "type": [ "string", "null" ], "description": "The failure reason when the run failed" }, "progress": { "anyOf": [ { "$ref": "#/components/schemas/SimulationProgressSchema" }, { "type": "null" } ], "description": "The progress of the run" }, "scenario": { "anyOf": [ { "$ref": "#/components/schemas/DigitalTwinScenarioSchema" }, { "type": "null" } ], "description": "The scenario to run" }, "outputs": { "anyOf": [ { "type": "object", "additionalProperties": { "anyOf": [ { "$ref": "#/components/schemas/DigitalTwinPredictionResultSchema" }, { "$ref": "#/components/schemas/OptimizationResultSchema" }, { "$ref": "#/components/schemas/InterventionResultSchema" }, { "$ref": "#/components/schemas/TimeSeriesInterventionResultSchema" }, { "$ref": "#/components/schemas/MultiCounterfactualExplanationSchema" }, { "$ref": "#/components/schemas/ExplanationResultSchema" }, { "$ref": "#/components/schemas/ParentImpactResultSchema" }, { "$ref": "#/components/schemas/TemporalExplanationResultSchema" }, { "$ref": "#/components/schemas/TemporalCounterfactualExplanationSchema" }, { "$ref": "#/components/schemas/TemporalOptimizationResultSchema" }, { "$ref": "#/components/schemas/PanelForecastResultSchema" }, { "$ref": "#/components/schemas/PanelInterventionResultSchema" }, { "$ref": "#/components/schemas/PanelExplanationResultSchema" }, { "$ref": "#/components/schemas/PanelCounterfactualResultSchema" }, { "$ref": "#/components/schemas/PanelOptimizationResultSchema" }, { "$ref": "#/components/schemas/PanelParentImpactResultSchema" }, { "$ref": "#/components/schemas/RootCauseAnalysisResultSchema" }, { "$ref": "#/components/schemas/PanelRootCauseAnalysisResultSchema" }, { "$ref": "#/components/schemas/StaticPanelRootCauseAnalysisResultSchema" }, { "$ref": "#/components/schemas/AnomalyDetectionResultSchema" }, { "$ref": "#/components/schemas/TemporalAnomalyDetectionResultSchema" }, { "$ref": "#/components/schemas/PanelAnomalyDetectionResultSchema" }, { "$ref": "#/components/schemas/StaticPanelAnomalyDetectionResultSchema" }, { "$ref": "#/components/schemas/CausalHealthMonitorResultSchema" }, { "$ref": "#/components/schemas/PanelCausalHealthMonitorResultSchema" } ] } }, { "type": "null" } ], "description": "The output of the run" }, "outputsStorageType": { "anyOf": [ { "type": "string", "enum": [ "inline", "data_lake" ] }, { "type": "null" } ], "description": "Where outputs are stored" }, "resultsSummary": { "anyOf": [ { "type": "object", "properties": { "summary": { "type": "string" }, "keyPoints": { "type": "array", "items": { "type": "string" } } }, "required": [ "summary", "keyPoints" ] }, { "type": "null" } ], "description": "AI generated summary of the run results" }, "environmentGroupSnapshots": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/EnvironmentGroupSnapshotSchema" } }, { "type": "null" } ], "description": "Resolved membership of each scoped environment group, frozen at submit" }, "executedByUserId": { "type": [ "string", "null" ], "description": "The user who triggered the run" }, "applicationExecutionId": { "type": [ "string", "null" ], "description": "Set when an application execution triggered the run" }, "exportFormats": { "type": "array", "items": { "type": "string", "enum": [ "json", "csv" ] }, "description": "Formats /results accepts; empty until the run completes" } }, "required": [ "id", "organisationId", "workspaceId", "digitalTwinId", "digitalTwinVersionIds", "timeStarted", "status", "exportFormats" ] } }, "required": [ "data" ] }, "SimulationProgressSchema": { "type": "object", "properties": { "percentage": { "type": "number" }, "state": { "type": "string" }, "eta": { "type": [ "number", "null" ] } }, "required": [ "percentage", "state" ] }, "SortColumnSchema": { "type": "object", "properties": { "column": { "type": "string" }, "direction": { "$ref": "#/components/schemas/SortDirectionEnum" } }, "required": [ "column", "direction" ] }, "SortDirectionEnum": { "type": "string", "enum": [ "asc", "desc" ] }, "SourceDeleteConflictProblem": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "number", "const": 409 }, "detail": { "type": "string" }, "instance": { "type": "string" }, "blockingDigitalTwins": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "description": "The digital twins in this workspace trained on the source or on anything derived from it. Twins in workspaces this credential cannot reach are counted in `detail` rather than listed here." }, "sharedSources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "description": "The sources in the deletion tree that are shared into other workspaces. Present when that is what blocks the delete." }, "otherWorkspaceLinks": { "type": "number", "description": "How many links into other workspaces those sources hold between them." } }, "required": [ "type", "title", "status", "detail", "blockingDigitalTwins" ] }, "SourceEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Source" } }, "required": [ "data" ] }, "SourceJoinConfigSchema": { "type": "object", "properties": { "joinType": { "type": "string", "enum": [ "left", "inner" ], "default": "left" }, "strategy": { "type": [ "string", "null" ] } } }, "SourceListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Pass back as ?cursor= to fetch the next page" }, "hasMore": { "type": "boolean", "description": "Whether a further page exists" }, "total": { "type": "number", "description": "Total matching rows, when the query can count them" } }, "required": [ "hasMore" ] } }, "required": [ "data", "pagination" ] }, "SourcePinSchema": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "latest" } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "pinned" }, "versionId": { "type": "string" } }, "required": [ "kind", "versionId" ] } ], "discriminator": { "propertyName": "kind" } }, "SourceSchema": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "DATASET" }, "name": { "type": [ "string", "null" ] }, "conceptIds": { "type": "array", "items": { "type": "string" } }, "conceptVersions": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, { "type": "null" } ] }, "version": { "anyOf": [ { "$ref": "#/components/schemas/SourcePinSchema" }, { "type": "null" } ] } }, "required": [ "id", "type", "conceptIds" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "DATA_VIEW" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "CONCEPT" }, "name": { "type": [ "string", "null" ] }, "prioritiseCalculation": { "type": "boolean", "default": true }, "showCalculationColumns": { "type": "boolean", "default": false } }, "required": [ "id", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "GEO_SIDECAR" }, "name": { "type": [ "string", "null" ] }, "conceptId": { "type": "string" }, "sidecarKey": { "type": "string" } }, "required": [ "id", "type", "conceptId", "sidecarKey" ] } ], "discriminator": { "propertyName": "type" } }, "SplitInput": { "type": "object", "properties": { "fieldMapping": { "$ref": "#/components/schemas/PublicFieldMappingSchema" } }, "required": [ "fieldMapping" ] }, "SplitTypeEnum": { "type": "string", "enum": [ "delimiter", "pattern" ] }, "StaticInterventionSpecSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "intervention" }, "interventions": { "type": "array", "items": { "$ref": "#/components/schemas/InterventionSchema" }, "description": "A list of interventions with their respective conditions" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricSchema" }, "description": "SQL queries to calculate the metrics of interest." }, "variablesRelevantToMetric": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Variables causally relevant to the metric." }, "segmentDefinitions": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDefinitionSchema" } }, { "type": "null" } ], "description": "Optional list of segment definitions for targeted analysis of results." } }, "required": [ "type", "interventions", "metrics" ] }, "StaticPanelAnomalyDetectionRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "static_panel_anomaly_detection" }, "samples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ] }, "samplesRef": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" }, { "type": "null" } ] }, "targetFpr": { "type": "number", "minimum": 0.0001, "maximum": 0.1, "default": 0.005 }, "parentToleranceSigma": { "type": "number", "default": 0.5 }, "autoRca": { "type": "boolean", "default": true }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "panelSamples": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, { "type": "null" } ] }, "panelSamplesRef": { "anyOf": [ { "$ref": "#/components/schemas/PanelScenarioSamplesRefSchema" }, { "type": "null" } ] } }, "required": [ "type" ] }, "StaticPanelAnomalyDetectionResultSchema": { "type": "object", "properties": { "environmentResults": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AnomalyDetectionResultSchema" } } }, "required": [ "environmentResults" ] }, "StaticPanelRootCauseAnalysisRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "static_panel_root_cause_analysis" }, "targetVariable": { "type": "string" }, "samples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ] }, "samplesRef": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" }, { "type": "null" } ] }, "targetFpr": { "type": "number", "minimum": 0.0001, "maximum": 0.1, "default": 0.005 }, "parentToleranceSigma": { "type": "number", "default": 0.5 }, "environments": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "panelSamples": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "additionalProperties": {} } } }, { "type": "null" } ] }, "panelSamplesRef": { "anyOf": [ { "$ref": "#/components/schemas/PanelScenarioSamplesRefSchema" }, { "type": "null" } ] } }, "required": [ "type", "targetVariable" ] }, "StaticPanelRootCauseAnalysisResultSchema": { "type": "object", "properties": { "environmentResults": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/RootCauseAnalysisResultSchema" } } }, "required": [ "environmentResults" ] }, "StatusTypeEnum": { "type": "string", "enum": [ "active", "deprecated" ] }, "SuggestedRoleEnum": { "type": "string", "enum": [ "source", "target" ] }, "SuggestedSimulationSchema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "scenario": { "$ref": "#/components/schemas/DigitalTwinScenarioSchema" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "description", "scenario", "createdAt" ] }, "SymbolicEquationAlternativeSchema": { "type": "object", "properties": { "label": { "type": "string", "description": "How this alternative trades off, e.g. 'Balanced', 'Fewer terms', 'Better fit'" }, "expression": { "type": "string" }, "r2": { "type": [ "number", "null" ] }, "complexity": { "type": [ "number", "null" ] } }, "required": [ "label", "expression" ] }, "SymbolicEquationSchema": { "type": "object", "properties": { "expression": { "type": "string" }, "r2": { "type": "number" }, "noisePercentage": { "type": "number" }, "termBreakdown": { "type": "array", "items": { "$ref": "#/components/schemas/SymbolicTermSchema" } }, "complexity": { "type": "number" }, "explanationType": { "type": "string", "enum": [ "regression", "classification_rules", "conditional_probability" ], "default": "regression" }, "epsilonSigma": { "type": [ "number", "null" ] }, "epsilonSigmaRelative": { "type": [ "number", "null" ] }, "expressionWithNoise": { "type": [ "string", "null" ] }, "discoveryMethod": { "type": [ "string", "null" ] }, "parentContributions": { "type": "array", "items": { "$ref": "#/components/schemas/SymbolicParentContributionSchema" } }, "unexplainedPct": { "type": [ "number", "null" ] }, "directionReferenceClass": { "type": [ "string", "null" ] }, "alternatives": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SymbolicEquationAlternativeSchema" } }, { "type": "null" } ], "description": "Pareto-front alternatives to the chosen equation (balanced / fewer terms / better fit); absent until discovery emits them" } }, "required": [ "expression", "r2", "noisePercentage", "termBreakdown", "complexity" ] }, "SymbolicParentContributionSchema": { "type": "object", "properties": { "parent": { "type": "string" }, "contributionPct": { "type": "number" }, "signedEffect": { "type": "number" }, "direction": { "type": "string", "enum": [ "positive", "negative", "mixed", "none" ] }, "terms": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "included", "noEffect" ] } }, "required": [ "parent", "contributionPct", "signedEffect", "direction", "terms", "status" ] }, "SymbolicTermSchema": { "type": "object", "properties": { "expression": { "type": "string" }, "parentVariable": { "type": [ "string", "null" ] }, "parentVariables": { "type": "array", "items": { "type": "string" } }, "coefficient": { "type": "number" }, "operator": { "type": "string" }, "contributionPercentage": { "type": "number" } }, "required": [ "expression", "coefficient", "operator", "contributionPercentage" ] }, "TargetEffectSchema": { "type": "object", "properties": { "causeTarget": { "type": [ "string", "number" ], "description": "Target value of the cause" }, "scalarEffect": { "type": "number", "description": "Scalar effect size" }, "confidenceInterval": { "type": "array", "items": { "type": "number" }, "description": "Confidence interval for the effect" }, "statisticalSignificance": { "type": "number", "description": "Statistical significance level" }, "deltaVector": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "Change in probability distribution" }, "nReplicates": { "type": "number", "description": "Number of replicates" }, "effectiveSampleSize": { "type": "number", "description": "Effective sample size" } }, "required": [ "causeTarget", "scalarEffect", "confidenceInterval", "statisticalSignificance", "nReplicates", "effectiveSampleSize" ] }, "TargetModeSchema": { "type": "string", "enum": [ "absolute", "relative_percentage", "relative_absolute" ], "default": "absolute" }, "TemporalAnomalyDetectionRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "temporal_anomaly_detection" }, "samples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ] }, "samplesRef": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" }, { "type": "null" } ] }, "startStep": { "type": [ "number", "null" ] }, "endStep": { "type": [ "number", "null" ] }, "targetFpr": { "type": "number", "minimum": 0.0001, "maximum": 0.1, "default": 0.005 }, "parentToleranceSigma": { "type": "number", "default": 0.5 }, "autoRcaTopK": { "type": "integer", "minimum": 0, "default": 1 } }, "required": [ "type" ] }, "TemporalAnomalyDetectionResultSchema": { "type": "object", "properties": { "calibratedThresholds": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ] }, "targetFpr": { "type": [ "number", "null" ] }, "totalTimestepsScanned": { "type": "number" }, "timesteps": { "type": "array", "items": { "$ref": "#/components/schemas/SampleAnomalyScanResultSchema" }, "default": [] }, "executionTime": { "type": "number", "default": 0 } }, "required": [ "totalTimestepsScanned" ] }, "TemporalCausalRelationshipAnalysisSchema": { "type": "object", "properties": { "causeVar": { "type": "string" }, "effectVar": { "type": "string" }, "overallEffect": { "$ref": "#/components/schemas/TemporalOverallEffectAnalysisSchema" }, "effectPropagation": { "anyOf": [ { "$ref": "#/components/schemas/TimeSeriesForecastSchema" }, { "type": "null" } ] }, "causalPaths": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } }, "required": [ "causeVar", "effectVar", "overallEffect", "causalPaths" ] }, "TemporalCausalStrengthSchema": { "type": "object", "properties": { "lag": { "type": "number" }, "effectSize": { "type": "number" }, "confidenceInterval": { "type": "array", "items": { "type": "number" } }, "statisticalSignificance": { "type": "number" } }, "required": [ "lag", "effectSize", "confidenceInterval", "statisticalSignificance" ] }, "TemporalCounterfactualExplanationSchema": { "type": "object", "properties": { "currentState": { "type": "object", "additionalProperties": {} }, "baselineTrajectory": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TimeSeriesForecastSchema" } }, "requestedTargets": { "type": "array", "items": { "$ref": "#/components/schemas/TemporalCounterfactualTargetSchema" } }, "counterfactuals": { "type": "array", "items": { "$ref": "#/components/schemas/TemporalCounterfactualSchema" } }, "baselineAlreadyMeetsTarget": { "type": [ "boolean", "null" ] }, "baselineAchievedAt": { "type": [ "number", "null" ] } }, "required": [ "currentState", "baselineTrajectory", "requestedTargets", "counterfactuals" ] }, "TemporalCounterfactualRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "temporal_counterfactual" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/TemporalCounterfactualTargetSchema" } }, "constraints": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CounterfactualVariableConstraintSchema" } }, { "type": "null" } ] }, "maxChanges": { "type": "number", "default": 3 }, "forecastHorizon": { "type": [ "number", "null" ] } }, "required": [ "type", "targets" ] }, "TemporalCounterfactualSchema": { "type": "object", "properties": { "changes": { "type": "array", "items": { "$ref": "#/components/schemas/TemporalVariableChangeSchema" } }, "predictedTrajectories": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TimeSeriesForecastSchema" } }, "targetAchievedAt": { "type": [ "number", "null" ] }, "allTargetsMet": { "type": "boolean" }, "certainty": { "type": "number" } }, "required": [ "changes", "predictedTrajectories", "allTargetsMet", "certainty" ] }, "TemporalCounterfactualTargetSchema": { "type": "object", "properties": { "variable": { "type": "string" }, "value": {}, "timestamp": { "type": [ "number", "null" ] }, "aggregation": { "type": "string", "enum": [ "point", "mean", "cumulative" ], "default": "point" }, "targetMode": { "$ref": "#/components/schemas/TargetModeSchema" }, "matchMode": { "anyOf": [ { "$ref": "#/components/schemas/CounterfactualMatchModeSchema" }, { "type": "null" } ], "description": "Left unset, each aggregation keeps its own rule: a 10% band for point and mean, at-least for cumulative. A value overrides that." }, "toleranceType": { "anyOf": [ { "$ref": "#/components/schemas/CounterfactualToleranceTypeSchema" }, { "type": "null" } ] }, "toleranceValue": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "variable" ] }, "TemporalDependenciesObjectSchema": { "type": "object", "properties": { "prerequisites": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "prerequisites" ] }, "TemporalDependenciesSchema": { "anyOf": [ { "not": {} }, { "anyOf": [ { "$ref": "#/components/schemas/TemporalDependenciesObjectSchema" }, { "type": "null" } ] } ] }, "TemporalDependencyChangeSchema": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ChangeTypeEnum" }, "variable": { "type": "string" }, "oldPrerequisites": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "newPrerequisites": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "type", "variable" ] }, "TemporalExplanationRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "temporal_explanation" }, "explanationMode": { "anyOf": [ { "$ref": "#/components/schemas/ExplanationModeSchema" }, { "type": "null" } ], "description": "Explicit explanation mode selection" }, "causeVariable": { "type": [ "string", "null" ] }, "effectVariable": { "type": [ "string", "null" ] }, "causeVariables": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Multi-select cause variables for directional mode" }, "effectVariables": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Multi-select effect variables for directional mode" }, "segments": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDefinitionSchema" } }, { "type": "null" } ] }, "forecastHorizonOverride": { "type": [ "number", "null" ] } }, "required": [ "type" ] }, "TemporalExplanationResultSchema": { "type": "object", "properties": { "explanationType": { "type": "string", "enum": [ "directional", "discovery", "impact" ] }, "causalRelationships": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TemporalCausalRelationshipAnalysisSchema" } }, { "type": "null" } ] }, "forecastHorizonUsed": { "type": "number" }, "executionTime": { "type": "number" } }, "required": [ "explanationType", "forecastHorizonUsed", "executionTime" ] }, "TemporalInterventionTimingSchema": { "type": "object", "properties": { "variable": { "type": "string" }, "earliestTimestamp": { "type": [ "number", "null" ] }, "latestTimestamp": { "type": [ "number", "null" ] }, "allowRamping": { "type": "boolean", "default": true }, "maxRampSteps": { "type": [ "number", "null" ] } }, "required": [ "variable" ] }, "TemporalMetricSpecSchema": { "type": "object", "properties": { "startDate": { "type": [ "string", "null" ], "description": "Evaluation start as an ISO date (UTC); the backend resolves it into startTimestampMs" }, "endDate": { "type": [ "string", "null" ], "description": "Evaluation end as an ISO date (UTC), inclusive" }, "startTimestampMs": { "type": [ "number", "null" ], "description": "Start timestamp (ms). Without an end the window runs intervalSteps grid steps from here; a start alone is one grid step." }, "endTimestampMs": { "type": [ "number", "null" ], "description": "End timestamp (ms) inclusive. Windows narrower than one model step widen to one full step." }, "intervalSteps": { "type": [ "number", "null" ], "description": "Window length in model steps when no end is given, counted from the start (or the first forecast step). Ignored when an end is set." } } }, "TemporalOptimisationObjectiveSchema": { "type": "object", "properties": { "direction": { "type": "string", "enum": [ "maximise", "minimise" ] }, "variable": { "type": "string" }, "metricSqlQuery": { "type": "string" }, "weight": { "type": "number", "default": 1 }, "temporal": { "anyOf": [ { "$ref": "#/components/schemas/TemporalMetricSpecSchema" }, { "type": "null" } ] }, "discountFactor": { "type": "number", "default": 1 }, "conceptId": { "type": [ "string", "null" ] }, "conceptEditVersion": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "direction", "variable", "metricSqlQuery" ] }, "TemporalOptimisationScenarioSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "temporal_optimisation" }, "objectives": { "type": "array", "items": { "$ref": "#/components/schemas/TemporalOptimisationObjectiveSchema" } }, "decisionVars": { "type": "array", "items": { "type": "string" } }, "variableConstraints": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/VariableConstraintSchema" } }, { "type": "null" } ] }, "metricConstraints": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/MetricConstraintSchema" } }, { "type": "null" } ] }, "interventionTiming": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/TemporalInterventionTimingSchema" } }, { "type": "null" } ] }, "forecastHorizon": { "type": "number" }, "interventionCountConfig": { "anyOf": [ { "$ref": "#/components/schemas/InterventionCountConfigSchema" }, { "type": "null" } ] } }, "required": [ "type", "objectives", "decisionVars", "forecastHorizon" ] }, "TemporalOptimizationResultSchema": { "type": "object", "properties": { "paretoFront": { "type": "array", "items": { "$ref": "#/components/schemas/TemporalParetoDominantSolutionSchema" } }, "baselineMetrics": { "type": "object", "additionalProperties": { "type": "number" } }, "balancedSolution": { "anyOf": [ { "$ref": "#/components/schemas/TemporalParetoDominantSolutionSchema" }, { "type": "null" } ] }, "bestPerObjective": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TemporalParetoDominantSolutionSchema" } }, { "type": "null" } ] }, "forecastHorizon": { "type": "number" }, "forecastStartMs": { "type": [ "number", "null" ], "description": "First forecast grid timestamp (ms): the step after the training data ends" }, "forecastEndMs": { "type": [ "number", "null" ], "description": "Last forecast grid timestamp (ms, inclusive)" }, "executionTime": { "type": "number" }, "allConstraintsSatisfiable": { "type": "boolean", "default": true, "description": "Whether any plan satisfying every metric constraint was found" }, "metricScaleBases": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MetricScaleBasisSchema" } }, { "type": "null" } ], "description": "Per-objective scale basis; an extensive metric over the stacked Monte Carlo paths is rescaled to a single path" } }, "required": [ "paretoFront", "baselineMetrics", "forecastHorizon", "executionTime" ] }, "TemporalOverallEffectAnalysisSchema": { "type": "object", "properties": { "effectSize": { "type": "number" }, "effectRange": { "type": "array", "items": { "type": "number" } }, "confidenceInterval": { "type": "array", "items": { "type": "number" } }, "statisticalSignificance": { "type": "number" }, "lagEffects": { "type": "array", "items": { "$ref": "#/components/schemas/TemporalCausalStrengthSchema" } }, "seasonalEffects": { "type": "array", "items": { "$ref": "#/components/schemas/SeasonalEffectDecompositionSchema" } }, "impulseResponse": { "type": "array", "items": { "type": "number" } }, "cumulativeEffect": { "type": "number" }, "peakEffectLag": { "type": "number" }, "contrast": { "$ref": "#/components/schemas/ContrastSchema" } }, "required": [ "effectSize", "effectRange", "confidenceInterval", "statisticalSignificance", "lagEffects", "seasonalEffects", "impulseResponse", "cumulativeEffect", "peakEffectLag", "contrast" ] }, "TemporalParetoDominantSolutionSchema": { "type": "object", "properties": { "interventions": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Interventions in this solution" }, "interventionCount": { "type": "number", "default": 0, "description": "Number of interventions in this solution" }, "objectiveValues": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Values of the objectives" }, "implementationDifficulty": { "type": [ "number", "null" ], "description": "Difficulty of implementing this solution" }, "expectedOutcomes": { "type": "object", "additionalProperties": {}, "description": "Expected outcomes of the solution" }, "uncertainty": { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": {} }, "description": "Uncertainty in objective values" }, "improvementOverBaseline": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Improvements over baseline" }, "constraintsSatisfied": { "type": "boolean", "default": true, "description": "Whether all constraints were satisfied by this solution" }, "constraintViolations": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Descriptions of constraint violations if any" }, "targetsAchieved": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "boolean" } }, { "type": "null" } ], "description": "Whether each objective's target was achieved" }, "segmentResults": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "number" } } }, { "type": "null" } ], "description": "Per-segment objective values: {segment_id: {objective_name: value}}" }, "segmentSampleSizes": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "number" } }, { "type": "null" } ], "description": "Per-segment sample sizes: {segment_id: sample_count}" }, "segmentInterventions": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ], "description": "Segment-specific interventions with conditions" }, "totalSampleCount": { "type": [ "number", "null" ] }, "affectedSampleCount": { "type": [ "number", "null" ] }, "affectedPercentage": { "type": [ "number", "null" ] }, "appliedInterventions": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/InterventionSchema" } }, { "type": "null" } ], "description": "The exact intervention rows the evaluator ran for this plan, after scoping and relative-mode conversion" }, "interventionResult": { "anyOf": [ { "$ref": "#/components/schemas/TimeSeriesInterventionResultSchema" }, { "type": "null" } ], "description": "The plan re-run as a Monte Carlo temporal intervention over the same horizon" }, "interventionSequence": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesInterventionSchema" } }, "forecastTrajectories": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TimeSeriesForecastSchema" } }, { "type": "null" } ], "description": "Superseded by interventionResult.forecastData; empty on runs that carry a per-plan result" } }, "required": [ "interventions", "objectiveValues", "expectedOutcomes", "uncertainty", "improvementOverBaseline", "interventionSequence" ] }, "TemporalRootCauseAnalysisRequestSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "temporal_root_cause_analysis" }, "targetVariable": { "type": "string" }, "samples": { "anyOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ] }, "samplesRef": { "anyOf": [ { "$ref": "#/components/schemas/ScenarioSamplesRefSchema" }, { "type": "null" } ] }, "anomalyTimestep": { "type": [ "number", "null" ] }, "targetFpr": { "type": "number", "minimum": 0.0001, "maximum": 0.1, "default": 0.005 }, "parentToleranceSigma": { "type": "number", "default": 0.5 } }, "required": [ "type", "targetVariable" ] }, "TemporalVariableChangeSchema": { "type": "object", "properties": { "variable": { "type": "string" }, "fromValue": {}, "toValue": {}, "timestamp": { "type": [ "number", "null" ] }, "persistent": { "type": "boolean", "default": true }, "rampSteps": { "type": [ "number", "null" ] }, "importance": { "type": "number", "default": 1 } }, "required": [ "variable" ] }, "TimeComponentArtifactSchema": { "type": "object", "properties": { "models": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TimeDecompositionModelSchema" } }, "varExplained": { "type": "object", "additionalProperties": { "type": "number" } }, "trainNSamples": { "type": "number" } }, "required": [ "models", "varExplained", "trainNSamples" ] }, "TimeDecompositionModelSchema": { "type": "object", "properties": { "theilSenSlope": { "type": "number" }, "theilSenIntercept": { "type": "number" }, "harmonic": { "anyOf": [ { "$ref": "#/components/schemas/HarmonicFitSchema" }, { "type": "null" } ] } }, "required": [ "theilSenSlope", "theilSenIntercept" ] }, "TimeSeriesCoverageSchema": { "type": "object", "properties": { "observedSteps": { "type": "number", "description": "Grid steps that carried at least one observed row" }, "gridSteps": { "type": "number", "description": "Steps on the dense grid the twin trains on" }, "imputedSteps": { "type": "number", "description": "Grid steps reconstructed by imputation, never measured" }, "gapCount": { "type": "number", "description": "Total gap runs; `gaps` lists only the largest" }, "gaps": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesGapSchema" } } }, "required": [ "observedSteps", "gridSteps", "imputedSteps", "gapCount", "gaps" ] }, "TimeSeriesEnvProfileSchema": { "type": "object", "properties": { "envKey": { "type": "string" }, "tsSeasonalPeriods": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SeasonalPeriodSchema" } }, { "type": "null" } ] }, "tsCategoricalSeasonality": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CategoricalSeasonalPeriodSchema" } }, { "type": "null" } ] }, "tsMissingPatterns": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CyclicPatternSchema" } }, { "type": "null" } ] }, "tsActiveWindows": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CyclicPatternSchema" } }, { "type": "null" } ] }, "trendSlopePerSecond": { "type": [ "number", "null" ] }, "trendR2": { "type": [ "number", "null" ] }, "tsTypicalDeltaSeconds": { "type": [ "number", "null" ] } }, "required": [ "envKey" ] }, "TimeSeriesForecastSchema": { "type": "object", "properties": { "variable": { "type": "string", "description": "Variable name" }, "timestamps": { "type": "array", "items": { "type": "number" }, "description": "Timestamps in milliseconds" }, "baselineMean": { "type": "array", "items": { "type": "number" }, "description": "Mean values under baseline" }, "baselineStd": { "type": "array", "items": { "type": "number" }, "description": "Std dev under baseline" }, "interventionMean": { "type": "array", "items": { "type": "number" }, "description": "Mean values under intervention" }, "interventionStd": { "type": "array", "items": { "type": "number" }, "description": "Std dev under intervention" }, "categories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Ordered category labels when the variable is categorical; null for numeric variables" }, "baselineProbs": { "anyOf": [ { "type": "array", "items": { "type": "array", "items": { "type": "number" } } }, { "type": "null" } ], "description": "Per-timestep category probabilities under baseline, shape [timestep][category]" }, "interventionProbs": { "anyOf": [ { "type": "array", "items": { "type": "array", "items": { "type": "number" } } }, { "type": "null" } ], "description": "Per-timestep category probabilities under intervention, shape [timestep][category]" }, "interventionTimestamp": { "type": [ "number", "null" ], "description": "When intervention started (if applicable)" }, "historyTimestamps": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ], "description": "Trailing observed-history timestamps in ms, ending at the forecast start boundary; absent on categorical variables and results stored before this field existed" }, "historyValues": { "anyOf": [ { "type": "array", "items": { "type": [ "number", "null" ] } }, { "type": "null" } ], "description": "Observed values aligned with historyTimestamps; null entries mark missing source rows" }, "isIntervened": { "type": "boolean", "description": "Whether this variable was directly intervened on" }, "isMediator": { "type": "boolean", "description": "Whether this is on causal path" }, "isOutcome": { "type": "boolean", "description": "Whether this is a metric/outcome variable" } }, "required": [ "variable", "timestamps", "baselineMean", "baselineStd", "interventionMean", "interventionStd", "isIntervened", "isMediator", "isOutcome" ] }, "TimeSeriesGapSchema": { "type": "object", "properties": { "startDate": { "type": "string", "description": "First grid step in the gap" }, "endDate": { "type": "string", "description": "Last grid step in the gap" }, "missingSteps": { "type": "number", "description": "Consecutive grid steps with no observed rows" } }, "required": [ "startDate", "endDate", "missingSteps" ] }, "TimeSeriesInterventionResultSchema": { "type": "object", "properties": { "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricResultSchema" }, "description": "Intervention metrics" }, "sampleSize": { "type": "number", "description": "Number of samples used" }, "causalPaths": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "Causal paths from intervention to target" }, "causalPathsByMetric": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "description": "Causal paths per metric name" }, "segmentAnalysis": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentEffectSchema" }, "description": "Segment-specific effects" }, "uncertainty": { "type": "object", "properties": { "meanEffect": { "type": "number", "description": "Mean effect" }, "stdEffect": { "type": "number", "description": "Standard deviation of effect" }, "confidenceInterval": { "type": "array", "items": { "type": "number" }, "description": "Confidence interval" }, "confidenceLevel": { "type": "number", "description": "Confidence level" }, "pValue": { "type": "number", "description": "P-value testing null hypothesis of no effect" }, "significant": { "type": "boolean", "description": "Whether the effect is statistically significant" }, "robustnessValue": { "type": [ "number", "null" ], "description": "Cinelli-Hazlett robustness value: share of residual variance an unmeasured confounder must explain in both treatment and outcome to move the estimate to the null (0..1)" }, "eValue": { "type": [ "number", "null" ], "description": "E-value on the risk-ratio scale; only present for binary-rate metrics" }, "eValueCiLimit": { "type": [ "number", "null" ], "description": "E-value for the confidence-interval limit closest to the null" }, "baselineInterval": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ], "description": "Percentile interval of the resampled baseline reading, on the metric's scale, at confidenceLevel" } }, "required": [ "meanEffect", "stdEffect", "confidenceInterval", "confidenceLevel", "pValue", "significant" ], "description": "Uncertainty quantification" }, "uncertainties": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/InterventionUncertaintySchema" }, "description": "Per-metric bootstrap uncertainties" }, "mediatorShifts": { "$ref": "#/components/schemas/MediatorShiftsSchema", "description": "Per-metric mediator shifts: {metricName: {mediators: [...], paths: {...}}}" }, "robustness": { "$ref": "#/components/schemas/InterventionRobustnessScoreInlineSchema", "description": "Robustness score for panel data interventions" }, "interventionValues": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": {} } }, { "type": "null" } ], "description": "Pre/post value per intervened variable: {variable: {baseline, intervention}}" }, "sweptVariable": { "type": [ "string", "null" ], "description": "Variable swept by a `range` intervention, when the scenario carried one" }, "sweptMode": { "anyOf": [ { "type": "string", "enum": [ "absolute", "percentage" ] }, { "type": "null" } ], "description": "Units of the sweep grid — percentage grids apply relative changes and share units with percent dials" }, "doseResponse": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DoseResponseAnalysisSchema" } }, { "type": "null" } ], "description": "Per-metric sweep curve keyed by metric name, present only for range scenarios" }, "executionTime": { "type": "number", "description": "Execution time in seconds" }, "originalInterventions": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/TimeSeriesInterventionSchema" }, { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesInterventionSchema" } } ] } }, { "type": "null" } ], "description": "Original intervention spec as provided by user (preserves sequences and ramps)" }, "expandedInterventions": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesInterventionSchema" } }, "description": "Mapping from timestamp to the concrete interventions applied at that time" }, "forecastData": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TimeSeriesForecastSchema" }, "description": "Time series forecasts for intervened variables, mediators, and outcomes" }, "forecastStartMs": { "type": [ "number", "null" ], "description": "First forecast grid timestamp (ms): the step after the training data ends" }, "forecastEndMs": { "type": [ "number", "null" ], "description": "Last forecast grid timestamp (ms, inclusive)" } }, "required": [ "metrics", "sampleSize", "uncertainty", "executionTime" ] }, "TimeSeriesInterventionSchema": { "type": "object", "properties": { "variable": { "type": "string", "description": "The variable to intervene on" }, "valueSpec": { "anyOf": [ { "$ref": "#/components/schemas/SetValueSpecSchema" }, { "$ref": "#/components/schemas/RelativeChangeSpecSchema" }, { "$ref": "#/components/schemas/SetProbabilitySpecSchema" }, { "$ref": "#/components/schemas/AdjustProbabilitySpecSchema" }, { "$ref": "#/components/schemas/SetMembersSpecSchema" }, { "$ref": "#/components/schemas/RangeValueSpecSchema" } ], "description": "Specification of how to modify the variable." }, "conditions": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ConditionSchema" } }, { "type": "null" } ], "description": "Optional conditions defining the subpopulation for intervention." }, "detachFormula": { "type": [ "boolean", "null" ], "description": "Allow this intervention on a computed value. Its formula is switched off for the run: the variable takes the intervened value instead of being recomputed from its inputs, and its inputs do not move to match." }, "timestamp": { "type": [ "number", "null" ], "description": "The timestamp to intervene at (for temporal models)" }, "persistent": { "type": [ "boolean", "null" ], "description": "If True, intervention persists from timestamp onwards. If False, applies only at that timestamp. Only used for temporal models." }, "durationSteps": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Hold the value for this many steps starting at the timestamp, then release. Overrides persistent when set (>1). Only used for temporal models." }, "rampSteps": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ], "description": "Number of steps to gradually reach this intervention's value. Within a sequence, ramps from the previous state; on a single intervention, ramps from baseline (relative changes only)." } }, "required": [ "variable", "valueSpec" ] }, "TimeSeriesInterventionSpecSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "temporal_intervention" }, "interventions": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/TimeSeriesInterventionSchema" }, { "type": "array", "items": { "$ref": "#/components/schemas/TimeSeriesInterventionSchema" } } ] }, "description": "A list of time series interventions or sequences (nested lists) for time series models" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/MetricSchema" }, "description": "SQL queries to calculate the metrics of interest." }, "variablesRelevantToMetric": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Variables causally relevant to the metric." }, "segmentDefinitions": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SegmentDefinitionSchema" } }, { "type": "null" } ], "description": "Optional list of segment definitions for targeted analysis of results." } }, "required": [ "type", "interventions", "metrics" ] }, "TimeSeriesMetadataSchema": { "type": "object", "properties": { "colName": { "type": "string", "description": "Column name for the time series" }, "granularity": { "type": "string", "enum": [ "ms", "s", "min", "h", "D", "W", "ME", "Y", "L", "S", "T", "H" ], "description": "Current granularity of the time series" }, "validGranularities": { "type": "array", "items": { "type": "string" }, "description": "List of valid granularities" }, "startDate": { "type": "string", "description": "Start date of the time series" }, "endDate": { "type": "string", "description": "End date of the time series" }, "typicalDeltaSeconds": { "type": [ "number", "null" ] }, "selectedGrid": { "type": [ "string", "null" ] }, "candidateGrids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "scoring": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "additionalProperties": { "type": "number" } } }, { "type": "null" } ] }, "coverage": { "anyOf": [ { "$ref": "#/components/schemas/TimeSeriesCoverageSchema" }, { "type": "null" } ], "description": "Observed vs imputed grid steps; absent on twins trained before this existed" } }, "required": [ "colName", "granularity", "validGranularities", "startDate", "endDate" ] }, "ToleranceUnitEnum": { "type": "string", "enum": [ "us", "ms", "s", "m", "h", "d" ] }, "UnlinkSchema": { "type": "object", "properties": { "sourceIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "sourceIds" ] }, "UnmatchedRuleEnum": { "type": "string", "enum": [ "error", "drop", "append" ] }, "UnspecifiedEnvelope": { "type": "object", "properties": { "data": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "object", "additionalProperties": {} }, { "type": "array", "items": {} } ], "description": "Payload not declared in this repo" } }, "required": [ "data" ] }, "UpdateConnectorInput": { "type": "object", "properties": { "name": { "type": "string" }, "credentials": { "type": [ "object", "null" ], "additionalProperties": {} } } }, "UpdateDataViewSchema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/DataViewMutationSourceSchema" } }, "operations": { "type": "array", "items": {} }, "anchorConceptId": { "type": [ "string", "null" ] } } }, "UpdateEnvironmentGroupInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "New display name; unique per twin" }, "definition": { "$ref": "#/components/schemas/EnvironmentGroupDefinitionSchema", "description": "Replacement membership rule" } } }, "UpdateReportInput": { "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "markdown": { "type": "string" } } }, "UpdateSourceSchema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "UpdateTwinInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "tags": { "type": "array", "items": { "type": "string" } } } }, "UpdateWorkspaceSchema": { "type": "object", "properties": { "name": { "type": "string" } }, "additionalProperties": false }, "ValueClassEnum": { "type": "string", "enum": [ "continuous", "sparse_event", "bursty", "binary_indicator" ] }, "VariableChangeSchema": { "type": "object", "properties": { "variable": { "type": "string", "description": "The variable to change" }, "fromValue": { "description": "Original value" }, "toValue": { "description": "New value" }, "importance": { "type": "number", "description": "Importance of the change" } }, "required": [ "variable", "importance" ] }, "VariableConstraintSchema": { "type": "object", "properties": { "variable": { "type": "string", "description": "The variable this constraint applies to" }, "type": { "type": "string", "enum": [ "range", "set", "conditional" ], "description": "Type of constraint" }, "minValue": { "type": [ "number", "null" ], "description": "Minimum allowed value (for range type)" }, "maxValue": { "type": [ "number", "null" ], "description": "Maximum allowed value (for range type)" }, "allowedValues": { "anyOf": [ { "type": "array", "items": { "type": [ "string", "number", "boolean" ] } }, { "type": "null" } ], "description": "List of allowed values (for set type)" }, "maxChangePercent": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Maximum percentage change from baseline allowed" }, "conditionalAllowedValues": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/ConditionalAllowedValuesSchema" } }, { "type": "null" } ], "description": "Conditional allowed values based on other variable values (for conditional type)" } }, "required": [ "variable", "type" ] }, "VariableRolesSchema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "string" } }, "targets": { "type": "array", "items": { "type": "string" } } }, "required": [ "sources", "targets" ] }, "ViewConceptOverrideEntrySchema": { "type": "object", "properties": { "override": { "type": "object", "additionalProperties": {} }, "displayName": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "lineageHash": { "type": [ "string", "null" ] }, "lastEditedBy": { "type": [ "string", "null" ] }, "lastEditedAt": { "type": [ "string", "null" ] } }, "required": [ "override" ] }, "ViewSnapshotSchema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceSchema" } }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/OperationSchema" } }, "outputColumn": { "type": "string" } }, "required": [ "sources", "operations", "outputColumn" ] }, "WebhookBody": { "type": "object", "properties": { "webhookUrl": { "type": [ "string", "null" ], "format": "uri" } } }, "WorkspaceEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ] }, "WorkspaceListEnvelope": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } }, "required": [ "data" ] }, "DigitalTwin": { "type": "object", "properties": { "id": { "type": "string" }, "organisationId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "normalizedName": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/DigitalTwinTypeEnum" }, "canonicalInputSchema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SchemaEntryModelSchema" } }, { "type": "null" } ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/StatusTypeEnum", "default": "active" }, "createdAt": { "type": "string" }, "suggestedSimulations": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SuggestedSimulationSchema" } }, { "type": "null" } ] }, "suggestionsGeneratedAt": { "type": [ "string", "null" ] }, "environmentGroups": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/EnvironmentGroupSchema" } }, { "type": "null" } ] }, "autoUpdate": { "anyOf": [ { "$ref": "#/components/schemas/AutoUpdateSettingsSchema" }, { "type": "null" } ] }, "maintainedBy": { "type": "array", "items": { "type": "object", "properties": { "applicationId": { "type": "string" }, "version": { "type": "string" }, "flowId": { "type": "string" } }, "required": [ "applicationId", "version", "flowId" ] } } }, "required": [ "id", "organisationId", "workspaceId", "name", "type" ] }, "DigitalTwinVersion": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "twinId": { "type": "string" }, "organisationId": { "type": "string" }, "workspaceId": { "type": "string" }, "versionMajor": { "type": "number", "minimum": 0 }, "versionMinor": { "type": "number", "minimum": 0 }, "versionPatch": { "type": "number", "minimum": 0 }, "version": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "createdBy": { "type": [ "string", "null" ] }, "derivedFromVersionId": { "type": [ "string", "null" ] }, "changelog": { "anyOf": [ { "$ref": "#/components/schemas/ChangeLogSchema" }, { "type": "null" } ] }, "datasetId": { "type": "string" }, "type": { "$ref": "#/components/schemas/DigitalTwinTypeEnum" }, "inputFields": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SchemaEntryModelSchema" } }, { "type": "null" } ] }, "temporalDependencies": { "anyOf": [ { "$ref": "#/components/schemas/TemporalDependenciesSchema" }, { "type": "null" } ] }, "timeSeriesMetadata": { "anyOf": [ { "$ref": "#/components/schemas/TimeSeriesMetadataSchema" }, { "type": "null" } ] }, "granularity": { "type": [ "string", "null" ] }, "fixedSubGraph": { "anyOf": [ { "$ref": "#/components/schemas/FixedSubGraphSchema" }, { "type": "null" } ] }, "variableRoles": { "anyOf": [ { "$ref": "#/components/schemas/VariableRolesSchema" }, { "type": "null" } ] }, "derivedColumns": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/DtDerivedColumnInfoSchema" } }, { "type": "null" } ] }, "dataSignature": { "type": "string" }, "configSignature": { "type": "string" }, "nTrainSamples": { "type": [ "number", "null" ] }, "causalGraph": { "type": "array", "items": { "$ref": "#/components/schemas/CausalRelationshipSchema" } }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/CausalNodeSchema" } }, "evaluation": { "anyOf": [ { "$ref": "#/components/schemas/EvaluationResultSchema" }, { "type": "null" } ] }, "panelEvaluation": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/EvaluationResultSchema" } }, { "type": "null" } ] }, "graphRecommendations": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/GraphRecommendationsSchema" } }, { "type": "null" } ] }, "environmentColumns": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "selectedEnvironmentColumns": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "selectedTimeColumnName": { "type": [ "string", "null" ] }, "environmentSelection": { "anyOf": [ { "$ref": "#/components/schemas/EnvironmentSelectionSchema" }, { "type": "null" } ] }, "extraOps": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/OperationSchema" } }, { "type": "null" } ] }, "nEnvironments": { "type": [ "number", "null" ] }, "latentClusters": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/LatentClusterInfoSchema" } }, { "type": "null" } ] }, "latentDiscoveryConfig": { "anyOf": [ { "$ref": "#/components/schemas/LatentDiscoveryConfigSchema" }, { "type": "null" } ] }, "nodeDomains": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "min", "max" ] } }, { "type": "null" } ] }, "lastTimestampMs": { "type": [ "number", "null" ] }, "headCommit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "trainedWindowSignature": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "trainedWindowProfile": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ColumnWindowProfileSchema" } }, { "type": "null" } ] }, "resolvedInputs": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "datasetId": { "type": "string" }, "versionId": { "type": [ "string", "null" ] }, "deltaVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "datasetId" ] } }, { "type": "null" } ] }, "updateEligibility": { "anyOf": [ { "type": "object", "properties": { "updateMode": { "type": "string", "enum": [ "assimilable", "retrain_required", "up_to_date", "unsupported" ] }, "reasons": { "type": "array", "items": { "type": "string" }, "default": [] }, "newRows": { "type": [ "number", "null" ] }, "fromTsMs": { "type": [ "number", "null" ] }, "toTsMs": { "type": [ "number", "null" ] }, "historyDiff": { "anyOf": [ { "$ref": "#/components/schemas/HistoryDiffSchema" }, { "type": "null" } ] } }, "required": [ "updateMode" ] }, { "type": "null" } ] }, "trainingStages": { "anyOf": [ { "type": "object", "properties": { "confounderModelling": { "type": "boolean" }, "equationDiscovery": { "type": "boolean" }, "lagScreening": { "type": [ "boolean", "null" ] }, "evalHorizons": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/EvalHorizonSchema" } }, { "type": "null" } ] } }, "required": [ "confounderModelling", "equationDiscovery" ] }, { "type": "null" } ] }, "timeComponent": { "anyOf": [ { "$ref": "#/components/schemas/TimeComponentArtifactSchema" }, { "type": "null" } ] }, "causalAlgorithmVersion": { "type": [ "string", "null" ] }, "digitalTwinAlgorithmVersion": { "type": [ "string", "null" ] }, "shardCount": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "maxLag": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "layout": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "positions": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } }, { "type": "null" } ] }, "edgeWaypoints": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } }, { "type": "null" } ] } }, "required": [ "success" ] }, { "type": "null" } ] }, "lifecycleState": { "$ref": "#/components/schemas/LifecycleStateEnum", "default": "created" }, "currentTaskId": { "type": [ "string", "null" ] }, "failureContext": { "anyOf": [ { "$ref": "#/components/schemas/FailureContextSchema" }, { "type": "null" } ] }, "traces": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "properties": { "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } } }, { "type": "null" } ] }, "arrayFeatureMap": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, { "type": "null" } ] }, "arrayFeatureToBase": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "twinId", "organisationId", "workspaceId", "versionMajor", "versionMinor", "versionPatch", "datasetId", "type", "dataSignature", "configSignature", "causalGraph", "nodes" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "twinId": { "type": "string" }, "organisationId": { "type": "string" }, "workspaceId": { "type": "string" }, "versionMajor": { "type": "number", "minimum": 0 }, "versionMinor": { "type": "number", "minimum": 0 }, "versionPatch": { "type": "number", "minimum": 0 }, "version": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "createdBy": { "type": [ "string", "null" ] }, "derivedFromVersionId": { "type": [ "string", "null" ] }, "changelog": { "anyOf": [ { "$ref": "#/components/schemas/ChangeLogSchema" }, { "type": "null" } ] }, "sourceId": { "type": "string" }, "type": { "$ref": "#/components/schemas/DigitalTwinTypeEnum" }, "inputFields": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SchemaEntryModelSchema" } }, { "type": "null" } ] }, "temporalDependencies": { "anyOf": [ { "$ref": "#/components/schemas/TemporalDependenciesSchema" }, { "type": "null" } ] }, "timeSeriesMetadata": { "anyOf": [ { "$ref": "#/components/schemas/TimeSeriesMetadataSchema" }, { "type": "null" } ] }, "granularity": { "type": [ "string", "null" ] }, "fixedSubGraph": { "anyOf": [ { "$ref": "#/components/schemas/FixedSubGraphSchema" }, { "type": "null" } ] }, "variableRoles": { "anyOf": [ { "$ref": "#/components/schemas/VariableRolesSchema" }, { "type": "null" } ] }, "derivedColumns": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/DtDerivedColumnInfoSchema" } }, { "type": "null" } ] }, "dataSignature": { "type": "string" }, "configSignature": { "type": "string" }, "nTrainSamples": { "type": [ "number", "null" ] }, "causalGraph": { "type": "array", "items": { "$ref": "#/components/schemas/CausalRelationshipSchema" } }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/CausalNodeSchema" } }, "evaluation": { "anyOf": [ { "$ref": "#/components/schemas/EvaluationResultSchema" }, { "type": "null" } ] }, "panelEvaluation": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/EvaluationResultSchema" } }, { "type": "null" } ] }, "graphRecommendations": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/GraphRecommendationsSchema" } }, { "type": "null" } ] }, "environmentColumns": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "selectedEnvironmentColumns": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "selectedTimeColumnName": { "type": [ "string", "null" ] }, "environmentSelection": { "anyOf": [ { "$ref": "#/components/schemas/EnvironmentSelectionSchema" }, { "type": "null" } ] }, "extraOps": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/OperationSchema" } }, { "type": "null" } ] }, "nEnvironments": { "type": [ "number", "null" ] }, "latentClusters": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/LatentClusterInfoSchema" } }, { "type": "null" } ] }, "latentDiscoveryConfig": { "anyOf": [ { "$ref": "#/components/schemas/LatentDiscoveryConfigSchema" }, { "type": "null" } ] }, "nodeDomains": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "min", "max" ] } }, { "type": "null" } ] }, "lastTimestampMs": { "type": [ "number", "null" ] }, "headCommit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "trainedWindowSignature": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "trainedWindowProfile": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ColumnWindowProfileSchema" } }, { "type": "null" } ] }, "resolvedInputs": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "datasetId": { "type": "string" }, "versionId": { "type": [ "string", "null" ] }, "deltaVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "datasetId" ] } }, { "type": "null" } ] }, "updateEligibility": { "anyOf": [ { "type": "object", "properties": { "updateMode": { "type": "string", "enum": [ "assimilable", "retrain_required", "up_to_date", "unsupported" ] }, "reasons": { "type": "array", "items": { "type": "string" }, "default": [] }, "newRows": { "type": [ "number", "null" ] }, "fromTsMs": { "type": [ "number", "null" ] }, "toTsMs": { "type": [ "number", "null" ] }, "historyDiff": { "anyOf": [ { "$ref": "#/components/schemas/HistoryDiffSchema" }, { "type": "null" } ] } }, "required": [ "updateMode" ] }, { "type": "null" } ] }, "trainingStages": { "anyOf": [ { "type": "object", "properties": { "confounderModelling": { "type": "boolean" }, "equationDiscovery": { "type": "boolean" }, "lagScreening": { "type": [ "boolean", "null" ] }, "evalHorizons": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/EvalHorizonSchema" } }, { "type": "null" } ] } }, "required": [ "confounderModelling", "equationDiscovery" ] }, { "type": "null" } ] }, "timeComponent": { "anyOf": [ { "$ref": "#/components/schemas/TimeComponentArtifactSchema" }, { "type": "null" } ] }, "causalAlgorithmVersion": { "type": [ "string", "null" ] }, "digitalTwinAlgorithmVersion": { "type": [ "string", "null" ] }, "shardCount": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "maxLag": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "layout": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "positions": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } }, { "type": "null" } ] }, "edgeWaypoints": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } }, { "type": "null" } ] } }, "required": [ "success" ] }, { "type": "null" } ] }, "lifecycleState": { "$ref": "#/components/schemas/LifecycleStateEnum", "default": "created" }, "currentTaskId": { "type": [ "string", "null" ] }, "failureContext": { "anyOf": [ { "$ref": "#/components/schemas/FailureContextSchema" }, { "type": "null" } ] }, "traces": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "object", "properties": { "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } } } }, { "type": "null" } ] }, "arrayFeatureMap": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, { "type": "null" } ] }, "arrayFeatureToBase": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "twinId", "organisationId", "workspaceId", "versionMajor", "versionMinor", "versionPatch", "sourceId", "type", "dataSignature", "configSignature", "causalGraph", "nodes" ] } ] }, "OntologyConcept": { "type": "object", "properties": { "id": { "type": "string" }, "organisationId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "conceptClassification": { "anyOf": [ { "$ref": "#/components/schemas/ConceptClassificationEnum" }, { "type": "null" } ] }, "anchorConceptLinks": { "type": "array", "items": { "type": "string" }, "default": [] }, "schemaFieldName": { "type": "string" }, "schemaType": { "$ref": "#/components/schemas/SchemaMainTypeEnum" }, "schemaSubtype": { "anyOf": [ { "$ref": "#/components/schemas/SchemaSubTypeEnum" }, { "type": "null" } ] }, "metadata": { "$ref": "#/components/schemas/ConceptMetadataSchema" }, "lockedMetadataFields": { "type": "array", "items": { "type": "string" } }, "detectedMetadata": { "anyOf": [ { "$ref": "#/components/schemas/ConceptMetadataSchema" }, { "type": "null" } ] }, "fieldMappings": { "type": "array", "items": { "type": "object", "properties": { "sourceId": { "type": "string" }, "field": { "type": "string" }, "status": { "$ref": "#/components/schemas/BindingStatusEnum", "default": "confirmed" }, "source": { "$ref": "#/components/schemas/BindingSourceEnum", "default": "ingest" }, "confidence": { "type": [ "number", "null" ] }, "evidence": { "type": [ "string", "null" ] }, "valueMap": { "anyOf": [ { "anyOf": [ { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "string" }, { "type": "string" } ] } }, { "allOf": [ {}, { "type": "array", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "string" }, { "type": "string" } ] } } ] } ] }, { "type": "null" } ] }, "canonicalField": { "type": [ "string", "null" ] }, "scopeFields": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "precedence": { "type": [ "number", "null" ] }, "keyRole": { "anyOf": [ { "$ref": "#/components/schemas/KeyRoleEnum" }, { "type": "null" } ] }, "conformance": { "anyOf": [ { "$ref": "#/components/schemas/ConformanceReportSchema" }, { "type": "null" } ] }, "decidedBy": { "type": [ "string", "null" ] }, "decidedAt": { "type": [ "string", "null" ] } }, "required": [ "sourceId", "field" ] } }, "derivedInfo": { "anyOf": [ { "$ref": "#/components/schemas/DerivedConceptInfoSchema" }, { "type": "null" } ] }, "conceptKind": { "$ref": "#/components/schemas/ConceptKindEnum", "default": "standard" }, "metricSql": { "type": [ "string", "null" ] }, "relationshipRules": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipRuleSchema" }, "default": [] }, "temporalPrerequisites": { "type": "array", "items": { "type": "string" }, "default": [] }, "suggestedRole": { "anyOf": [ { "$ref": "#/components/schemas/SuggestedRoleEnum" }, { "type": "null" } ] }, "trustTier": { "anyOf": [ { "type": "string", "enum": [ "exploratory", "curated_pending", "curated" ] }, { "type": "null" } ] }, "ontologyRef": { "anyOf": [ { "type": "object", "properties": { "ontologyId": { "type": "string" }, "ontologyVersion": { "type": "string" }, "canonicalId": { "type": "string" }, "installScope": { "anyOf": [ { "type": "object", "properties": { "conceptCanonicalIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "filters": { "type": "array", "items": { "type": "object", "properties": { "conceptRef": { "type": "string" }, "values": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ] } }, "required": [ "conceptRef" ] }, "default": [] } } }, { "type": "null" } ] } }, "required": [ "ontologyId", "ontologyVersion", "canonicalId" ] }, { "type": "null" } ] }, "layerIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" }, "default": [] }, "valueMappings": { "type": "array", "items": { "$ref": "#/components/schemas/ConceptValueMappingSchema" }, "default": [] }, "lockedConceptFields": { "type": "array", "items": { "type": "string" } }, "detectedConceptStructure": { "anyOf": [ { "$ref": "#/components/schemas/DetectedConceptStructureSchema" }, { "type": "null" } ] }, "lastEditedBy": { "type": [ "string", "null" ] }, "lastEditedAt": { "type": [ "string", "null" ] }, "lineageDrift": { "type": [ "boolean", "null" ] }, "editVersion": { "type": "integer", "minimum": 0, "default": 0 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organisationId", "workspaceId", "name", "schemaFieldName", "schemaType", "metadata", "fieldMappings" ] }, "Report": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "workspaceId": { "type": "string" }, "organisationId": { "type": "string" }, "title": { "type": "string" }, "markdown": { "type": "string" }, "widgets": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "chart" }, "explorerConfig": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "dataView": { "anyOf": [ { "$ref": "#/components/schemas/DataViewSchema" }, { "type": "null" } ] }, "operations": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/OperationSchema" } }, { "type": "null" } ] }, "additionalSources": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SourceSchema" } }, { "type": "null" } ] }, "inlineData": { "anyOf": [ { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "None", "String", "Category", "Number", "Boolean", "DateTime", "Array", "Unknown" ] } }, "required": [ "name", "type" ] }, "minItems": 1 }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } }, "default": [] }, "downsampled": { "type": "boolean" }, "totalRows": { "type": [ "number", "null" ] } }, "required": [ "columns" ] }, { "type": "null" } ] }, "series": { "anyOf": [ { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": [ "string", "number" ] }, "default": [] }, "datasets": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "default": [] }, "meta": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "number", "default": 1 }, "xField": { "type": [ "string", "null" ] }, "columns": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ] }, "default": [] }, "series": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "yField": { "type": [ "string", "null" ] }, "aggregation": { "type": [ "string", "null" ] } }, "required": [ "label" ] }, "default": [] }, "categoriesTotal": { "type": [ "number", "null" ] }, "categoriesShown": { "type": [ "number", "null" ] }, "otherFolded": { "type": [ "boolean", "null" ] }, "sortBy": { "type": [ "string", "null" ] }, "sortType": { "type": [ "string", "null" ] }, "binCount": { "type": [ "number", "null" ] }, "linksTotal": { "type": [ "number", "null" ] }, "linksShown": { "type": [ "number", "null" ] }, "pointsTotal": { "type": [ "number", "null" ] }, "pointsShown": { "type": [ "number", "null" ] }, "rowsScanned": { "type": [ "number", "null" ] }, "rowsWithoutCategory": { "type": [ "number", "null" ] }, "rowsExcluded": { "type": [ "number", "null" ] }, "rowsExcludedBy": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "column": { "type": [ "string", "null" ] }, "rows": { "type": "number" } }, "required": [ "reason", "rows" ] } }, { "type": "null" } ] }, "downsampled": { "type": [ "boolean", "null" ] }, "summary": { "type": "string", "default": "" } }, "additionalProperties": true }, { "type": "null" } ] } } }, { "type": "null" } ] }, "xSelection": { "type": "string" }, "traces": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "default": [] }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "bar" }, "options": { "anyOf": [ { "type": "object", "properties": { "stacked": { "type": "boolean", "default": false }, "aggregation": { "type": "string", "enum": [ "average", "sum", "count", "min", "max" ], "default": "sum" } } }, { "type": "null" } ] } }, "required": [ "id", "name", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "line" }, "options": { "anyOf": [ { "type": "object", "properties": { "aggregation": { "anyOf": [ { "type": "string", "enum": [ "average", "sum", "count", "min", "max" ], "default": "sum" }, { "type": "null" } ] }, "tension": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.4 }, "showPoints": { "type": "boolean", "default": true } } }, { "type": "null" } ] } }, "required": [ "id", "name", "ySelection", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "scatter" }, "options": { "anyOf": [ { "type": "object", "properties": { "showLine": { "type": "boolean", "default": false }, "pointRadius": { "type": "number", "minimum": 1, "maximum": 20, "default": 3 } } }, { "type": "null" } ] } }, "required": [ "id", "name", "ySelection", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "area" }, "options": { "anyOf": [ { "type": "object", "properties": { "aggregation": { "anyOf": [ { "type": "string", "enum": [ "average", "sum", "count", "min", "max" ], "default": "sum" }, { "type": "null" } ] }, "tension": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.4 }, "fillOpacity": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.3 } } }, { "type": "null" } ] } }, "required": [ "id", "name", "ySelection", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "default": [] }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "histogram" }, "options": { "anyOf": [ { "type": "object", "properties": { "bins": { "type": "number", "minimum": 5, "maximum": 100, "default": 20 } } }, { "type": "null" } ] } }, "required": [ "id", "name", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "default": [] }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "pie" }, "options": { "anyOf": [ { "type": "object", "properties": { "aggregation": { "default": "sum", "type": "string", "enum": [ "average", "sum", "count", "min", "max" ] } } }, { "type": "null" } ] } }, "required": [ "id", "name", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "default": [] }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "doughnut" }, "options": { "anyOf": [ { "type": "object", "properties": { "aggregation": { "default": "sum", "type": "string", "enum": [ "average", "sum", "count", "min", "max" ] } } }, { "type": "null" } ] } }, "required": [ "id", "name", "chartType" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "ySelection": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "yAxisPosition": { "type": "string", "enum": [ "left", "right" ], "default": "left" }, "color": { "type": [ "string", "null" ] }, "visible": { "type": "boolean", "default": true }, "chartType": { "type": "string", "const": "sankey" } }, "required": [ "id", "name", "ySelection", "chartType" ] } ], "discriminator": { "propertyName": "chartType" } } }, "config": { "type": "object", "properties": { "responsive": { "type": "boolean", "default": true }, "chartTitle": { "type": [ "string", "null" ] }, "dataPoints": { "type": "number", "default": -1 }, "dataDisplayOrder": { "type": "string", "enum": [ "fromStart", "fromEnd" ], "default": "fromStart" }, "sortBy": { "anyOf": [ { "type": "string", "enum": [ "none", "x", "y" ] }, { "type": "null" } ] }, "sortType": { "anyOf": [ { "type": "string", "enum": [ "ascending", "descending", "natural" ] }, { "type": "null" } ] }, "advancedSettings": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] } } } }, "required": [ "id", "xSelection", "traces", "config" ] }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "table" }, "title": { "type": [ "string", "null" ] }, "columns": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "totalRows": { "type": "number" }, "csvExport": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "sql_evidence" }, "rowCount": { "type": "integer", "minimum": 0 }, "queryTruncated": { "type": "boolean" }, "queryTotalRowCount": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "source", "rowCount", "queryTruncated" ] }, { "type": "null" } ] }, "livePaging": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "anchor_sql" }, "sql": { "type": "string" }, "projectionMode": { "type": "string", "enum": [ "related", "minimal" ], "default": "related" } }, "required": [ "source", "sql" ] }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "columns", "rows", "totalRows" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "data_preview" }, "datasetId": { "type": "string" } }, "required": [ "id", "evidenceId", "type", "datasetId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "data_view_preview" }, "dataViewId": { "type": "string" } }, "required": [ "id", "evidenceId", "type", "dataViewId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "kpi_card" }, "title": { "type": "string" }, "value": { "type": [ "string", "number" ] }, "dataBinding": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "sourceType": { "type": "string", "const": "dataset" }, "datasetId": { "type": "string", "minLength": 1 }, "valueField": { "type": "string", "minLength": 1 } }, "required": [ "sourceType", "datasetId", "valueField" ] }, { "type": "object", "properties": { "sourceType": { "type": "string", "const": "dataview" }, "dataViewId": { "type": "string", "minLength": 1 }, "valueField": { "type": "string", "minLength": 1 } }, "required": [ "sourceType", "dataViewId", "valueField" ] } ], "discriminator": { "propertyName": "sourceType" } }, { "type": "null" } ] }, "unit": { "type": [ "string", "null" ] }, "unitId": { "type": [ "string", "null" ] }, "change": { "type": [ "number", "null" ] }, "changePeriod": { "type": [ "string", "null" ] }, "trend": { "anyOf": [ { "type": "string", "enum": [ "up", "down", "neutral" ] }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "title", "value" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "causal_graph" }, "digitalTwinVersionId": { "type": "string" } }, "required": [ "id", "evidenceId", "type", "digitalTwinVersionId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "dataset_search_results" }, "searchQuery": { "type": "string" }, "datasetIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "evidenceId", "type", "searchQuery", "datasetIds" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "data_view_search_results" }, "searchQuery": { "type": "string" }, "dataViewIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "evidenceId", "type", "searchQuery", "dataViewIds" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "digital_twin_result" }, "digitalTwinRunId": { "type": "string" } }, "required": [ "id", "evidenceId", "type", "digitalTwinRunId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "digital_twin_search_results" }, "digitalTwinVersionIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "evidenceId", "type", "digitalTwinVersionIds" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "digital_twin_run_search_results" }, "searchQuery": { "type": "string" }, "runIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "evidenceId", "type", "searchQuery", "runIds" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "ontology_graph" }, "searchQuery": { "type": "string" }, "conceptIds": { "type": "array", "items": { "type": "string" } }, "anchorType": { "type": "string", "enum": [ "dataset", "identifier", "conceptType" ], "default": "dataset" }, "showFullGraph": { "type": "boolean", "default": false } }, "required": [ "id", "evidenceId", "type", "searchQuery", "conceptIds" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "path_analysis_sankey" }, "digitalTwinVersionId": { "type": "string" }, "selectedNode": { "type": [ "string", "null" ] }, "selectedEdge": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" } }, "required": [ "source", "target" ] }, { "type": "null" } ] }, "depthLimit": { "type": "number", "default": 2 } }, "required": [ "id", "evidenceId", "type", "digitalTwinVersionId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "parameter_distribution" }, "digitalTwinVersionId": { "type": "string" }, "selectedNode": { "type": [ "string", "null" ] }, "selectedEdge": { "anyOf": [ { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" } }, "required": [ "source", "target" ] }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "digitalTwinVersionId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "causal_diff" }, "version1Id": { "type": "string" }, "version2Id": { "type": "string" } }, "required": [ "id", "evidenceId", "type", "version1Id", "version2Id" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "dose_response" }, "causeVariable": { "type": "string" }, "sweptMode": { "anyOf": [ { "type": "string", "enum": [ "absolute", "percentage" ] }, { "type": "null" } ] }, "metric": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "properties": { "causeValue": { "type": "number" }, "effect": { "type": "number" }, "ciLower": { "type": [ "number", "null" ] }, "ciUpper": { "type": [ "number", "null" ] } }, "required": [ "causeValue", "effect" ] } }, "referenceValue": { "type": [ "number", "null" ] }, "isLinear": { "type": [ "boolean", "null" ] }, "inflectionPoints": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ] }, "digitalTwinRunId": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type", "causeVariable", "metric", "points" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "page_context" }, "section": { "anyOf": [ { "type": "string", "enum": [ "Organisation Home", "Workspace Home", "Dataset Selection", "Dataset Page", "Data View Selection", "Data View Page", "Digital Twin Selection", "Digital Twin Page", "Report Selection", "Report Page", "Settings" ] }, { "type": "null" } ] }, "summary": { "type": "string" }, "entityName": { "type": [ "string", "null" ] }, "entityType": { "anyOf": [ { "type": "string", "enum": [ "dataset", "data_view", "digital_twin", "report" ] }, { "type": "null" } ] }, "itemCount": { "type": [ "number", "null" ] } }, "required": [ "id", "evidenceId", "type", "summary" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "dag_review" }, "digitalTwinVersionId": { "type": "string" }, "digitalTwinName": { "type": "string" }, "nodeCount": { "type": "number" }, "edgeCount": { "type": "number" }, "overallHealth": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "description": { "type": "string" }, "severity": { "type": "string", "enum": [ "high", "medium", "low" ] }, "suggestedFix": { "type": [ "string", "null" ] }, "affectedNodes": { "type": "array", "items": { "type": "string" }, "default": [] }, "affectedEdges": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" } }, "required": [ "source", "target" ] }, "default": [] } }, "required": [ "type", "description", "severity" ] }, "default": [] }, "recommendations": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "id", "evidenceId", "type", "digitalTwinVersionId", "digitalTwinName", "nodeCount", "edgeCount", "overallHealth" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "causal_context" }, "outcomeVariable": { "type": "string" }, "relatedConcepts": { "type": "array", "items": { "type": "object", "properties": { "concept": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "sourceName": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] }, "isIdentifier": { "type": "boolean", "default": false } }, "required": [ "concept" ] }, "default": [] }, "datasetSourceCount": { "type": "number", "default": 0 }, "recommendation": { "type": [ "string", "null" ] }, "existingDataViewId": { "type": [ "string", "null" ] }, "existingDataViewName": { "type": [ "string", "null" ] }, "existingDigitalTwinId": { "type": [ "string", "null" ] }, "existingDigitalTwinName": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type", "outcomeVariable" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "graph_query_result" }, "queryType": { "type": "string" }, "digitalTwinVersionId": { "type": "string" }, "queriedNode": { "type": [ "string", "null" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "node": { "type": "string" }, "edgeLabel": { "type": [ "string", "null" ] }, "strength": { "type": [ "number", "null" ] }, "depth": { "type": [ "number", "null" ] }, "type": { "type": [ "string", "null" ] } }, "required": [ "node" ] }, "default": [] }, "path": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "queryType", "digitalTwinVersionId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "ontology_data" }, "columns": { "type": "array", "items": { "type": "string" }, "default": [] }, "rowCount": { "type": "number", "default": 0 }, "sampleRows": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "default": [] }, "dataViewId": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "ontology_mutation_preview" }, "operations": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "default": [] }, "successCount": { "type": "number", "default": 0 }, "failureCount": { "type": "number", "default": 0 }, "affectedConceptIds": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "docs_sources" }, "documentReferences": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "path": { "type": "string" }, "pageId": { "type": [ "string", "null" ] } }, "required": [ "title", "path" ] } } }, "required": [ "id", "evidenceId", "type", "documentReferences" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "background_runs" }, "runs": { "type": "array", "items": { "type": "object", "properties": { "runId": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "entityId": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "percentage": { "type": [ "number", "null" ] }, "label": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "runId", "name", "domain", "status" ] } } }, "required": [ "id", "evidenceId", "type", "runs" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "environment_segments" }, "title": { "type": "string" }, "silhouetteScore": { "type": [ "number", "null" ] }, "segments": { "type": "array", "items": { "type": "object", "properties": { "segment": { "type": "number" }, "label": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "environments": { "type": "array", "items": { "type": "string" } } }, "required": [ "segment", "label", "environments" ] } }, "points": { "type": "array", "items": { "type": "object", "properties": { "envKey": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "segment": { "type": "number" } }, "required": [ "envKey", "x", "y", "segment" ] } } }, "required": [ "id", "evidenceId", "type", "title", "segments", "points" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "environment_comparison" }, "title": { "type": "string" }, "sliceLabel": { "type": "string" }, "baselineLabel": { "type": "string" }, "sliceEnvCount": { "type": "number" }, "baselineEnvCount": { "type": "number" }, "edges": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "target": { "type": "string" }, "sliceAgreement": { "type": "number" }, "baselineAgreement": { "type": "number" }, "sliceStrength": { "type": [ "number", "null" ] }, "baselineStrength": { "type": [ "number", "null" ] }, "verdict": { "type": "string", "enum": [ "slice-only", "missing-from-slice", "differs", "consistent" ] } }, "required": [ "source", "target", "sliceAgreement", "baselineAgreement", "verdict" ] } } }, "required": [ "id", "evidenceId", "type", "title", "sliceLabel", "baselineLabel", "sliceEnvCount", "baselineEnvCount", "edges" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "environment_coverage" }, "title": { "type": "string" }, "environments": { "type": "array", "items": { "type": "object", "properties": { "envKey": { "type": "string" }, "trainingRows": { "type": [ "number", "null" ] }, "variablesTrained": { "type": [ "number", "null" ] }, "variablesTotal": { "type": [ "number", "null" ] }, "missing": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "name" ] } }, "evaluation": { "type": [ "string", "null" ] } }, "required": [ "envKey", "missing" ] } } }, "required": [ "id", "evidenceId", "type", "title", "environments" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "clarification" }, "toolCallId": { "type": "string" }, "mode": { "type": "string", "enum": [ "multiple_choice", "form" ] }, "question": { "type": "string" }, "why": { "type": [ "string", "null" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" }, "preview": { "type": [ "string", "null" ] } }, "required": [ "label", "value" ] }, "default": [] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "number", "string", "select", "multiselect", "boolean", "source", "dataset", "digitalTwin", "ontologyConcept" ], "default": "string" }, "default": { "anyOf": [ {}, { "type": "null" } ] }, "options": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value" ] } ] } }, { "type": "null" } ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "step": { "type": [ "number", "null" ] }, "pattern": { "type": [ "string", "null" ] }, "control": { "type": [ "string", "null" ] }, "placeholder": { "type": [ "string", "null" ] }, "help": { "type": [ "string", "null" ] }, "required": { "type": [ "boolean", "null" ] }, "secret": { "type": [ "boolean", "null" ] }, "urlParam": { "type": [ "string", "null" ] } }, "required": [ "id" ] }, "default": [] }, "selectedValues": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "selectedFieldValues": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "toolCallId", "mode", "question" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "action_confirmation" }, "toolCallId": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "severity": { "type": "string", "enum": [ "mutates_truth", "long_running", "irreversible" ] }, "actionLabel": { "type": "string" }, "estimatedDuration": { "type": [ "string", "null" ] }, "changes": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "before": { "type": [ "string", "null" ] }, "after": { "type": [ "string", "null" ] } }, "required": [ "label" ] } }, { "type": "null" } ] }, "details": { "type": [ "string", "null" ] }, "editableKind": { "anyOf": [ { "type": "string", "enum": [ "extraction_schema" ] }, { "type": "null" } ] }, "editableInputs": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "toolName": { "type": [ "string", "null" ] }, "toolInputs": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "toolCallId", "title", "summary", "severity", "actionLabel" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "navigation" }, "commandId": { "type": "string" }, "label": { "type": "string" }, "subtitle": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "navigate", "create", "action" ], "default": "navigate" }, "entity": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dataset", "dataview", "concept", "digitalTwin", "report", "digitalTwinRun" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "type", "id", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "commandId", "label" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "foundational_ontology_install" }, "ontologyId": { "type": "string" }, "version": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "trustTier": { "type": "string" }, "anchorsSummary": { "type": [ "string", "null" ] }, "conceptCount": { "type": "number" }, "sourceCount": { "type": "number" }, "suggestedScopeNote": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type", "ontologyId", "version", "name", "trustTier", "conceptCount", "sourceCount" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "stat_grid" }, "title": { "type": [ "string", "null" ] }, "stats": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "value": { "type": [ "string", "number" ] }, "unit": { "type": [ "string", "null" ] }, "unitId": { "type": [ "string", "null" ] }, "decimals": { "type": [ "number", "null" ] }, "change": { "type": [ "number", "null" ] }, "changePeriod": { "type": [ "string", "null" ] }, "trend": { "anyOf": [ { "type": "string", "enum": [ "up", "down", "neutral" ] }, { "type": "null" } ] } }, "required": [ "title", "value" ] } }, "gridCols": { "anyOf": [ { "type": "number", "enum": [ 2, 3, 4 ] }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "stats" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "markdown" }, "content": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "heading" }, "text": { "type": [ "string", "null" ] }, "eyebrow": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "divider" }, "style": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "image" }, "src": { "type": [ "string", "null" ] }, "alt": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "iframe" }, "url": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "application" }, "applicationId": { "type": "string" }, "runId": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "moduleCount": { "type": [ "number", "null" ] }, "publicUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "evidenceId", "type", "applicationId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "report" }, "reportId": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "rev": { "type": [ "number", "null" ] } }, "required": [ "id", "evidenceId", "type", "reportId" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "evidenceId": { "type": "string" }, "type": { "type": "string", "const": "lineage" }, "lineageId": { "type": "string" }, "tool": { "type": "string", "default": "" }, "hops": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string", "default": "" } }, "required": [ "kind", "id" ] }, "status": { "type": "string", "enum": [ "resolved", "denied", "deleted" ] }, "parents": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string", "default": "" } }, "required": [ "kind", "id" ] }, "default": [] }, "pin": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "versionId": { "type": [ "string", "null" ] }, "ordinal": { "type": [ "number", "null" ] }, "deltaVersion": { "type": [ "number", "null" ] }, "label": { "type": [ "string", "null" ] } }, "required": [ "kind", "id" ] }, { "type": "null" } ] }, "detail": { "type": "object", "additionalProperties": {}, "default": {} } }, "required": [ "ref", "status" ] }, "default": [] }, "reading": { "anyOf": [ { "type": "object", "properties": { "value": { "type": [ "number", "null" ] }, "valueType": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "display": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "request": { "anyOf": [ { "type": "object", "properties": { "sql": { "type": [ "string", "null" ] }, "query": { "type": [ "string", "null" ] } } }, { "type": "null" } ] } }, "required": [ "id", "evidenceId", "type", "lineageId" ] } ], "discriminator": { "propertyName": "type" } } }, "evidenceIds": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "status": { "$ref": "#/components/schemas/ReportStatusSchema" }, "rev": { "type": "integer" }, "error": { "type": [ "string", "null" ] }, "prompt": { "type": [ "string", "null" ] }, "publish": { "anyOf": [ { "$ref": "#/components/schemas/reportPublishSchema" }, { "type": "null" } ] } }, "required": [ "workspaceId", "organisationId", "title", "markdown", "widgets", "evidenceIds", "createdAt", "updatedAt" ] }, "Source": { "type": "object", "properties": { "id": { "type": "string" }, "workspaceId": { "type": [ "string", "null" ] }, "organisationId": { "type": "string" }, "name": { "type": "string" }, "parentSourceId": { "type": [ "string", "null" ] }, "dataSource": { "anyOf": [ { "$ref": "#/components/schemas/DataSourceTypeEnum" }, { "type": "null" } ] }, "dataFormat": { "$ref": "#/components/schemas/datasetFormatsEnum" }, "description": { "type": [ "string", "null" ] }, "maintainedBy": { "type": "array", "items": { "type": "object", "properties": { "applicationId": { "type": "string" }, "version": { "type": "string" }, "flowId": { "type": "string" } }, "required": [ "applicationId", "version", "flowId" ] } }, "richDescription": { "anyOf": [ { "$ref": "#/components/schemas/RichDescriptionSchema" }, { "type": "null" } ] }, "schemaEntries": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/SchemaEntryModelSchema" } }, { "type": "null" } ] }, "importWarnings": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "ontologyMode": { "$ref": "#/components/schemas/OntologyModeEnum", "default": "auto" }, "documentCount": { "type": [ "number", "null" ] }, "columnMetadata": { "anyOf": [ { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ColumnMetadataSchema" } }, { "type": "null" } ] }, "extension": { "type": [ "string", "null" ] }, "totalSize": { "type": [ "number", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "lastSaved": { "type": [ "string", "null" ] }, "virtual": { "type": [ "boolean", "null" ] }, "ontologyStatus": { "anyOf": [ { "$ref": "#/components/schemas/OntologyStatusEnum" }, { "type": "null" } ] }, "ontologyError": { "type": [ "string", "null" ] }, "extractionStatus": { "anyOf": [ { "$ref": "#/components/schemas/ExtractionStatusEnum" }, { "type": "null" } ] }, "extractionError": { "type": [ "string", "null" ] }, "pageCount": { "type": [ "number", "null" ] }, "derivedFromDatasetIds": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "derivedVia": { "anyOf": [ { "$ref": "#/components/schemas/DerivedViaEnum" }, { "type": "null" } ] }, "extractionRecipe": { "anyOf": [ { "$ref": "#/components/schemas/ExtractionRecipeSchema" }, { "type": "null" } ] }, "pendingAnnotationCount": { "type": [ "number", "null" ] }, "ontologyExcludedFields": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string", "enum": [ "auto", "user", "suggestion" ] } }, "required": [ "field", "reason", "source" ] } }, { "type": "null" } ] }, "batchRanges": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "hash": { "type": "string" }, "fileName": { "type": "string" }, "uploadedAt": { "type": "string" }, "rowStart": { "type": "number" }, "rowEnd": { "type": "number" } }, "required": [ "hash", "fileName", "uploadedAt", "rowStart", "rowEnd" ] } }, { "type": "null" } ] }, "currentVersionId": { "type": [ "string", "null" ] }, "latestVersionOrdinal": { "type": [ "number", "null" ] }, "staging": { "type": [ "boolean", "null" ] }, "readMode": { "type": "string", "enum": [ "direct_query", "snapshot" ], "description": "How this source is read. direct_query runs every read against the origin database — live, but subject to its statement timeout, and no row count is recorded; snapshot reads a stored copy, which changes only when it is synced" }, "directQuery": { "anyOf": [ { "$ref": "#/components/schemas/directQuerySettingsSchema" }, { "type": "null" } ], "description": "How a direct_query source is read. Null on a snapshot source, where none of it applies. The relation itself is not reported: on a storage source it is resolved against the bucket inside the connector's encrypted credentials, which the connector routes strip" } }, "required": [ "id", "organisationId", "name", "dataFormat", "readMode", "directQuery" ] }, "Workspace": { "type": "object", "properties": { "id": { "type": "string" }, "organisationId": { "type": "string" }, "name": { "type": "string" }, "createdAt": { "type": "string" }, "isOrgLibrary": { "type": "boolean" } }, "required": [ "organisationId", "name", "createdAt" ] } }, "responses": { "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "https://platform.rootcause.ai/errors/bad-request" ] }, "title": { "type": "string", "examples": [ "Bad Request" ] }, "status": { "type": "integer", "examples": [ "400" ] }, "detail": { "type": "string", "examples": [ "The request body or parameters failed validation" ] }, "instance": { "type": "string" } }, "required": [ "type", "title", "status", "detail" ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "https://platform.rootcause.ai/errors/unauthorized" ] }, "title": { "type": "string", "examples": [ "Unauthorized" ] }, "status": { "type": "integer", "examples": [ "401" ] }, "detail": { "type": "string", "examples": [ "Missing or invalid API key" ] }, "instance": { "type": "string" } }, "required": [ "type", "title", "status", "detail" ] } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "https://platform.rootcause.ai/errors/forbidden" ] }, "title": { "type": "string", "examples": [ "Insufficient Permissions" ] }, "status": { "type": "integer", "examples": [ "403" ] }, "detail": { "type": "string", "examples": [ "The credential lacks the scope or permission this call requires" ] }, "instance": { "type": "string" } }, "required": [ "type", "title", "status", "detail" ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "https://platform.rootcause.ai/errors/not-found" ] }, "title": { "type": "string", "examples": [ "Not Found" ] }, "status": { "type": "integer", "examples": [ "404" ] }, "detail": { "type": "string", "examples": [ "No such resource in this organisation" ] }, "instance": { "type": "string" } }, "required": [ "type", "title", "status", "detail" ] } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "https://platform.rootcause.ai/errors/conflict" ] }, "title": { "type": "string", "examples": [ "Conflict" ] }, "status": { "type": "integer", "examples": [ "409" ] }, "detail": { "type": "string", "examples": [ "The request conflicts with the current state of the resource" ] }, "instance": { "type": "string" } }, "required": [ "type", "title", "status", "detail" ] } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "https://platform.rootcause.ai/errors/validation-error" ] }, "title": { "type": "string", "examples": [ "Validation Error" ] }, "status": { "type": "integer", "examples": [ "422" ] }, "detail": { "type": "string", "examples": [ "The body parsed as JSON but failed schema validation" ] }, "instance": { "type": "string" } }, "required": [ "type", "title", "status", "detail" ] } } } }, "429": { "description": "Too Many Requests; the response carries Retry-After", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "https://platform.rootcause.ai/errors/rate-limit-exceeded" ] }, "title": { "type": "string", "examples": [ "Rate Limit Exceeded" ] }, "status": { "type": "integer", "examples": [ "429" ] }, "detail": { "type": "string", "examples": [ "The key's per-minute rate limit is exhausted; retry after the interval in Retry-After" ] }, "instance": { "type": "string" } }, "required": [ "type", "title", "status", "detail" ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "examples": [ "https://platform.rootcause.ai/errors/internal-error" ] }, "title": { "type": "string", "examples": [ "Internal Server Error" ] }, "status": { "type": "integer", "examples": [ "500" ] }, "detail": { "type": "string", "examples": [ "An unexpected error occurred" ] }, "instance": { "type": "string" } }, "required": [ "type", "title", "status", "detail" ] } } } } } }, "paths": { "/api/v1/workspaces/{wsId}/applications": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-applications", "summary": "List applications", "description": "Lists the applications in the workspace. Paginated (limit, cursor). Deployed copies of an application are not listed; only the applications themselves. The builder graph, trigger and type configuration are not part of the public shape.", "tags": [ "Applications" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationListEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/applications/{id}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-applications-{id}", "summary": "Get application", "description": "Returns the application by id from platform MongoDB. Must belong to the workspace; deployed copies are not addressable. The builder graph, trigger and type configuration are not part of the public shape.", "tags": [ "Applications" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-api-v1-workspaces-{wsId}-applications-{id}", "summary": "Delete application", "description": "Deletes the application, its module data and any deployed copies of it. Deployed copies are not deletable on their own. This is the same deletion the workspace UI performs. Requires applications:delete and full permission.", "tags": [ "Applications" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/catalog/concepts": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-catalog-concepts", "summary": "List catalog concepts", "description": "Returns ontology concepts for the workspace in catalog shape: id, name, description, schemaFieldName, schemaType, classification, fieldMappings (tableId, field), metadata, etc. Optional query param sourceId filters to concepts that have a field mapping for that source. Paginated (limit, default 200; cursor).", "tags": [ "Catalog" ], "parameters": [ { "in": "query", "name": "sourceId", "required": false, "schema": { "type": "string", "description": "Restrict to concepts mapped to this source." }, "description": "Restrict to concepts mapped to this source.", "example": "123" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/catalog/graph": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-catalog-graph", "summary": "Get catalog knowledge graph", "description": "Returns the ontology as a graph: nodes are concepts (id, name, schemaType, classification, suggestedRole); edges are anchor links (type \"anchor\") and temporal prerequisites (type \"temporal_prerequisite\"). Built from workspace concepts in platform MongoDB; no proxy.", "tags": [ "Catalog" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/catalog/tables": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-catalog-tables", "summary": "List catalog tables", "description": "Returns tabular sources in the workspace as catalog \"tables\": id, name, namespace (workspaceId), schema (field, type, subtype, description), documentCount, format, createdAt. Only dataFormat Tabular; virtual and folder-only are excluded. Paginated (limit, default 200; cursor). Used by semantic catalog and MCP.", "tags": [ "Catalog" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/catalog/views": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-catalog-views", "summary": "List catalog views", "description": "Returns datasets in the workspace as catalog \"views\": id, name, description, namespace, sources, operationCount, rowCount, timestamps. Read from platform MongoDB (integration views). Paginated (limit, default 200; cursor). Used by semantic catalog and MCP.", "tags": [ "Catalog" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/connectors": { "get": { "operationId": "get-api-v1-connectors", "summary": "List connectors", "description": "Returns all data connectors for the organisation. Credentials are never returned; only metadata (name, type, status, etc.). Results are filtered by organisationId from the auth context.", "tags": [ "Connectors" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorListEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-api-v1-connectors", "summary": "Create connector", "description": "Creates a new connector with name, type, and optional credentials. Stored in platform MongoDB; credentials are encrypted at rest. Connector starts in status \"unconfigured\" until used with browse/import/test.", "tags": [ "Connectors" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectorInput" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/connectors/{id}": { "get": { "operationId": "get-api-v1-connectors-{id}", "summary": "Get connector", "description": "Returns a single connector by id. Credentials are stripped from the response. 404 if not in this organisation.", "tags": [ "Connectors" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "patch": { "operationId": "patch-api-v1-connectors-{id}", "summary": "Update connector", "description": "Updates connector name and/or credentials. Other fields (type, status) are managed by the system. updatedAt is set automatically.", "tags": [ "Connectors" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConnectorInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-api-v1-connectors-{id}", "summary": "Delete connector", "description": "Permanently deletes the connector. Requires full permission. Does not delete sources or jobs created from prior imports.", "tags": [ "Connectors" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/connectors/{id}/browse": { "get": { "operationId": "get-api-v1-connectors-{id}-browse", "summary": "Browse connector resources", "description": "Returns the browse options at one level of the connector's hierarchy (e.g. databases, then tables, then columns). Pass the current level via `level` and the selected ancestors as additional query parameters (e.g. `?level=tables&database=sales`, then `?level=columns&database=sales&table=orders`; PostgreSQL uses `schema` instead of `database`). Any query parameter other than `level` and `search` is forwarded as browse context. Connector must exist and belong to the organisation.", "tags": [ "Connectors" ], "parameters": [ { "in": "query", "name": "level", "required": true, "schema": { "type": "string", "enum": [ "warehouses", "databases", "schemas", "tables", "columns", "containers", "buckets", "folders", "files", "collections" ], "description": "Hierarchy level to list, from the connector's browse hierarchy." }, "description": "Hierarchy level to list, from the connector's browse hierarchy.", "example": "warehouses" }, { "in": "query", "name": "search", "required": false, "schema": { "type": "string", "description": "Case-insensitive filter on option values/labels." }, "description": "Case-insensitive filter on option values/labels.", "example": "example" }, { "in": "query", "name": "database", "required": false, "schema": { "type": "string", "description": "Browse context: parent database (MySQL/ClickHouse/Snowflake)." }, "description": "Browse context: parent database (MySQL/ClickHouse/Snowflake).", "example": "example" }, { "in": "query", "name": "schema", "required": false, "schema": { "type": "string", "description": "Browse context: parent schema (PostgreSQL/Snowflake)." }, "description": "Browse context: parent schema (PostgreSQL/Snowflake).", "example": "example" }, { "in": "query", "name": "table", "required": false, "schema": { "type": "string", "description": "Browse context: parent table, for level=columns." }, "description": "Browse context: parent table, for level=columns.", "example": "example" }, { "in": "query", "name": "warehouse", "required": false, "schema": { "type": "string", "description": "Browse context: warehouse (Snowflake)." }, "description": "Browse context: warehouse (Snowflake).", "example": "example" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/connectors/{id}/direct-query": { "post": { "operationId": "post-api-v1-connectors-{id}-direct-query", "summary": "Create a directly-queried source", "description": "Creates a source that reads the connector at query time instead of importing a copy of it — the API equivalent of the platform's direct-query (federated) option. Nothing is ingested and no pipeline runs: the schema is probed from the remote catalogue and the source is created synchronously, so this returns 201 with the source rather than a job to poll. Supported on PostgreSQL, MySQL, Snowflake, ClickHouse, S3, Google Cloud Storage and Azure Data Lake; every other connector must be imported. Body: optional workspaceId (required only for an organisation-wide credential; a workspace-scoped one supplies it), datasetName, config (the connector-specific selection: {table} or {query} plus database/schema/warehouse for SQL connectors, {path} for storage — connectorId and type are filled in from the route), orderingColumn, and optional relation, appendOnly, statementTimeoutSeconds, maxRowsScanned and parentId. A SQL source may name a table or a hand-written query, never both: the query is probed as a derived table, so a pivot, a join or an aggregate is a direct-query source in its own right and orderingColumn must name a column it returns. A directly-queried source cannot also be on a sync schedule, and cannot be narrowed by a data selection — filter it in the workspace instead. Ontology analysis is queued in the background; poll the source until its schema is annotated. Storage connectors are read in place as Parquet, so maxRowsScanned, a recursive read and any format other than parquet are refused rather than ignored.", "tags": [ "Connectors" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorDirectQueryInput" } } } }, "responses": { "201": { "description": "Created; the source is queryable immediately", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectQuerySourceEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/connectors/{id}/import": { "post": { "operationId": "post-api-v1-connectors-{id}-import", "summary": "Import data from connector", "description": "Starts an import job from the connector into a workspace. Body: optional workspaceId (required only for an organisation-wide credential; a workspace-scoped one supplies it), config (the connector-specific selection: {table} or a custom {query} for SQL connectors like Snowflake/PostgreSQL/MySQL/ClickHouse, {path} for storage, {object, fields} for CRM connectors — connectorId and type are filled in from the route), optional datasetName, ontologyMode (auto | manual, default auto), and webhookUrl for a completion callback. Returns 202 with jobId and links.self; import runs asynchronously — poll the linked job, or sources, to track progress. The job id is the pipeline run the data service started, so it always resolves; a response carrying no run id is a 500 rather than a 202 you cannot poll. Use preview-query to validate custom SQL before importing.", "tags": [ "Connectors" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorImportInput" } } } }, "responses": { "202": { "description": "Accepted; poll the linked resource for completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobAccepted" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/connectors/{id}/preview-query": { "post": { "operationId": "post-api-v1-connectors-{id}-preview-query", "summary": "Preview a connector dataset", "description": "Reads the first rows of a connector dataset and returns them, or the underlying error verbatim — what to call before committing to a full import. Point it at a browsed dataset ({table} plus database/schema/warehouse for SQL connectors, {database, collection} for MongoDB, {path} for storage), or pass {query} to preview custom SQL instead; connectorId and type are filled in from the route. Optional limit defaults to 50 and is capped at 1000. Storage previews read only the head of the object, so previewing a large file is cheap. Read-only against the external system; nothing is stored.", "tags": [ "Connectors" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewQueryInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/connectors/{id}/test": { "post": { "operationId": "post-api-v1-connectors-{id}-test", "summary": "Test connector connection", "description": "Proxies to data-service integrations test. Validates that the connector's credentials and configuration can reach the external source. Does not modify data. Use before import to avoid failed jobs.", "tags": [ "Connectors" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/datasets": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-datasets", "summary": "List datasets", "description": "Lists datasets for the workspace with current ontology conceptVersions on every source. Paginated (limit, cursor).", "tags": [ "Datasets" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-api-v1-workspaces-{wsId}-datasets", "summary": "Create dataset", "description": "Creates a new dataset — a derived, queryable table over one or more sources. Body: name, sources, operations, optional description, tags, anchorConceptId. Every non-empty source must include conceptVersions with exactly one entry per conceptId, copied from a current GET or recommendation response; stale versions return a conflict. Returns the created dataset document.", "tags": [ "Datasets" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetInput" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/datasets/{id}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-datasets-{id}", "summary": "Get dataset", "description": "Returns the dataset by id with current ontology conceptVersions on every source. Must belong to the workspace.", "tags": [ "Datasets" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "patch": { "operationId": "patch-api-v1-workspaces-{wsId}-datasets-{id}", "summary": "Update dataset", "description": "Updates name, description, tags, sources, operations, anchorConceptId. A sources update must round-trip conceptVersions from a current GET and include exactly one version per conceptId; stale versions return a conflict. Changing sources/operations may change schema and row count.", "tags": [ "Datasets" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDataViewSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-api-v1-workspaces-{wsId}-datasets-{id}", "summary": "Delete dataset", "description": "Deletes the dataset. Its sources are left intact. Requires full permission.", "tags": [ "Datasets" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/datasets/recommended": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-datasets-recommended", "summary": "Get recommended datasets", "description": "Returns recommended dataset definitions for the workspace (e.g. based on ontology or usage). Used to suggest datasets to create.", "tags": [ "Datasets" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/datasets/{id}/enriched": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-datasets-{id}-enriched", "summary": "Get enriched dataset", "description": "Returns the dataset with enriched metadata: output schema, column metadata, row count, concept metadata, operation details. Use when you need full schema and stats without fetching records.", "tags": [ "Datasets" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/datasets/{id}/metadata": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-datasets-{id}-metadata", "summary": "Get dataset metadata", "description": "Returns schema entries, column metadata, and row count for the dataset in one call. More efficient than fetching schema and records separately when you only need structure and count.", "tags": [ "Datasets" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/datasets/{id}/records": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-datasets-{id}-records", "summary": "Get dataset records", "description": "Returns paginated rows from the dataset. Query params: limit (default 50, max 1000), cursor (opaque, from the previous response's pagination.cursor). Data is computed on demand from sources and operations; no materialisation.", "tags": [ "Datasets" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/datasets/{id}/schema": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-datasets-{id}-schema", "summary": "Get dataset schema", "description": "Returns the output schema (list of schema entries) for the dataset. Reflects the result of applying all operations to the sources.", "tags": [ "Datasets" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/datasets/{id}/validate": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-datasets-{id}-validate", "summary": "Validate an operations chain", "description": "Validates an operations chain without persisting anything — a schema dry-run. Body: sources, operations (same shape as a dataset). Returns sourceSchemas, operationSchemas (schema after each step), finalSchema, and the enriched dataset preview. Use to check schema and metadata before creating or updating a dataset.", "tags": [ "Datasets" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/datasets/{id}/export/{format}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-datasets-{id}-export-{format}", "summary": "Export dataset", "description": "Streams the dataset result as a file. Path param format: csv, json, or parquet. Response is streaming with appropriate Content-Type and Content-Disposition. Requires exports:read scope.", "tags": [ "Datasets" ], "parameters": [ { "in": "path", "name": "format", "required": true, "schema": { "type": "string", "enum": [ "csv", "json", "parquet" ], "description": "Export format" }, "description": "Export format", "example": "csv" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins", "summary": "List digital twins", "description": "Lists digital twins in the workspace. Paginated (limit, cursor). Read from platform MongoDB. Versions are listed under /versions.", "tags": [ "Digital Twins" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalTwinListEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins", "summary": "Create digital twin", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTwinInput" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalTwinCreatedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}", "summary": "Get digital twin", "description": "Returns the digital twin by id from platform MongoDB. Must belong to the workspace. Includes canonicalInputSchema, suggestedSimulations.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalTwinEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "patch": { "operationId": "patch-api-v1-workspaces-{wsId}-digital-twins-{id}", "summary": "Update digital twin", "description": "Updates name and/or tags. Only these fields are writable. Stored in platform MongoDB. A name already held by another twin in the workspace is refused with 409 rather than silently suffixed.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTwinInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalTwinEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-api-v1-workspaces-{wsId}-digital-twins-{id}", "summary": "Delete digital twin", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/import": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-import", "summary": "Import digital twin from export zip", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "in": "query", "name": "webhookUrl", "required": false, "schema": { "type": "string", "description": "Called with the job result when the import reaches a terminal state." }, "description": "Called with the job result when the import reaches a terminal state.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "in": "header", "name": "x-filename", "required": true, "schema": { "type": "string", "description": "Filename to store the upload under" }, "description": "Filename to store the upload under", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/zip": { "schema": { "$ref": "#/components/schemas/BinaryUpload" } } } }, "responses": { "202": { "description": "Accepted; poll the linked resource for completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobAccepted" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/environment-groups": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}-environment-groups", "summary": "List environment groups", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentGroupListEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-environment-groups", "summary": "Create an environment group", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvironmentGroupInput" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentGroupEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/export": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-export", "summary": "Start digital twin export", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportTwinInput" } } } }, "responses": { "202": { "description": "Accepted; poll the linked resource for completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobAccepted" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}-versions", "summary": "List versions", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalTwinVersionListEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-versions", "summary": "Create version", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateVersionInput" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalTwinVersionEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/environment-groups/{groupId}": { "patch": { "operationId": "patch-api-v1-workspaces-{wsId}-digital-twins-{id}-environment-groups-{groupId}", "summary": "Update an environment group", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: groupId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEnvironmentGroupInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentGroupEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-api-v1-workspaces-{wsId}-digital-twins-{id}-environment-groups-{groupId}", "summary": "Delete an environment group", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "groupId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: groupId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}", "summary": "Get version", "description": "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).", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}", "summary": "Delete version", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/export/{pipelineRunId}/download": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}-export-{pipelineRunId}-download", "summary": "Download completed export", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "pipelineRunId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: pipelineRunId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/discover": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-discover", "summary": "Run causal discovery", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookBody" } } } }, "responses": { "202": { "description": "Accepted; poll the linked resource for completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobAccepted" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/environments": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-environments", "summary": "List the version's environments", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/evaluation": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-evaluation", "summary": "Get model evaluation", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/graph": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-graph", "summary": "Get causal graph", "description": "Returns the version's causal graph: relationships (edges), nodes, and fixedSubGraph (user-fixed edges/anti-edges). Read from platform MongoDB.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "put": { "operationId": "put-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-graph", "summary": "Replace causal graph", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutGraphInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/params": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-params", "summary": "Get version parameters", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/run-pipeline": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-run-pipeline", "summary": "Run full pipeline", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookBody" } } } }, "responses": { "202": { "description": "Accepted; poll the linked resource for completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobAccepted" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/sample": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-sample", "summary": "Sample raw draws from the trained model", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleTwinInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/scenario-from-query": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-scenario-from-query", "summary": "Generate scenario from natural-language query", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScenarioFromQueryInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/score": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-score", "summary": "Score rows against targets", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreRowsInput" } } } }, "responses": { "202": { "description": "Accepted; poll the linked resource for completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncRunAccepted" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/temporal-dependencies": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-temporal-dependencies", "summary": "Get temporal dependencies", "description": "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).", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "put": { "operationId": "put-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-temporal-dependencies", "summary": "Set temporal dependencies", "description": "Stores temporal dependencies in the version (platform MongoDB). Body: object as returned by GET. Used to override or persist computed dependencies.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemporalDependenciesObjectSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/train": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-train", "summary": "Train digital twin model", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookBody" } } } }, "responses": { "202": { "description": "Accepted; poll the linked resource for completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobAccepted" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/update-eligibility": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-update-eligibility", "summary": "Check whether the model can assimilate new data", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/update-model": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-update-model", "summary": "Assimilate new data into the trained model", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookBody" } } } }, "responses": { "202": { "description": "Accepted; poll the linked resource for completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobAccepted" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/variable-roles": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-variable-roles", "summary": "Get variable roles", "description": "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).", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "put": { "operationId": "put-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-variable-roles", "summary": "Set variable roles", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VariableRolesSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/environment-groups/resolve": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-environment-groups-resolve", "summary": "Resolve an environment group against a version", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveEnvironmentGroupInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedEnvironmentGroupEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/environments/resolve": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-environments-resolve", "summary": "Query environments by data statistics", "description": "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}]}}.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveEnvironmentsInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedEnvironmentGroupEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/graph/fixed": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-graph-fixed", "summary": "Get fixed subgraph", "description": "Returns the version's fixed subgraph: relationships (edges pinned as present) and antiRelationships (edges forbidden). Empty arrays when nothing is fixed.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "patch": { "operationId": "patch-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-graph-fixed", "summary": "Patch fixed subgraph", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchFixedGraphInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/digital-twins/{id}/versions/{vId}/graph/slice": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-digital-twins-{id}-versions-{vId}-graph-slice", "summary": "Aggregate the causal graph over an environment subset", "description": "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.", "tags": [ "Digital Twins" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "name": "vId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: vId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphSliceInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/jobs": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-jobs", "summary": "List pipeline jobs", "description": "Lists pipeline runs for the workspace. Proxies to data-service GET /api/internal/pipeline-runs/workspace/{wsId}. Results are paginated in-app (limit, cursor). Jobs include connector imports, digital-twin train/run-pipeline/discover, report generate, etc. Use the returned job ids to poll GET /jobs/{id} or cancel via POST /jobs/{id}/cancel.", "tags": [ "Jobs" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/jobs/{id}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-jobs-{id}", "summary": "Get job status", "description": "Returns the pipeline run by id. Proxies to data-service GET /api/internal/pipeline-runs/by-id/{id}. Use to poll status after a 202 from import, train, run-pipeline, discover, or report generate. Response shape is defined by the data-service (e.g. status, progress, result). 404 if the run does not exist in this workspace. A job whose worker died is reported as failed rather than left active.", "tags": [ "Jobs" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/jobs/{id}/cancel": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-jobs-{id}-cancel", "summary": "Cancel a running job", "description": "Cancels a running pipeline job. Requires the jobs:cancel scope — jobs:read alone no longer authorizes a cancel. Proxies to data-service POST /api/pipeline-runs/{id}/cancel. Returns jobId, status cancelled, and sourceQueryCancelled — true when the cancel reached the source database and stopped the query itself, false when the connector has no source-side cancellation and the query ends when the connection drops, and null when the job is owned by a workflow that stops the source asynchronously, so the outcome is not known at the time of the reply. A job the data-service refuses to cancel answers with that refusal and its status, and with a readable reason rather than a generic one: 409 when the job already finished, 400 when it is not a cancellable kind of job (connector imports, syncs, replaces and extends are; document extractions are not), 400 when it has no running work associated with it. 404 if the run does not exist in this workspace.", "tags": [ "Jobs" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/mcp": { "get": { "operationId": "get-api-v1-mcp", "summary": "MCP SSE stream (org-level)", "description": "Server-sent events stream that delivers a single event with the POST endpoint URI so clients can discover where to send MCP requests.", "tags": [ "MCP" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "text/event-stream": { "x-oai-itemSchema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-api-v1-mcp", "summary": "MCP Streamable HTTP endpoint (org-level)", "description": "Org-level Model Context Protocol endpoint. Accepts a JSON-RPC 2.0 request body and negotiates protocol version from the client's initialize params or the MCP-Protocol-Version header; supported revisions are 2025-11-25, 2025-06-18 and 2025-03-26 (JSON-RPC batching is honoured only on 2025-03-26, which is the one revision that permitted it). A request carrying modern per-request _meta (2026-07-28 and later) is answered with UnsupportedProtocolVersion (-32022) listing what is supported. Capabilities: tools, resources, prompts. Prompts are the platform skills, so they surface as slash commands in MCP clients. tools/list is filtered to the tools the presented credential's scopes permit, and destructive or long-running tools require an explicit confirm: true argument before they run. Session scoped to the organisation (Mcp-Session-Id: org-{orgId}).", "tags": [ "MCP" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/ontology/concepts": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-ontology-concepts", "summary": "List ontology concepts", "description": "Lists ontology concepts for the workspace. Paginated (limit, cursor). Optional query param sourceId filters to concepts that have a field mapping for that source. Read from platform MongoDB (ontologyConcepts collection). Concepts are created by ontology extraction on sources or manually via POST.", "tags": [ "Ontology" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "in": "query", "name": "sourceId", "required": false, "schema": { "type": "string", "description": "Restrict to concepts mapped to this source." }, "description": "Restrict to concepts mapped to this source.", "example": "123" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OntologyConceptListEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-api-v1-workspaces-{wsId}-ontology-concepts", "summary": "Create ontology concept", "description": "Creates a new ontology concept. Body: name, schemaFieldName, schemaType, optional metadata, description, conceptClassification, fieldMappings, anchorConceptLinks, derivedInfo, suggestedRole. Stored in platform MongoDB only; no data-service call. Used for manual curation or when auto-extraction is not used.", "tags": [ "Ontology" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConceptInput" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OntologyConceptEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/ontology/graph": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-ontology-graph", "summary": "Get full ontology graph", "description": "Returns the full ontology as a graph: nodes are all workspace concepts (from platform MongoDB); edges are anchor (anchorConceptLinks) and temporal_prerequisite (temporalPrerequisites). Built in-platform from ontologyConcepts; no proxy. Same structure as catalog/graph but from the ontology API.", "tags": [ "Ontology" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/ontology/query": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-ontology-query", "summary": "Execute ontology query", "description": "Runs an Anchor SQL statement over the workspace's ontology concepts. Concepts are referenced by name and the ontology plans the joins, time alignment and location matching; SHOW/DESCRIBE metadata commands are also accepted. Always responds 200 with the result union discriminated by `ok`: rows responses carry rows, columns, units, the compiled plan, warnings and `nextStartKey` (pass back as `startKey` to fetch the next page); error responses carry the structured compile error (code, span, candidates, suggestedQuery). The materialised result is not persisted; create a dataset via POST datasets to keep it.", "tags": [ "Ontology" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OntologyQueryInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnchorSqlResponseEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/ontology/concepts/{id}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-ontology-concepts-{id}", "summary": "Get ontology concept", "description": "Returns the concept by id from platform MongoDB. Must belong to the workspace.", "tags": [ "Ontology" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OntologyConceptEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "put": { "operationId": "put-api-v1-workspaces-{wsId}-ontology-concepts-{id}", "summary": "Replace ontology concept", "description": "Replaces the concept with the provided fields. Platform loads the existing concept, merges the body, preserves the persisted editVersion when omitted, then proxies to data-service POST /api/ontology/update-concept so downstream consumers (e.g. catalog, data-service) stay in sync. Body should include _id and any fields to update.", "tags": [ "Ontology" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicConceptUpdateInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OntologyConceptEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-api-v1-workspaces-{wsId}-ontology-concepts-{id}", "summary": "Delete ontology concept", "description": "Deletes the concept from platform MongoDB only (deleteManyOntologyConcepts). Does not call data-service; any data-service copy or derived indices are not updated by this route.", "tags": [ "Ontology" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/ontology/concepts/merge": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-ontology-concepts-merge", "summary": "Merge ontology concepts", "description": "Merges one or more source concepts into a single target concept in one atomic request. Body: targetConceptId, sourceConceptIds (string array); sourceConceptId (string) is a deprecated legacy single-merge field coalesced into sourceConceptIds. Proxies to data-service POST /api/ontology/merge-concepts. Field mappings and relationships from every source are consolidated into the target; the sources are deleted. The whole batch is rejected atomically if any source is missing or fails merge validation. Returns the merged concept.", "tags": [ "Ontology" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/ontology/concepts/search": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-ontology-concepts-search", "summary": "Search ontology concepts", "description": "Searches concepts by text and filters. Query params: query (text), schemaType, classification, sourceId, limit (default 50). Proxies to data-service GET /api/ontology/search/{workspaceId}. Use for typeahead or filtered concept pickers.", "tags": [ "Ontology" ], "parameters": [ { "in": "query", "name": "query", "required": true, "schema": { "type": "string", "description": "Search text matched against concept names." }, "description": "Search text matched against concept names.", "example": "example" }, { "in": "query", "name": "limit", "required": false, "schema": { "description": "Maximum number of concepts to return.", "type": "number" }, "description": "Maximum number of concepts to return.", "example": 1 }, { "in": "query", "name": "sourceId", "required": false, "schema": { "type": "string", "description": "Restrict to concepts mapped to this source." }, "description": "Restrict to concepts mapped to this source.", "example": "123" }, { "in": "query", "name": "classification", "required": false, "schema": { "type": "string", "description": "Filter by concept classification." }, "description": "Filter by concept classification.", "example": "example" }, { "in": "query", "name": "schemaType", "required": false, "schema": { "type": "string", "description": "Filter by concept schema type." }, "description": "Filter by concept schema type.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/ontology/concepts/{id}/mappings": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-ontology-concepts-{id}-mappings", "summary": "Get concept field mappings", "description": "Returns the concept's id, name, and fieldMappings (source/table and field links). Read from platform MongoDB; no proxy. fieldMappings link this concept to columns in workspace sources.", "tags": [ "Ontology" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/ontology/concepts/{id}/relationships": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-ontology-concepts-{id}-relationships", "summary": "Get concept relationships", "description": "Returns the concept's id, name, anchorConceptLinks, and temporalPrerequisites. Read from platform MongoDB. anchorConceptLinks are concept ids this concept is anchored to; temporalPrerequisites are concept ids that must precede this one in time.", "tags": [ "Ontology" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/ontology/concepts/{id}/split": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-ontology-concepts-{id}-split", "summary": "Split ontology concept", "description": "Splits one concept by moving a single field mapping to a new concept. Body: fieldMapping (the mapping to split out). Proxies to data-service POST /api/ontology/split-concept with conceptId and fieldMapping. Returns the result from data-service (e.g. new concept and updated original).", "tags": [ "Ontology" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SplitInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/render/widget": { "post": { "operationId": "post-api-v1-render-widget", "summary": "Render a widget payload to HTML", "description": "Renders a widget payload (as emitted by agent/MCP tools or stored on reports) into a self-contained themed HTML fragment with inline styles — the same session-less renderer used across the platform's export surfaces. Suited to embedding: notebook rich display, emails, static pages. Body: widget (type plus kind-specific fields), theme (light | dark). 422 when the kind needs a live session or the payload is a bare pointer.", "tags": [ "Rendering" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderWidgetInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/reports": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-reports", "summary": "List reports", "description": "Lists reports in the workspace. Paginated (limit, cursor). Read from platform MongoDB. Reports have title, description, status (e.g. draft), markdown, widgets, evidenceIds.", "tags": [ "Reports" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportListEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-api-v1-workspaces-{wsId}-reports", "summary": "Create report", "description": "Creates a new report. Body: title, optional description. Report is created in draft status with empty markdown, widgets, and evidenceIds. Stored in platform MongoDB; content is written via PATCH or by the agent's report tools.", "tags": [ "Reports" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReportInput" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/reports/{id}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-reports-{id}", "summary": "Get report", "description": "Returns the report by id from platform MongoDB. Must belong to the workspace.", "tags": [ "Reports" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "patch": { "operationId": "patch-api-v1-workspaces-{wsId}-reports-{id}", "summary": "Update report", "description": "Updates title, description, and/or markdown. Only these fields are writable. updatedAt is set automatically. Widgets and evidence are typically managed by the UI or other flows.", "tags": [ "Reports" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReportInput" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-api-v1-workspaces-{wsId}-reports-{id}", "summary": "Delete report", "description": "Deletes the report from platform MongoDB. Requires reports:write and full permission.", "tags": [ "Reports" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/simulations": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-simulations", "summary": "List simulations", "description": "Returns the workspace's simulation runs, newest first, whether they were started via this API, the UI, or an application. Cursor-paginated; `pagination.total` is the count matching the current filters. Result payloads are omitted — use /simulations/{id}/results or /simulations/{id}/export/{format}. Each run carries `exportFormats`, decided here by model and scenario shape alone so that listing a page costs no extra reads: the formats /simulations/{id}/export/{format} accepts for it — `[\"json\", \"csv\"]` for a completed forecast-shaped run on a multi-environment (panel) model, `[\"json\"]` for any other completed run, `[]` while a run is unfinished. Single-environment models produce no panel forecast, so they never offer csv. A `csv` entry here means the run is eligible by model and scenario shape. GET /simulations/{id} confirms it against the run's stored artifacts, and the export itself returns 400 if they are gone, so read the single run before offering a csv download.", "tags": [ "Simulations" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "description": "Filter by run status." }, "description": "Filter by run status.", "example": "example" }, { "in": "query", "name": "digitalTwinId", "required": false, "schema": { "type": "string", "description": "Only return runs of this digital twin." }, "description": "Only return runs of this digital twin.", "example": "123" }, { "in": "query", "name": "scenarioType", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/ScenarioTypeEnum" } ], "description": "Filter by scenario type." }, "description": "Filter by scenario type.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-api-v1-workspaces-{wsId}-simulations", "summary": "Run simulation", "description": "Runs a digital-twin simulation with a scenario. Body: digitalTwinId, digitalTwinVersionId, scenario (key-value inputs), optional environmentGroupIds, optional webhookUrl. Proxies to data-service POST /api/digital-twin/execute-run. Returns 202 with runId and links (self, results). Simulation runs asynchronously; poll GET /simulations/{runId} for status and GET /simulations/{runId}/results for outputs when ready. Inside the scenario the field naming the family is `type`; `scenarioType` is the filter on GET /simulations and is refused here by name, as is an unknown family, so a misspelling is a 422 that says which field is wrong.", "tags": [ "Simulations" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteSimulationInput" } } } }, "responses": { "202": { "description": "Accepted; poll the linked resource for completion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncRunAccepted" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/simulations/{id}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-simulations-{id}", "summary": "Get simulation", "description": "Returns the simulation run by id. Read from platform MongoDB (digitalTwinRun collection). Must belong to the workspace. Includes status, inputs, metadata, and `exportFormats` (see the list endpoint); use /simulations/{id}/results for output data. A run submitted with `environmentGroupIds` also carries `environmentGroupSnapshots`: one entry per group ({id, name, envKeys, droppedEnvKeys, notice?}) recording the membership the server resolved at submit time. It is a frozen record, not a live read — editing or deleting the group afterwards leaves it untouched, and `droppedEnvKeys` names members the version could not honour.", "tags": [ "Simulations" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/simulations/{id}/results": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-simulations-{id}-results", "summary": "Get simulation results", "description": "Returns the simulation outputs (run.outputs) from platform MongoDB. 404 if the run has no outputs yet (e.g. still running or failed before producing results). Use after GET /simulations/{id} shows completion.", "tags": [ "Simulations" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/simulations/{id}/score": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-simulations-{id}-score", "summary": "Read scoring verdicts and per-row changes", "description": "Reads a completed batch-scoring run back: `digest` (verdict counts, top drivers, row summaries) plus one page of per-row detail with each row's full change list. Query params: limit (default 50), cursor. 409 while the run is still executing; 404 when the run carries no counterfactual results (it was not a scoring run).", "tags": [ "Simulations" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/simulations/{id}/sweep": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-simulations-{id}-sweep", "summary": "Read a sweep curve", "description": "Reads the full dose-response curve of a completed range-intervention (sweep) run, one metric per call. Query param metric selects the curve; omit it to list the available metrics plus the sweep digest. Each point carries the swept value, mean, standard deviation, and confidence interval. 409 while the run is still executing; 404 when the run carries no sweep.", "tags": [ "Simulations" ], "parameters": [ { "in": "query", "name": "metric", "required": false, "schema": { "type": "string", "description": "Which metric's curve to return; required when the run carries several." }, "description": "Which metric's curve to return; required when the run carries several.", "example": "example" }, { "in": "query", "name": "environment", "required": false, "schema": { "type": "string", "description": "Which environment's curve to return on a multi-environment (panel) run. Required there: without it the response lists the available environments instead of picking one." }, "description": "Which environment's curve to return on a multi-environment (panel) run. Required there: without it the response lists the available environments instead of picking one.", "example": "example" }, { "in": "query", "name": "environmentFilter", "required": false, "schema": { "type": "string", "description": "Narrows the environment listing on a panel run to keys containing this text." }, "description": "Narrows the environment listing on a panel run to keys containing this text.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/simulations/{id}/export/{format}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-simulations-{id}-export-{format}", "summary": "Export simulation", "description": "Downloads a completed simulation as a file. `format=json` returns a self-contained bundle (run metadata, scenario, and full outputs) and works for every scenario type. `format=csv` streams the server-side wide forecast CSV and is only available for forecast-shaped simulations (forecast, panel_forecast, prediction) that ran against a multi-environment (panel) model with parquet-backed results; anything else gets a 400 pointing at format=json. Check `exportFormats` on the run to know in advance. 400 if the run has not completed. Requires the exports:read scope.", "tags": [ "Simulations" ], "parameters": [ { "in": "path", "name": "format", "required": true, "schema": { "type": "string", "enum": [ "csv", "json", "parquet" ], "description": "Export format" }, "description": "Export format", "example": "csv" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/sources": { "get": { "operationId": "get-api-v1-sources", "summary": "List organisation sources", "description": "Lists sources across the whole organisation, including ones not linked into any workspace. Sources are org-owned; a workspace sees one only through a link, so this is where to look when a workspace appears to have no data. Query params: limit, cursor, parentId (folder id, or 'all' to flatten the tree), format, search, sortBy, sortDir. Reads platform MongoDB.", "tags": [ "Sources" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "in": "query", "name": "parentId", "required": false, "schema": { "type": "string", "description": "Only return sources derived from this source." }, "description": "Only return sources derived from this source.", "example": "123" }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string", "description": "Filter by data format." }, "description": "Filter by data format.", "example": "example" }, { "in": "query", "name": "search", "required": false, "schema": { "type": "string", "description": "Case-insensitive filter on source name." }, "description": "Case-insensitive filter on source name.", "example": "example" }, { "in": "query", "name": "sortBy", "required": false, "schema": { "type": "string", "description": "Field to sort by (default createdAt)." }, "description": "Field to sort by (default createdAt).", "example": "example" }, { "in": "query", "name": "sortDir", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction (default desc)." }, "description": "Sort direction (default desc).", "example": "asc" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceListEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/sources/{id}": { "get": { "operationId": "get-api-v1-sources-{id}", "summary": "Get organisation source", "description": "Returns one org-level source, plus linkedWorkspaceIds — the workspaces it is currently linked into. Must belong to the caller's organisation and pass the caller's sources-area access check.", "tags": [ "Sources" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgSourceEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-sources", "summary": "List sources", "description": "Lists sources in the workspace. Query params: limit, cursor (for pagination), parentId (filter by parent folder), format (Tabular or Folder). Excludes virtual sources. Results from platform MongoDB.", "tags": [ "Sources" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "in": "query", "name": "parentId", "required": false, "schema": { "type": "string", "description": "Only return sources derived from this source." }, "description": "Only return sources derived from this source.", "example": "123" }, { "in": "query", "name": "format", "required": false, "schema": { "type": "string", "enum": [ "Tabular", "Folder" ], "description": "Filter by data format." }, "description": "Filter by data format.", "example": "Tabular" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceListEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-api-v1-workspaces-{wsId}-sources", "summary": "Create source", "description": "Creates an empty source (metadata only). Body: name, dataFormat (default Tabular), optional description, parentSourceId. No data is written; use upload, from-data, or connector import to add data. The source record is created in platform MongoDB; data-service is not called until first upload.", "tags": [ "Sources" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSourceSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources/{id}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-sources-{id}", "summary": "Get source", "description": "Returns the source by id from platform MongoDB. Must belong to the workspace. Includes schemaEntries, columnMetadata, documentCount, totalSize if populated by upload or from-data.", "tags": [ "Sources" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "patch": { "operationId": "patch-api-v1-workspaces-{wsId}-sources-{id}", "summary": "Update source", "description": "Updates source name and/or description only. Schema and data are not changed here.", "tags": [ "Sources" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSourceSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-api-v1-workspaces-{wsId}-sources-{id}", "summary": "Delete source", "description": "Deletes the source, every source derived from it, and the data-service state behind them; data views referencing them keep their ids and are flagged broken. Requires `full` access to every source in that tree, not just the one named. Refused with 409 while a digital twin was trained on any of them — `blockingDigitalTwins` names the twins in this workspace, and twins in workspaces the credential cannot reach are counted in `detail` rather than named — and refused while any source in the tree is shared into other workspaces, since deleting it removes it from those too (`sharedSources`, `otherWorkspaceLinks`). `force=true` overrides both refusals, but never the access check.", "tags": [ "Sources" ], "parameters": [ { "in": "query", "name": "force", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Delete even when digital twins were trained on this source. Without it such a delete is refused with 409." }, "description": "Delete even when digital twins were trained on this source. Without it such a delete is refused with 409.", "example": "true" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceDeleteConflictProblem" } } } }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources/from-data": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-sources-from-data", "summary": "Create source from in-memory data", "description": "Creates a new tabular source from a JSON array of records. Body: name, data (array of objects, min length 1), optional description, parentSourceId. Platform creates the source id and record, then hands the data to the data-service, which runs full ingest (type inference, null cleaning, schema), persists to storage, then runs ontology extraction and consolidation. The response carries schemaEntries, columnMetadata, documentCount, totalSize. Use when you have in-memory data (e.g. from an API) rather than a file; avoids file upload and matches UI upload behaviour including ontology.", "tags": [ "Sources" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSourceFromDataSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources/link": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-sources-link", "summary": "Link sources into a workspace", "description": "Makes org-level sources visible inside this workspace. Body: sourceIds (min 1), optional parentSourceId to place them under a folder. Linking a folder brings its whole subtree. Nothing is copied or moved — one source can be linked into many workspaces. Requires write standing on the workspace, not just the sources:write scope. Returns { linked, alreadyLinked }.", "tags": [ "Sources" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources/unlink": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-sources-unlink", "summary": "Unlink sources from a workspace", "description": "Removes sources from this workspace. Body: sourceIds (min 1). Only the link is deleted — the org-level source, its data and its ontology concepts are left intact, and other workspaces keep their links. Removing a folder takes its descendants with it. Requires write standing on the workspace.", "tags": [ "Sources" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnlinkSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources/{id}/extend": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-sources-{id}-extend", "summary": "Extend source with additional data", "description": "Appends data to the source from an uploaded file. Request body: raw file bytes; use header x-filename or Content-Disposition for filename. Does not run ontology processing; schema is inferred from the existing source or file. Use to add more rows without replacing existing data.", "tags": [ "Sources" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "in": "header", "name": "x-filename", "required": true, "schema": { "type": "string", "description": "Filename to store the upload under" }, "description": "Filename to store the upload under", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/BinaryUpload" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources/{id}/records": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-sources-{id}-records", "summary": "Get source records", "description": "Returns paginated rows from the source. Query params: limit (default 50, max 1000), cursor (opaque, from the previous response's pagination.cursor). Data is read from the query engine's storage.", "tags": [ "Sources" ], "parameters": [ { "in": "query", "name": "limit", "required": false, "schema": { "description": "Page size (1-1000, default 50).", "type": "number", "minimum": 1, "maximum": 1000 }, "description": "Page size (1-1000, default 50).", "example": 1 }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque cursor from a previous response's `pagination.cursor`." }, "description": "Opaque cursor from a previous response's `pagination.cursor`.", "example": "example" }, { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources/{id}/replace": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-sources-{id}-replace", "summary": "Replace source data", "description": "Replaces all data in the source with an uploaded file. Request body: raw file bytes; x-filename or Content-Disposition for filename. Ingest (type inference, schema) is applied, then mappings for columns the file no longer contains are detached and ontology extraction is requeued in every linked workspace so each automatically maintained dataset view can adopt the replacement schema. The data replacement can succeed even if ontology reconciliation is unavailable; in that case the response includes a warning telling the client to rerun extraction. Use when you want to refresh content without creating a new source.", "tags": [ "Sources" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "in": "header", "name": "x-filename", "required": true, "schema": { "type": "string", "description": "Filename to store the upload under" }, "description": "Filename to store the upload under", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/BinaryUpload" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources/{id}/retry-ontology": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-sources-{id}-retry-ontology", "summary": "Retry ontology processing", "description": "Retries ontology processing for a source that previously failed (e.g. ontologyStatus extraction_failed or consolidation_failed). If extraction failed, runs extraction inline then queues consolidation; if only consolidation failed, re-queues consolidation. Returns success when the retry is accepted; processing is asynchronous.", "tags": [ "Sources" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources/{id}/schema": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-sources-{id}-schema", "summary": "Get source schema", "description": "Returns source id, name, schema (schemaEntries), columnMetadata, and documentCount from platform MongoDB. No proxy; reflects the last known schema from upload or from-data. For live schema from storage, compare with records.", "tags": [ "Sources" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources/{id}/sync": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-sources-{id}-sync", "summary": "Sync source from its connector", "description": "Triggers a sync for a source that is backed by a live-data connector (e.g. scheduled pull). Only meaningful for sources with a connectionConfig that supports sync; no-op or error otherwise.", "tags": [ "Sources" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources/{id}/upload": { "post": { "operationId": "post-api-v1-workspaces-{wsId}-sources-{id}-upload", "summary": "Upload file to source", "description": "Uploads a file into this source (which must already exist). Request body: raw file bytes; x-filename or Content-Disposition for filename. The data-service parses the file (CSV, Excel, Parquet, etc.), runs full ingest with type inference, then runs ontology extraction and consolidation. For API-only flows, from-data is often simpler and returns the full source with schema.", "tags": [ "Sources" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: id" }, { "in": "header", "name": "x-filename", "required": true, "schema": { "type": "string", "description": "Filename to store the upload under" }, "description": "Filename to store the upload under", "example": "example" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/BinaryUpload" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}/sources/{id}/export/{format}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}-sources-{id}-export-{format}", "summary": "Export source", "description": "Streams the source contents as a file. Path param format: csv, json, or parquet. Response is streaming. Requires exports:read scope.", "tags": [ "Sources" ], "parameters": [ { "in": "path", "name": "format", "required": true, "schema": { "type": "string", "enum": [ "csv", "json", "parquet" ], "description": "Export format" }, "description": "Export format", "example": "csv" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/UnspecifiedEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/me": { "get": { "operationId": "get-api-v1-me", "summary": "Introspect the current credential", "description": "Returns what the presented credential is: userId, organisationId, workspaceId (the workspace the credential is pinned to, or null for org-wide), scopes, authType (apiKey | oauth), and rateLimit (requests per minute; null for OAuth connections, which share the fixed OAuth limit). Needs no scopes — any authenticated caller may ask who it is. Use it to fail fast on missing scopes before starting a workflow.", "tags": [ "Workspaces" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CredentialEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces": { "get": { "operationId": "get-api-v1-workspaces", "summary": "List workspaces", "description": "Lists workspaces the user can access within the organisation. Filtered by resource access: only workspaces where the user has at least read permission (owner, accessRights, or org role) are returned. Not paginated.", "tags": [ "Workspaces" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceListEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "post": { "operationId": "post-api-v1-workspaces", "summary": "Create workspace", "description": "Creates a new workspace with name and optional description. The caller becomes the owner. Workspace is scoped to the organisation from the auth context.", "tags": [ "Workspaces" ], "parameters": [], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkspaceSchema" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/api/v1/workspaces/{wsId}": { "get": { "operationId": "get-api-v1-workspaces-{wsId}", "summary": "Get workspace", "description": "Returns the workspace by id. wsId is resolved from the request URL; workspace must belong to the organisation and user must have access (enforced by middleware).", "tags": [ "Workspaces" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceEnvelope" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "patch": { "operationId": "patch-api-v1-workspaces-{wsId}", "summary": "Update workspace", "description": "Updates workspace name and/or description. Only these fields are writable. Used for display and organisation.", "tags": [ "Workspaces" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWorkspaceSchema" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceEnvelope" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } }, "delete": { "operationId": "delete-api-v1-workspaces-{wsId}", "summary": "Delete workspace", "description": "Permanently deletes the workspace. Requires sources:delete scope and full permission. Does not necessarily delete data in the data-service; workspace-scoped resources may remain until explicitly cleaned.", "tags": [ "Workspaces" ], "parameters": [ { "name": "wsId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "123", "description": "Path parameter: wsId" } ], "security": [ { "BearerAuth": [] } ], "responses": { "204": { "description": "No Content" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } } }, "tags": [ { "name": "Applications" }, { "name": "Catalog" }, { "name": "Connectors" }, { "name": "Datasets" }, { "name": "Digital Twins" }, { "name": "Jobs" }, { "name": "MCP" }, { "name": "Ontology" }, { "name": "Rendering" }, { "name": "Reports" }, { "name": "Simulations" }, { "name": "Sources" }, { "name": "Workspaces" } ] }