{ "openapi": "3.1.0", "info": { "title": "Mach-1 forecasting API", "version": "2026-10", "description": "Bounded forecasting using the existing prediction engine. Requires forecast-scoped credentials. Numerical limits: 4 series, 32768 total history buckets, 10000 total future points, 8 drivers per series. Runtime normalization additionally checks alignment, timezone, and observed-history rules." }, "servers": [ { "url": "https://build.aioncx.com" } ], "security": [ { "forecastKey": [] } ], "x-generated-from": [ "src/lib/atlas/predictions/prediction-request-schema.ts", "src/lib/atlas/predictions/numerical-schema.ts", "src/lib/api/forecast-http.ts", "src/lib/atlas/mach1/forecast-service.ts" ], "paths": { "/api/forecasts": { "post": { "operationId": "submitMach1Forecast", "summary": "Submit a numerical or registered-metric forecast", "description": "Requires forecast:submit. Retain the original payload and Idempotency-Key for uncertain retries. Request body limit: 1 MiB.", "parameters": [ { "name": "workspace_id", "in": "query", "required": false, "description": "Select a granted workspace. Required when a credential grants multiple workspaces.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Stable caller-generated key. Reuse only with the same request.", "schema": { "type": "string", "minLength": 1, "maxLength": 256 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForecastRequest" }, "example": { "method": "auto", "source": { "type": "numerical", "grain": "day", "timezone": "UTC", "historyStart": "2026-01-01T00:00:00Z", "horizon": 4, "series": [ { "id": "daily-contacts", "values": [ 42, 45, 48, 43, 51, 36, 31, 44, 47, 50, 46, 54, 38, 33, 46, 49, 52, 48, 56, 40, 35, 48, 51, 54, 50, 58, 42, 37 ] } ] } } } } }, "responses": { "200": { "description": "Existing or immediately resolved run", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "results_url" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "results_url": { "type": "string" }, "price": { "type": "object", "additionalProperties": true, "description": "Price retained at first acceptance. See the guide for current forecasting charges." } } } } } }, "202": { "description": "Accepted; draft, queued, or running", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "results_url" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "results_url": { "type": "string" }, "price": { "type": "object", "additionalProperties": true, "description": "Price retained at first acceptance. See the guide for current forecasting charges." } } } } } }, "400": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "401": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "403": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "404": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "409": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "413": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "415": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "503": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } } } } }, "/api/forecasts/{runId}": { "get": { "operationId": "getMach1Forecast", "summary": "Read retained forecast status and results", "description": "Requires forecast:read and current source access. Follow next_cursor with the same quantile selection. Reads do not create another prediction run.", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Select a granted workspace. Required when a credential grants multiple workspaces.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 2048 } }, { "name": "quantiles", "in": "query", "description": "Comma-separated supported levels. Default: 0.05,0.5,0.95. Keep the same selection across cursor pages.", "schema": { "type": "string", "default": "0.05,0.5,0.95" } } ], "responses": { "200": { "description": "Saved status and authorized result page", "content": { "application/json": { "schema": { "type": "object", "required": [ "run_id", "status", "rows", "next_cursor" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "method": { "type": "string" }, "method_version": { "type": [ "string", "null" ] }, "error": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "required": [ "interval_start", "interval_end", "predicted_value" ], "properties": { "series_id": { "type": [ "string", "null" ] }, "dimensions": { "type": "object", "additionalProperties": true }, "interval_start": { "type": "string", "format": "date-time" }, "interval_end": { "type": "string", "format": "date-time" }, "predicted_value": { "type": [ "number", "null" ] }, "lower_bound": { "type": [ "number", "null" ] }, "upper_bound": { "type": [ "number", "null" ] }, "point_statistic": { "type": "string" }, "tail_assumption": { "type": [ "string", "null" ] }, "interval_statistic": { "type": "string" }, "quantile_space": { "type": [ "string", "null" ] }, "quantiles": { "type": "array", "items": { "type": "object", "required": [ "level", "value" ], "properties": { "level": { "type": "number" }, "value": { "type": "number" } } } } } } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "401": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "403": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "404": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "409": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "413": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "415": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } }, "503": { "description": "Request refused or service unavailable", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "retryable": { "type": "boolean" } } } } } } } } } }, "components": { "securitySchemes": { "forecastKey": { "type": "http", "scheme": "bearer", "description": "A scoped Mach-1 atlas_ingest_ key with forecast:submit and/or forecast:read. Ingestion scopes alone do not grant forecasting." } }, "schemas": { "ForecastRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "method": { "default": "auto", "type": "string", "enum": [ "timestral", "auto", "moving_average", "weighted_recent_average", "seasonal_baseline", "seasonal_naive", "holt_winters", "driver_regression" ] }, "source": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "numerical" }, "grain": { "type": "string", "enum": [ "15m", "30m", "hour", "day", "week" ] }, "timezone": { "default": "UTC", "type": "string", "maxLength": 64 }, "historyStart": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "horizon": { "type": "integer", "minimum": 1, "maximum": 10000 }, "series": { "minItems": 1, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 120 }, "values": { "minItems": 2, "maxItems": 32768, "type": "array", "items": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "drivers": { "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 120 }, "valueType": { "type": "string", "enum": [ "numeric", "categorical" ] }, "availability": { "type": "string", "enum": [ "past_only", "known_future" ] }, "required": { "default": false, "type": "boolean" }, "values": { "type": "array", "items": { "anyOf": [ { "type": "number" }, { "type": "string", "maxLength": 120 }, { "type": "null" } ] } }, "mask": { "type": "array", "items": { "type": "boolean" } }, "availableAt": { "type": "array", "items": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } } }, "required": [ "id", "valueType", "availability", "values", "mask" ], "additionalProperties": false } } }, "required": [ "id", "values" ], "additionalProperties": false } } }, "required": [ "type", "grain", "historyStart", "horizon", "series" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "metric" }, "targetObjectType": { "type": "string", "minLength": 1, "maxLength": 120 }, "targetObjectId": { "default": null, "anyOf": [ { "type": "string", "maxLength": 240 }, { "type": "null" } ] }, "metricRef": { "type": "string", "minLength": 1, "maxLength": 240 }, "grain": { "type": "string", "enum": [ "15m", "30m", "hour", "day", "week" ] }, "timezone": { "default": "UTC", "type": "string", "maxLength": 64 }, "historyStart": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "historyEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "horizon": { "type": "integer", "minimum": 1, "maximum": 10000 }, "dimensions": { "default": [], "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "filters": { "default": [], "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "targetType": { "type": "string", "enum": [ "object", "attribute", "metric", "time" ] }, "ref": { "type": "string", "minLength": 1 }, "operator": { "type": "string", "enum": [ "eq", "neq", "in", "not_in", "gt", "gte", "lt", "lte", "between", "contains", "is_null", "is_not_null" ] }, "value": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, { "type": "null" } ] } }, "required": [ "targetType", "ref", "operator" ], "additionalProperties": false } }, { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, { "type": "null" } ] } } ] }, "inputs": { "default": [], "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "semanticRef": { "type": "string", "minLength": 1, "maxLength": 240 }, "kind": { "default": "metric", "type": "string", "const": "metric" }, "role": { "default": "feature", "type": "string", "const": "feature" }, "lagPeriods": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "label": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "semanticRef" ] } }, "timeRole": { "type": "string", "minLength": 1, "maxLength": 120 }, "scopeTime": { "default": { "mode": "event_time" }, "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "event_time" } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "reconstruction" }, "effectiveAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "mode", "effectiveAt" ], "additionalProperties": false } ] } }, "required": [ "type", "targetObjectType", "metricRef", "grain", "historyStart", "historyEnd", "horizon" ], "additionalProperties": false } ] } }, "required": [ "source" ], "additionalProperties": false } } } }