API overview¶

The public Forecast REST API lets external systems trigger runs and read results. Available on Growth+ tiers (API keys required).

Base URL¶

https://<your-bff-host>/api/v1

Production example: https://app.accupredix.com/api/v1

Authentication¶

All requests require an API key header:

X-API-Key: apx_live_xxxxxxxx

Create keys in the app under API keys (/api-keys, admin+). Keys may be scoped to a single workspace or org-wide.

See Authentication for scopes, IP allowlists, and errors. Full endpoint reference: API endpoints.

Quick start¶

1. Trigger a run¶

POST /api/v1/runs
Content-Type: application/json
X-API-Key: apx_live_xxx

{
  "workspace_id": "ws_abc123",
  "config_overrides": {}
}

Returns 202 Accepted with run object (id, status, …).

2. Poll until complete¶

GET /api/v1/runs/{run_id}
X-API-Key: apx_live_xxx

Repeat until status is completed or failed.

3. Fetch forecasts¶

GET /api/v1/runs/{run_id}/forecasts?limit=5000
X-API-Key: apx_live_xxx

Optional: apply_overrides=true to include manual overrides.

Endpoints summary¶

Method	Path	Description
`POST`	`/runs`	Start forecast run
`GET`	`/runs`	List runs (`status`, `since`, `workspace_id`)
`GET`	`/runs/{id}`	Run status and metrics
`GET`	`/runs/{id}/forecasts`	Forecast rows (quantiles per series/month)
`GET`	`/runs/{id}/safety-stock/{series_id}`	Safety stock recommendation
`GET`	`/alerts`	Demand-shift alerts (`unread`, `since`)
`GET`	`/series`	Series with trend changes
`GET`	`/series/{id}/forecast`	Plain-language forecast for one series
`POST`	`/forecasts`	Alias to trigger run (automation)

Rate limits and quota¶

Runs count against the org monthly run limit.
API runs beyond quota may be metered as overage on Growth+ (Stripe meter when configured).
Platform flag disable_public_api blocks all public API calls (maintenance).

Errors¶

Code	Meaning
`401`	Missing or invalid API key
`403`	Key not authorized for workspace; IP allowlist block
`402`	Plan quota exceeded (no overage)
`404`	Run or workspace not found
`503`	Public API disabled globally

OpenAPI¶

Signed-in admins see the live OpenAPI schema from API keys in the app. This document covers the stable v1 surface used by Zapier/Make integrations.

Automation examples¶

See app-backend/integrations/README.md in the repository for Zapier/Make field mapping notes.