{ "openapi": "3.1.0", "info": { "version": "1.0.0", "title": "The Forecasting Company API", "description": "Welcome to the TFC API. If you have any issues or feedback please get in touch with us at `support@theforecastingcompany.com`." }, "servers": [ { "url": "https://api.retrocast.com" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Send your API key as `Authorization: Bearer `. Keys are opaque strings issued via the developer portal." }, "api_key": { "type": "http", "scheme": "bearer" } }, "responses": { "InvalidRequest": { "description": "The request body or parameters failed validation. Branch on `code = invalid_request`. Check the optional `errors` array for field-level details.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/responses/NotFound/content/application~1problem%2Bjson/schema" }, "example": { "type": "about:blank", "title": "Invalid request", "status": 422, "code": "invalid_request", "detail": "Request failed validation", "errors": [ { "path": "body.series[0].target", "message": "Field required" } ] } } } }, "InvalidAuth": { "description": "Missing or invalid API key. Branch on `code = invalid_auth`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/responses/NotFound/content/application~1problem%2Bjson/schema" }, "example": { "type": "about:blank", "title": "Invalid authentication", "status": 401, "code": "invalid_auth", "detail": "Invalid or missing API key" } } } }, "Forbidden": { "description": "Authenticated, but not allowed to access this resource. Branch on `code = forbidden`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/responses/NotFound/content/application~1problem%2Bjson/schema" }, "example": { "type": "about:blank", "title": "Forbidden", "status": 403, "code": "forbidden", "detail": "You do not have permission to access this job" } } } }, "NotFound": { "description": "The addressed resource doesn't exist. Branch on `code = not_found`.", "content": { "application/problem+json": { "schema": { "$defs": { "FieldError": { "description": "Pointer to one invalid field in a validation failure.", "properties": { "path": { "description": "Dot-string path to the offending field, e.g. 'body.series[0].target'.", "title": "Path", "type": "string" }, "message": { "description": "Human-readable description of what's wrong with this field.", "title": "Message", "type": "string" } }, "required": [ "path", "message" ], "title": "FieldError", "type": "object" } }, "description": "Error response body returned for every non-2xx response, with content-type `application/problem+json`. Follows RFC 9457.", "properties": { "type": { "default": "about:blank", "description": "A URI reference identifying the problem type. `about:blank` when no specific type is documented.", "title": "Type", "type": "string" }, "title": { "description": "A short, human-readable summary of the problem.", "title": "Title", "type": "string" }, "status": { "description": "The HTTP status code.", "exclusiveMaximum": 600, "minimum": 400, "title": "Status", "type": "integer" }, "code": { "description": "Machine-readable error code. Switch on this in client code to handle errors programmatically. Common values: forbidden, forecast_failed, internal_error, invalid_auth, invalid_request, not_found, rate_limited. Additional codes may be introduced over time; treat unknown codes as the same category as the HTTP status.", "examples": [ "forbidden", "forecast_failed", "internal_error", "invalid_auth", "invalid_request", "not_found", "rate_limited" ], "title": "Code", "type": "string" }, "detail": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Human-readable explanation specific to this occurrence.", "title": "Detail" }, "errors": { "anyOf": [ { "items": { "$ref": "#/components/responses/NotFound/content/application~1problem%2Bjson/schema/%24defs/FieldError" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Field-level breakdown for validation errors. Absent when not applicable.", "title": "Errors" } }, "required": [ "title", "status", "code" ], "title": "ProblemDetails", "type": "object" }, "example": { "type": "about:blank", "title": "Not found", "status": 404, "code": "not_found", "detail": "Job 'abc123' not found." } } } }, "RateLimited": { "description": "Rate limit exceeded. Retry after the time indicated by the `Retry-After` header. Branch on `code = rate_limited`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/responses/NotFound/content/application~1problem%2Bjson/schema" }, "example": { "type": "about:blank", "title": "Rate limit exceeded", "status": 429, "code": "rate_limited" } } } }, "InternalError": { "description": "Unexpected server-side failure. Branch on `code` (`forecast_failed` or `internal_error`).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/responses/NotFound/content/application~1problem%2Bjson/schema" }, "example": { "type": "about:blank", "title": "Forecast failed", "status": 500, "code": "forecast_failed", "detail": "Job failed with error: ..." } } } }, "RateLimitNoRetryAfter": { "description": "Rate Limiting Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "title", "status" ], "examples": [ { "type": "https://httpproblems.com/http-status/429", "title": "Too Many Requests", "status": 429, "instance": "/foo/bar" } ], "properties": { "type": { "type": "string", "example": "https://httpproblems.com/http-status/429", "description": "A URI reference that identifies the problem." }, "title": { "type": "string", "example": "Too Many Requests", "description": "A short, human-readable summary of the problem." }, "status": { "type": "number", "example": 429, "description": "The HTTP status code." }, "instance": { "type": "string", "example": "/foo/bar" } } } } } }, "RateLimitWithRetryAfter": { "description": "Rate Limiting Response", "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "title", "status" ], "examples": [ { "type": "https://httpproblems.com/http-status/429", "title": "Too Many Requests", "status": 429, "instance": "/foo/bar" } ], "properties": { "type": { "type": "string", "example": "https://httpproblems.com/http-status/429", "description": "A URI reference that identifies the problem." }, "title": { "type": "string", "example": "Too Many Requests", "description": "A short, human-readable summary of the problem." }, "status": { "type": "number", "example": 429, "description": "The HTTP status code." }, "instance": { "type": "string", "example": "/foo/bar" } } } } }, "headers": { "retry-after": { "description": "The number of seconds to wait before making a new request.", "schema": { "type": "integer", "example": 60 } } } } } }, "tags": [ { "name": "Endpoints", "description": "Welcome to the TFC API. If you have any issues or feedback please get in touch with us at `support@theforecastingcompany.com`." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/forecast": { "post": { "tags": [ "Endpoints" ], "security": [ { "api_key": [] }, { "bearerAuth": [] } ], "summary": "Model inference", "description": "Perform inference with foundation models.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "example": "Bearer YOUR_KEY_HERE", "schema": { "type": "string" }, "description": "The `Authorization` header is used to authenticate with the API using your API key. Value is of the format `Bearer YOUR_KEY_HERE`." }, { "name": "model", "in": "query", "required": true, "description": "The forecasting model to use for inference. Note that only `tabpfn-ts`, `moirai-2`, and `chronos-2` support exogenous variables.", "schema": { "type": "string", "enum": [ "t0-alpha", "timesfm-2", "timesfm-2p5", "moirai-2", "tabpfn-ts", "tirex", "tfc-global", "aets", "aarima", "chronos-2", "tabicl", "reverso", "patchtst-fm", "toto-2" ], "default": "t0-alpha" } }, { "name": "cloud", "in": "query", "required": false, "description": "Specify the cloud provider to use for inference. If none is set then any may be used depending on availability, including clouds not present in the below list (e.g. Oracle).", "schema": { "type": "string", "enum": [ "gcp", "aws" ] } }, { "name": "region", "in": "query", "required": false, "description": "Specify the region to use. If none is set then any may be used depending on availability, including regions not available for direct selection (such as ap or uk). Note that the region specifies the region for processing, but the request still passes through a control plane in the US.", "schema": { "type": "string", "enum": [ "us", "eu" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "AarimaConfig": { "additionalProperties": false, "properties": { "season_length": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Override automatic seasonal period detection.", "title": "Season Length" } }, "title": "AarimaConfig", "type": "object" }, "AarimaModelConfig": { "properties": { "model": { "const": "aarima", "title": "Model", "type": "string" }, "config": { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/AarimaConfig" } }, "required": [ "model", "config" ], "title": "AarimaModelConfig", "type": "object" }, "AetsConfig": { "additionalProperties": false, "properties": { "season_length": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Override automatic seasonal period detection.", "title": "Season Length" } }, "title": "AetsConfig", "type": "object" }, "AetsModelConfig": { "properties": { "model": { "const": "aets", "title": "Model", "type": "string" }, "config": { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/AetsConfig" } }, "required": [ "model", "config" ], "title": "AetsModelConfig", "type": "object" }, "Chronos2Config": { "additionalProperties": false, "properties": { "is_global": { "default": false, "description": "Enable influence across the time-series - useful if all passed in time-series are related (e.g. same product, different stores).", "title": "Is Global", "type": "boolean" } }, "title": "Chronos2Config", "type": "object" }, "Chronos2ModelConfig": { "properties": { "model": { "const": "chronos-2", "title": "Model", "type": "string" }, "config": { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/Chronos2Config" } }, "required": [ "model", "config" ], "title": "Chronos2ModelConfig", "type": "object" }, "EventConfig": { "properties": { "country": { "description": "ISO country code for events (2-char code or 'Global')", "examples": [ "US", "GB", "FR", "DE", "Global" ], "title": "Country", "type": "string" } }, "required": [ "country" ], "title": "EventConfig", "type": "object" }, "EventsCovariate": { "properties": { "type": { "const": "events", "examples": [ "events" ], "title": "Type", "type": "string" }, "config": { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/EventConfig", "examples": [ { "country": "US" } ] } }, "required": [ "type", "config" ], "title": "EventsCovariate", "type": "object" }, "FloatConfig": { "properties": { "data_source": { "title": "Data Source", "type": "string" }, "column": { "description": "Column for the data source", "maxLength": 100, "minLength": 1, "title": "Column", "type": "string" } }, "required": [ "data_source", "column" ], "title": "FloatConfig", "type": "object" }, "FloatDataSourceCovariate": { "properties": { "type": { "const": "float", "examples": [ "float" ], "title": "Type", "type": "string" }, "config": { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/FloatConfig", "examples": [ { "column": "SomeColumn" } ] } }, "required": [ "type", "config" ], "title": "FloatDataSourceCovariate", "type": "object" }, "ForexConfig": { "properties": { "base": { "default": "EUR", "description": "Base currency code (e.g. EUR, USD)", "examples": [ "EUR", "USD" ], "maxLength": 3, "minLength": 3, "title": "Base", "type": "string" }, "target": { "description": "Target currency code (e.g. USD, GBP, JPY)", "examples": [ "USD", "GBP", "JPY" ], "maxLength": 3, "minLength": 3, "title": "Target", "type": "string" } }, "required": [ "target" ], "title": "ForexConfig", "type": "object" }, "ForexCovariate": { "properties": { "type": { "const": "forex", "examples": [ "forex" ], "title": "Type", "type": "string" }, "config": { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/ForexConfig", "examples": [ { "base": "EUR", "target": "USD" } ] } }, "required": [ "type", "config" ], "title": "ForexCovariate", "type": "object" }, "HolidayConfig": { "properties": { "country": { "description": "ISO country code for holidays", "examples": [ "US", "GB", "FR", "DE" ], "maxLength": 2, "minLength": 2, "title": "Country", "type": "string" }, "smoothing_method": { "default": "auto", "description": "Method to smooth holiday indicators. 'auto' picks frequency-specific defaults; 'none' keeps binary 0/1.", "enum": [ "auto", "none", "gaussian", "exponential", "ramp", "flat" ], "title": "Smoothing Method", "type": "string" }, "window_size": { "default": 15, "description": "Size of the smoothing window, should be odd", "maximum": 15, "minimum": 1, "title": "Window Size", "type": "integer" }, "sigma": { "default": 7, "description": "Standard deviation for Gaussian kernel", "exclusiveMinimum": 0, "title": "Sigma", "type": "number" }, "ramp_days": { "default": 14, "description": "Number of days before/after for ramp up/down", "maximum": 35, "minimum": 1, "title": "Ramp Days", "type": "integer" } }, "required": [ "country" ], "title": "HolidayConfig", "type": "object" }, "HolidaysCovariate": { "properties": { "type": { "const": "holidays", "examples": [ "holidays" ], "title": "Type", "type": "string" }, "config": { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/HolidayConfig", "examples": [ { "country": "US" } ] } }, "required": [ "type", "config" ], "title": "HolidaysCovariate", "type": "object" }, "InputSerie": { "properties": { "target": { "description": "A list of numeric target values.", "items": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "type": "string" } ] }, "minItems": 1, "title": "Target", "type": "array" }, "index": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "items": { "format": "date", "type": "string" }, "type": "array" }, { "items": { "format": "date-time", "type": "string" }, "type": "array" } ], "description": "A list of dates, datetimes, times, or integers.", "minLength": 1, "title": "Index" }, "hist_variables": { "additionalProperties": { "items": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "type": "string" } ] }, "type": "array" }, "default": {}, "description": "A dictionary mapping string keys to lists of historical numeric values, e.g. recorded temperatures, that has the length of the largest FCD (or the length of the target if no specific FCD is provided).", "title": "Hist Variables", "type": "object" }, "future_variables_index": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "items": { "format": "date", "type": "string" }, "type": "array" }, { "items": { "format": "date-time", "type": "string" }, "type": "array" } ], "default": [], "description": "A list of dates, datetimes, times, or integers.", "title": "Future Variables Index" }, "future_variables": { "additionalProperties": { "items": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "type": "string" } ] }, "type": "array" }, "default": {}, "description": "A dictionary mapping string keys to lists of numeric values that have the length of the largest FCD plus the horizon, e.g. forecasted temperatures.", "title": "Future Variables", "type": "object" }, "static_variables": { "additionalProperties": { "anyOf": [ { "type": "number" }, { "type": "integer" } ] }, "default": {}, "description": "A dictionary mapping string keys to static numeric values, e.g. a SKU.", "title": "Static Variables", "type": "object" }, "fcds": { "anyOf": [ { "items": { "type": "integer" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "A list of indexes representing the forecast creation dates, indexing the target. If not provided the forecast creation date is the latest possible date. This can be used to get multiple forecasts from the same series at once (e.g. for backtesting).", "title": "Fcds" }, "only_as_context": { "default": false, "description": "If True, the series will be used only as context (ie, not forecasted). This should always be False unless a global model is used.", "title": "Only As Context", "type": "boolean" } }, "required": [ "target", "index" ], "title": "InputSerie", "type": "object" }, "NaiveConfig": { "additionalProperties": false, "properties": { "season_length": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": 1, "description": "Override automatic seasonal period detection.", "title": "Season Length" } }, "title": "NaiveConfig", "type": "object" }, "NaiveModelConfig": { "properties": { "model": { "const": "naive", "title": "Model", "type": "string" }, "config": { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/NaiveConfig" } }, "required": [ "model", "config" ], "title": "NaiveModelConfig", "type": "object" }, "TemporalFeaturesConfig": { "properties": { "components": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Raw (non-cyclical) calendar components. Default: ['year'].", "examples": [ [ "year" ] ], "title": "Components" }, "seasonal_features": { "anyOf": [ { "additionalProperties": { "type": "number" }, "propertyNames": { "enum": [ "month_of_year", "day_of_month", "day_of_week", "day_of_year", "week_of_year", "hour_of_day", "hour_of_week", "minute_of_hour", "minute_of_day", "second_of_minute" ] }, "type": "object" }, { "type": "null" } ], "default": null, "description": "Cyclical features → natural periods for sin/cos encoding. Omit a key to exclude that feature. Default: all 10 standard features. Valid keys: month_of_year, day_of_month, day_of_week, day_of_year, week_of_year, hour_of_day, hour_of_week, minute_of_hour, minute_of_day, second_of_minute.", "examples": [ { "day_of_week": 7, "month_of_year": 12 } ], "title": "Seasonal Features" } }, "title": "TemporalFeaturesConfig", "type": "object" }, "TemporalFeaturesCovariate": { "properties": { "type": { "const": "temporal_features", "examples": [ "temporal_features" ], "title": "Type", "type": "string" }, "config": { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/TemporalFeaturesConfig", "examples": [ {} ] } }, "required": [ "type", "config" ], "title": "TemporalFeaturesCovariate", "type": "object" } }, "description": "API request model for the model inference endpoint.", "properties": { "series": { "examples": [ [ { "future_variables": { "local_attendance_forecast": [ 125, 75, 200, 122, 123, 150, 100, 120, 121, 119 ] }, "future_variables_index": [ "2001-01-06", "2001-01-07", "2001-01-08", "2001-01-09", "2001-01-10", "2001-01-11", "2001-01-12", "2001-01-13", "2001-01-14", "2001-01-15" ], "hist_variables": { "temperature": [ 74, 72, 79, 77, 75 ] }, "index": [ "2001-01-06", "2001-01-07", "2001-01-08", "2001-01-09", "2001-01-10" ], "static_variables": { "Population": 100000 }, "target": [ 125, 120, 140, 135, 133 ] } ] ], "items": { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/InputSerie" }, "title": "Series", "type": "array" }, "horizon": { "description": "Number of steps to forecast given the frequency.", "examples": [ 5 ], "maximum": 10000, "minimum": 1, "title": "Horizon", "type": "integer" }, "freq": { "description": "Frequency of the time series.", "enum": [ "10S", "min", "5min", "10min", "15min", "30min", "H", "D", "W", "M", "Q", "Y" ], "examples": [ "D" ], "title": "Freq", "type": "string" }, "context": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "The amount of history to use when forecasting. This is the number of steps to look back in the target series. More history can improve the forecast accuracy, but can also increase the computation time. By default this is set to the max of model capability or the length of the provided target series, whichever is shorter.", "examples": [ 20 ], "title": "Context" }, "quantiles": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "default": [ 0.1, 0.9, 0.4, 0.5 ], "title": "Quantiles" }, "covariates": { "anyOf": [ { "items": { "discriminator": { "mapping": { "events": "#/$defs/EventsCovariate", "float": "#/$defs/FloatDataSourceCovariate", "forex": "#/$defs/ForexCovariate", "holidays": "#/$defs/HolidaysCovariate", "temporal_features": "#/$defs/TemporalFeaturesCovariate" }, "propertyName": "type" }, "oneOf": [ { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/HolidaysCovariate" }, { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/FloatDataSourceCovariate" }, { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/ForexCovariate" }, { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/EventsCovariate" }, { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/TemporalFeaturesCovariate" } ] }, "type": "array" }, { "type": "null" } ], "default": null, "description": "Apply additional co-variates provided by TFC. Only supported by the following models: Moirai-2, Chronos-2 and TabPFN-TS.", "examples": [ [ { "config": { "country": "US" }, "type": "holidays" } ] ], "title": "Covariates" }, "model_config": { "anyOf": [ { "discriminator": { "mapping": { "aarima": "#/$defs/AarimaModelConfig", "aets": "#/$defs/AetsModelConfig", "chronos-2": "#/$defs/Chronos2ModelConfig", "naive": "#/$defs/NaiveModelConfig" }, "propertyName": "model" }, "oneOf": [ { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/AarimaModelConfig" }, { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/AetsModelConfig" }, { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/Chronos2ModelConfig" }, { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema/%24defs/NaiveModelConfig" } ] }, { "type": "null" } ], "default": null, "description": "Optional model-specific configuration overrides.", "examples": [ { "config": { "season_length": 7 }, "model": "aarima" } ], "title": "Model Config" } }, "required": [ "series", "horizon", "freq" ], "title": "ForecastRequest", "type": "object" }, "examples": { "simple": { "summary": "Simple univariate forecast", "value": { "series": [ { "index": [ "2001-01-06", "2001-01-07", "2001-01-08", "2001-01-09", "2001-01-10" ], "target": [ 125, 120, 140, 135, 133 ] } ], "horizon": 5, "freq": "D", "context": null, "quantiles": [ 0.1, 0.9, 0.4, 0.5 ] } }, "multiple": { "summary": "Multiple univariate forecasts", "value": { "series": [ { "index": [ "2001-01-06", "2001-01-07", "2001-01-08", "2001-01-09", "2001-01-10" ], "target": [ 125, 120, 140, 135, 133 ] }, { "index": [ "2001-01-06", "2001-01-07", "2001-01-08", "2001-01-09", "2001-01-10" ], "target": [ 500, 300, 200, 100, 200 ] } ], "horizon": 5, "freq": "D", "context": null, "quantiles": [ 0.1, 0.9, 0.4, 0.5 ] } }, "covars": { "summary": "Forecast with covariates", "value": { "series": [ { "future_variables": { "local_attendance_forecast": [ 125, 75, 200, 122, 123, 150, 100, 120, 121, 119 ] }, "future_variables_index": [ "2001-01-06", "2001-01-07", "2001-01-08", "2001-01-09", "2001-01-10", "2001-01-11", "2001-01-12", "2001-01-13", "2001-01-14", "2001-01-15" ], "hist_variables": { "temperature": [ 74, 72, 79, 77, 75 ] }, "index": [ "2001-01-06", "2001-01-07", "2001-01-08", "2001-01-09", "2001-01-10" ], "static_variables": { "Population": 100000 }, "target": [ 125, 120, 140, 135, 133 ] } ], "horizon": 5, "freq": "D", "context": null, "quantiles": [ 0.1, 0.9, 0.4, 0.5 ], "covariates": [ { "config": { "country": "US" }, "type": "holidays" } ] } }, "arima": { "summary": "With model config (ARIMA)", "value": { "series": [ { "index": [ "2001-01-06", "2001-01-07", "2001-01-08", "2001-01-09", "2001-01-10" ], "target": [ 125, 120, 140, 135, 133 ] } ], "horizon": 5, "freq": "D", "context": null, "quantiles": [ 0.1, 0.9, 0.4, 0.5 ], "model_config": { "config": { "season_length": 7 }, "model": "aarima" } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$defs": { "Metrics": { "properties": { "mae": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Mae" }, "mape": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Mape" }, "crps": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Crps" }, "wape": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Wape" }, "scaled_bias": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Scaled Bias" } }, "title": "Metrics", "type": "object" }, "OutputSerie": { "properties": { "prediction": { "additionalProperties": { "items": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "type": "string" } ] }, "type": "array" }, "examples": [ { "0.1": [ 1, 2, 3 ], "0.9": [ 1, 2, 3 ], "mean": [ 1, 2, 3 ] } ], "title": "Prediction", "type": "object" }, "index": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "items": { "format": "date", "type": "string" }, "type": "array" }, { "items": { "format": "date-time", "type": "string" }, "type": "array" } ], "examples": [], "title": "Index" }, "metrics": { "anyOf": [ { "$ref": "#/paths/~1forecast/post/responses/200/content/application~1json/schema/%24defs/Metrics" }, { "type": "null" } ], "default": null } }, "required": [ "prediction", "index" ], "title": "OutputSerie", "type": "object" } }, "description": "Synchronous `POST /forecast` response. Always carries a completed forecast.", "properties": { "series": { "description": "Per-input-series predictions.", "items": { "items": { "$ref": "#/paths/~1forecast/post/responses/200/content/application~1json/schema/%24defs/OutputSerie" }, "type": "array" }, "title": "Series", "type": "array" } }, "required": [ "series" ], "title": "ForecastResponse", "type": "object" } } } }, "401": { "$ref": "#/components/responses/InvalidAuth" }, "422": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "operationId": "508375c1-c842-4b15-8e34-adcefdf67c78" } }, "/forecast-jobs": { "post": { "tags": [ "Endpoints" ], "security": [ { "api_key": [] }, { "bearerAuth": [] } ], "summary": "Submit job for forecasting", "description": "Perform historic inference for a range of forecast creation dates (fcds). These jobs can run longer and need to be retrieved with a separate endpoint and the returned job ID.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "example": "Bearer YOUR_KEY_HERE", "schema": { "type": "string" }, "description": "The `Authorization` header is used to authenticate with the API using your API key. Value is of the format `Bearer YOUR_KEY_HERE`." }, { "name": "model", "in": "query", "required": true, "description": "The forecasting model to use for inference. Note that only `tabpfn-ts` and `moirai` support exogenous variables.", "schema": { "type": "string", "enum": [ "t0-alpha", "timesfm-2", "timesfm-2p5", "moirai-2", "tabpfn-ts", "tirex", "tfc-global", "aets", "aarima", "chronos-2", "tabicl", "reverso", "patchtst-fm", "toto-2" ], "default": "t0-alpha" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/paths/~1forecast/post/requestBody/content/application~1json/schema" }, "examples": { "simple": { "summary": "Simple univariate forecast", "value": { "series": [ { "index": [ "2001-01-06", "2001-01-07", "2001-01-08", "2001-01-09", "2001-01-10" ], "target": [ 125, 120, 140, 135, 133 ] } ], "horizon": 5, "freq": "D", "context": null, "quantiles": [ 0.1, 0.9, 0.4, 0.5 ] } }, "covars": { "summary": "Forecast with covariates", "value": { "series": [ { "future_variables": { "local_attendance_forecast": [ 125, 75, 200, 122, 123, 150, 100, 120, 121, 119 ] }, "future_variables_index": [ "2001-01-06", "2001-01-07", "2001-01-08", "2001-01-09", "2001-01-10", "2001-01-11", "2001-01-12", "2001-01-13", "2001-01-14", "2001-01-15" ], "hist_variables": { "temperature": [ 74, 72, 79, 77, 75 ] }, "index": [ "2001-01-06", "2001-01-07", "2001-01-08", "2001-01-09", "2001-01-10" ], "static_variables": { "Population": 100000 }, "target": [ 125, 120, 140, 135, 133 ] } ], "horizon": 5, "freq": "D", "context": null, "quantiles": [ 0.1, 0.9, 0.4, 0.5 ], "covariates": [ { "config": { "country": "US" }, "type": "holidays" } ] } } } } } }, "responses": { "200": { "description": "Job submitted successfully. The returned `job_id` is used to poll `GET /forecast-jobs/{job_id}` for results.", "content": { "application/json": { "schema": { "description": "`POST /forecast-jobs` response. Carries the identifier used to poll for results.", "properties": { "job_id": { "description": "Unique identifier for the submitted job. Use it with `GET /forecast-jobs/{job_id}` to poll for results.", "title": "Job Id", "type": "string" } }, "required": [ "job_id" ], "title": "JobSubmittedResponse", "type": "object" } } } }, "401": { "$ref": "#/components/responses/InvalidAuth" }, "422": { "$ref": "#/components/responses/InvalidRequest" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "operationId": "8aa3c090-f10c-4991-be37-ac760bf18df9" } }, "/forecast-jobs/{job_id}": { "get": { "tags": [ "Endpoints" ], "security": [ { "api_key": [] }, { "bearerAuth": [] } ], "summary": "Retrieve job result", "description": "Retrieve the forecast result from a forecast job.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "example": "Bearer YOUR_KEY_HERE", "schema": { "type": "string" }, "description": "The `Authorization` header is used to authenticate with the API using your API key. Value is of the format `Bearer YOUR_KEY_HERE`." }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job state. Switch on `status` — `completed` carries `series`, `failed` carries `error`, `in_progress` means keep polling.", "content": { "application/json": { "schema": { "$defs": { "JobCompleted": { "description": "Async polling response when the job finished successfully.", "properties": { "status": { "const": "completed", "title": "Status", "type": "string" }, "series": { "description": "Per-input-series predictions.", "items": { "items": { "$ref": "#/paths/~1forecast-jobs~1%7Bjob_id%7D/get/responses/200/content/application~1json/schema/%24defs/OutputSerie" }, "type": "array" }, "title": "Series", "type": "array" } }, "required": [ "status", "series" ], "title": "JobCompleted", "type": "object" }, "JobError": { "description": "Why a backgrounded forecast job failed. Returned as part of `JobFailed`.", "properties": { "code": { "description": "Machine-readable identifier for the failure category. Same vocabulary as the top-level Problem `code` field — currently always 'forecast_failed' for job failures, but apps may introduce more specific codes.", "examples": [ "forecast_failed" ], "title": "Code", "type": "string" }, "message": { "description": "Human-readable explanation of the failure.", "title": "Message", "type": "string" } }, "required": [ "code", "message" ], "title": "JobError", "type": "object" }, "JobFailed": { "description": "Async polling response when the job failed permanently. Don't retry.", "properties": { "status": { "const": "failed", "title": "Status", "type": "string" }, "error": { "$ref": "#/paths/~1forecast-jobs~1%7Bjob_id%7D/get/responses/200/content/application~1json/schema/%24defs/JobError", "description": "Structured explanation of the failure." } }, "required": [ "status", "error" ], "title": "JobFailed", "type": "object" }, "JobInProgress": { "description": "Async polling response when the job is still running. Keep polling.", "properties": { "status": { "const": "in_progress", "title": "Status", "type": "string" } }, "required": [ "status" ], "title": "JobInProgress", "type": "object" }, "Metrics": { "properties": { "mae": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Mae" }, "mape": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Mape" }, "crps": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Crps" }, "wape": { "anyOf": [ { "minimum": 0, "type": "number" }, { "type": "null" } ], "default": null, "title": "Wape" }, "scaled_bias": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Scaled Bias" } }, "title": "Metrics", "type": "object" }, "OutputSerie": { "properties": { "prediction": { "additionalProperties": { "items": { "anyOf": [ { "type": "number" }, { "type": "integer" }, { "type": "string" } ] }, "type": "array" }, "examples": [ { "0.1": [ 1, 2, 3 ], "0.9": [ 1, 2, 3 ], "mean": [ 1, 2, 3 ] } ], "title": "Prediction", "type": "object" }, "index": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "items": { "format": "date", "type": "string" }, "type": "array" }, { "items": { "format": "date-time", "type": "string" }, "type": "array" } ], "examples": [], "title": "Index" }, "metrics": { "anyOf": [ { "$ref": "#/paths/~1forecast-jobs~1%7Bjob_id%7D/get/responses/200/content/application~1json/schema/%24defs/Metrics" }, { "type": "null" } ], "default": null } }, "required": [ "prediction", "index" ], "title": "OutputSerie", "type": "object" } }, "description": "Discriminated union returned by `GET /forecast-jobs/{job_id}`. Switch on `status` — `completed` carries `series`, `failed` carries `error`, `in_progress` means keep polling.", "discriminator": { "mapping": { "completed": "#/$defs/JobCompleted", "failed": "#/$defs/JobFailed", "in_progress": "#/$defs/JobInProgress" }, "propertyName": "status" }, "oneOf": [ { "$ref": "#/paths/~1forecast-jobs~1%7Bjob_id%7D/get/responses/200/content/application~1json/schema/%24defs/JobCompleted" }, { "$ref": "#/paths/~1forecast-jobs~1%7Bjob_id%7D/get/responses/200/content/application~1json/schema/%24defs/JobInProgress" }, { "$ref": "#/paths/~1forecast-jobs~1%7Bjob_id%7D/get/responses/200/content/application~1json/schema/%24defs/JobFailed" } ] } } } }, "401": { "$ref": "#/components/responses/InvalidAuth" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } }, "operationId": "90ca39f2-a6b1-40df-ab65-3cad4d22ee7d" } }, "/openapi": { "get": { "tags": [ "Endpoints" ], "summary": "OpenAPI spec", "description": "Return the OpenAPI spec for the TFC API.", "operationId": "2e795717-af34-4826-ba15-23bb4bfee77f", "responses": { "429": { "$ref": "#/components/responses/RateLimitWithRetryAfter" } } } }, "/warmup": { "get": { "tags": [ "Endpoints" ], "summary": "Warmup model", "description": "Warmup a model endpoint for better UX in embedded applications.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "example": "Bearer YOUR_KEY_HERE", "schema": { "type": "string" }, "description": "The `Authorization` header is used to authenticate with the API using your API key. Value is of the format `Bearer YOUR_KEY_HERE`." }, { "name": "model", "in": "query", "required": true, "description": "The forecasting model to warmup.", "schema": { "type": "string", "enum": [ "t0-alpha", "timesfm-2", "timesfm-2p5", "moirai-2", "tabpfn-ts", "tirex", "tfc-global", "aets", "aarima", "chronos-2", "tabicl", "reverso", "patchtst-fm", "toto-2" ], "default": "t0-alpha" } }, { "name": "cloud", "in": "query", "required": false, "description": "Specify the cloud provider to use. If none is set then any may be used depending on availability, including clouds not present in the below list (e.g. Oracle).", "schema": { "type": "string", "enum": [ "gcp", "aws" ] } }, { "name": "region", "in": "query", "required": false, "description": "Specify the region to use. If none is set then any may be used depending on availability, including regions not available for direct selection (such as ap or uk). Note that the region specifies the region for processing, but the request still passes through a control plane in the US.", "schema": { "type": "string", "enum": [ "us", "eu" ] } } ], "operationId": "ff53b50e-f7b2-4876-a49b-03331b7e0faa", "security": [ { "api_key": [] } ], "responses": { "429": { "$ref": "#/components/responses/RateLimitWithRetryAfter" } } } } } }