API endpoint reference¶
Complete reference for the public REST API v1 (/api/v1/*). Requires
Growth+ tier and valid X-API-Key header unless noted.
Base URL: https://app.accupredix.com/api/v1 (or your deployment BFF host).
Authentication¶
All endpoints require:
X-API-Key: apx_live_<secret>
See Authentication for scopes, IP allowlists, and rotation.
Runs¶
POST /runs¶
Start a forecast run.
Body
{
"workspace_id": "ws_abc123",
"config_overrides": {}
}
Response 202 Accepted — run object with id, status, workspace_id, …
Errors: 401 invalid key · 403 workspace scope / IP block · 402 quota · 503 API disabled
POST /forecasts¶
Alias for POST /runs (Zapier/Make action name).
GET /runs¶
List runs — automation trigger (INT-005/006).
| Query | Description |
|---|---|
status |
e.g. complete, completed, failed |
since |
ISO-8601 datetime — finished after this time |
workspace_id |
Filter (must match key scope) |
Example
GET /runs?status=complete&since=2026-06-01T00:00:00Z
GET /runs/{run_id}¶
Run status, metrics, timestamps.
GET /runs/{run_id}/forecasts¶
Forecast rows for a completed run.
| Query | Default | Description |
|---|---|---|
limit |
500 | Max rows (≤ 10000) |
apply_overrides |
false | Include manual overrides in final |
Response fields (per row): unique_id, ds, q10, q50, q90, optional final, series metadata.
GET /runs/{run_id}/safety-stock/{series_id}¶
Safety stock recommendation for one series.
| Query | Default | Description |
|---|---|---|
lead_time |
1.0 | Months |
service_level |
0.95 | 0.5–0.999 |
Alerts¶
GET /alerts¶
Demand-shift alerts — automation trigger.
| Query | Default | Description |
|---|---|---|
unread |
true | Unread only |
since |
— | ISO datetime filter |
workspace_id |
— | Optional filter |
Series¶
GET /series¶
Series with changed demand trend — automation trigger.
| Query | Description |
|---|---|
trend_changed_since |
ISO datetime |
workspace_id |
Optional filter |
GET /series/{series_id}/forecast¶
Plain-language forecast for one series — automation action.
| Query | Required | Description |
|---|---|---|
run_id |
Yes | Run containing the series |
Response highlights: product_name, best_estimate, low_estimate,
high_estimate, trend_label, accuracy_score — mapped in Zapier/Make.
Error codes¶
| HTTP | Meaning |
|---|---|
| 400 | Bad query (e.g. invalid since) |
| 401 | Missing/invalid API key |
| 402 | Plan quota exceeded |
| 403 | Workspace scope, suspended org, IP allowlist |
| 404 | Run, series, or workspace not found |
| 503 | disable_public_api platform flag |
Rate limits and quota¶
- Each
POST /runscounts against monthly run quota - Growth+ may bill API overage beyond quota (Stripe meter)
- No separate rate limit header today — avoid polling faster than once per minute
Automation mapping¶
| Zapier/Make | Endpoint |
|---|---|
| Trigger: run completed | GET /runs?status=complete&since={last_poll} |
| Trigger: demand alert | GET /alerts?unread=true&since={last_poll} |
| Trigger: trend changed | GET /series?trend_changed_since={last_poll} |
| Action: trigger run | POST /forecasts or POST /runs |
| Action: series forecast | GET /series/{id}/forecast?run_id={run} |
| Action: safety stock | GET /runs/{id}/safety-stock/{series_id} |
See app-backend/integrations/README.md for field mapping notes.