Getting started with the API

What the StockAI API is, which plans include it, the base URL, and how to make your first call end to end.

The StockAI API lets your ERP, your point of sale or a script of your own do what a person does in the app: upload sales, update stock, train, read the stock signal, log and receive purchase orders, and take approved orders out to your ERP. This section is the step-by-step guide; the full reference for every endpoint, generated from the code, is in the developer documentation.

What you can do with the API

Catalogue and inventory

Read and write stock per SKU and warehouse, suppliers, warehouses, physical counts and transfers. See Catalogue and inventory.

Forecasts and sessions

Replace the sales file, train, check training status, and read forecasts, accuracy and results. See Forecasts and sessions.

Orders and suppliers

Log orders, receive them, and take approved ones out to your ERP with a cursor. See Orders and suppliers.

Sync

Push stock from your system in idempotent batches and watch that it stays current. See Sync and files.

Webhooks

Have StockAI notify your system when an order is approved or a product is about to run out. See Webhooks.

MCP

Connect an AI assistant that reads your stock signal. See MCP.

Who can use it

The API and the MCP server are paid features. Your account's plan decides whether it has them:

On every plan with the API, each key also has a ceiling of 120 calls per minute. If your account does not include the API, creating a key, or using one that already existed, is refused with 403 and error_code: "plan_feature_locked". Within the account, analysts and administrators can create keys; a read-only user cannot.

curl https://app.stockai.es/api/v1/entitlements \
  -H "Authorization: Bearer $STOCKAI_KEY"

# "data": {
#   "tier": "pro",
#   "limits":   { "max_api_keys": 3, "max_api_calls_per_day": 2000, ... },
#   "features": { "api": true, "mcp": true, "whatsapp_bot": true },
#   "usage":    { "max_api_keys": 1, ... }
# }

GET /entitlements tells you, with the same key, which plan your account is on, its ceilings and how many keys it uses: useful for your integration to warn before it hits a limit.

The base URL and the response format

https://app.stockai.es/api/v1

If StockAI runs on your company's own server, replace app.stockai.es with its domain; everything else is the same. Every route in this guide hangs off /api/v1.

Every successful response is wrapped the same way. What you want is always inside data:

{
  "success": true,
  "data": { ... },
  "meta": { "timestamp": "2026-10-23T02:45:23.756880+00:00" }
}

An error response has no data: it carries detail (English text for people) and almost always error_code and error_params. Your code must decide on error_code, never on the text. Details in Limits and errors.

Your first call, step by step

1. Sign in to StockAI as an analyst or administrator and open Automation, "API Keys" tab.
2. Press "Generate key", type a name that says which system will use it (for example "Nightly ERP"), choose "Read only" and press "Create".
3. Copy the key with "Copy". It starts with sk_live_ and is never shown again. Store it in your system's secret manager, never in code.
4. From a terminal, call GET /planning with the key in the Authorization header:

export STOCKAI_KEY="sk_live_..."   # from your secret manager, never from the repository

curl https://app.stockai.es/api/v1/planning \
  -H "Authorization: Bearer $STOCKAI_KEY"

The response tells you at what detail (period: day, week or month) and over how many periods (horizon) everything else is computed, and above all active_session_id: the run the app computes today's stock signal from.

{
  "success": true,
  "data": {
    "period": "daily",
    "horizon": 14,
    "available_periods": ["daily", "weekly"],
    "max_horizon": 90,
    "period_source": "auto",
    "period_reason": "natural_frequency",
    "requested_period": null,
    "active_session_id": "sess_cc9ab9137953"
  },
  "meta": { "timestamp": "2026-10-23T02:45:23.756880+00:00" }
}

1. With that id you can read the stock signal: GET /inventory/status?session_id=... (the parameter is optional; without it the active session is used).
2. When the system needs to write (upload sales, log orders), create a second, "Read and write" key. See Keys and authentication.
3. Before touching real data, test against a sandbox.

Trying it without writing code

The app's API screen shows your installation's base URL, has a field to paste your key and a "Run" button on each call that really runs it against your account. It is the way to see the real shape of a response before writing anything.