API Reference

The forecast engine is a FastAPI service (forecast-api/, port 8020). Base path: /api/powerforecast/v1. OpenAPI: /docs and /openapi.json.

Endpoints

The wizard uses the asynchronous flow: POST /jobs, poll GET /jobs/{id} every 0.5 s, then /result and /diagnostics.

Stored forecasts (/runs)

Every job the engine runs (/jobs or /forecast) is also stored as a run in the product's SQLite database (/data/powerforecast.db, volume powerforecast-data): the full request (input series included), the result, the diagnostics, the status (RUNNING, DONE, FAILED), who asked (header X-PPT-User, else caller, else api) and when. Runs never expire. Redis still holds the jobs while they run and for RUN_TTL_SECONDS after; once a job left Redis, GET /jobs/{id}, /result and /diagnostics answer from the stored run, so a finished job never vanishes. GET /jobs/{id} also gives run_id.

A request with call_context: "critic" (the AI Forecast Critic's trials) is stored with kind: "trial" and left out of GET /runs unless kind=trial or kind=all.

Delete is two-step: DELETE /runs/{id} hides the run (restorable with POST /runs/{id}/restore); DELETE /runs/{id}?purge=true on a deleted run removes it for good (the history keeps its name and hash). Errors: NOT_FOUND 404, NOT_DELETED 409 (purge or restore of a run that is not deleted), TOO_LARGE 413 (a request over FORECAST_MAX_JSON_MB, 50 MB, refused by /jobs and /forecast before any work).

No sign-in check yet. Anyone who can reach the API can list, change and remove stored forecasts. Accepted until the product has its own authentication; keep backups (installation guide).

The envelope

Every response of /api/powerforecast/v1 is a PDP ProductResponseEnvelope:

{
  "jobId": "jobId_1792874861471",
  "producer": "PowerForecast",
  "status": "success | partial | failed",
  "timestamp": "2026-10-25T09:12:03.120Z",
  "execution_time_ms": 48160,
  "payload": { },
  "errors": [ { "code": "VALIDATION_ERROR", "message": "…", "recoverable": true } ],
  "trace": { "caller": "self", "call_context": "standalone" }
}

A refused or failed forecast still answers HTTP 200 with status: failed and errors[].

Request (POST /jobs, POST /forecast)

{
  "caller": "self", "call_context": "standalone",
  "name": "US retail sales 2026 budget",
  "description": "…",
  "business_target": "revenue",
  "granularity": "per_category",
  "scenario_type": "baseline",
  "frequency": "M",
  "horizon": 12,
  "confidence_level": 0.95,
  "models": null,
  "handle_missing": true,
  "handle_outliers": true,
  "data": [
    { "unique_id": "Grocery stores", "ds": ["2015-01-01", "2015-02-01", "…"], "y": [48210.0, 45102.0, "…"] }
  ]
}

Result (payload of /jobs/{id}/result)

The wizard adds data (the input series) to the saved results file, so the Results page can draw the history.

Diagnostics (payload of /jobs/{id}/diagnostics)

residual_diagnostics[] per series: residual_mean, residual_std, skewness, kurtosis, has_bias (with its p-value), is_normal (normality tests), is_uncorrelated (Ljung-Box, Durbin-Watson), is_homoscedastic (Breusch-Pagan and others), analysis_scale, failed_tests. Plus overall_quality, quality_score, recommendations, test_summary.

Example

curl -s -X POST http://localhost:8020/api/powerforecast/v1/jobs \
     -H "Content-Type: application/json" --data-binary @forecast-demos/04-us-retail-sales-budget/spec.budget.json
# -> { "status": "partial", "jobId": "jobId_…" }
curl -s http://localhost:8020/api/powerforecast/v1/jobs/jobId_…            # until "status": "success"
curl -s http://localhost:8020/api/powerforecast/v1/jobs/jobId_…/result

Jobs, results and diagnostics are kept in Redis with a time-to-live; when a job has expired, the engine can ask PowerOrchestrator for it.