The StockAI API and MCP server

Almost everything you do inside StockAI can also be done through the API: upload sales, train and read the forecast, read the traffic light, record orders, manage suppliers and warehouses. Connect it to your ERP, your POS or any system of your own. And with the MCP server, Claude, ChatGPT or your own AI assistant does it in conversation with you.

Base URL
https://app.stockai.es/api/v1
MCP server
https://app.stockai.es/api/v1/mcp
Authentication
Authorization: Bearer sk_live_…
Endpoints
308 documented176 read132 write
GET/api/v1/planning
Request
curl "$STOCKAI/planning" \
  -H "Authorization: Bearer $STOCKAI_KEY"
Response
200 OK application/json
{
  "success": true,
  "data": {},
  "meta": {
    "timestamp": "2026-10-02T08:00:00Z"
  }
}

Authentication

Every call carries an API key in the Authorization header. Keys are created in the app, under Automation → API Keys, and shown once: StockAI stores only a hash.

shell
export STOCKAI=https://app.stockai.es/api/v1
export STOCKAI_KEY=sk_live_…

curl "$STOCKAI/planning" \
  -H "Authorization: Bearer $STOCKAI_KEY"

A key acts as itself, not as the person who created it: it keeps working if that person leaves the company.

Read keys and write keys

When you create a key you choose what it may do. Every endpoint in the reference says which kind of key it needs.

ReadReads everything a viewer sees: traffic light, forecasts, suppliers, orders, reports.
Read and writeAlso creates and changes, like an analyst: uploads files, trains, records orders, edits inventory and suppliers.

A read key that tries to write gets 403 with error_code api_key_scope_insufficient, and nothing changes.

What a key can never do

Some actions belong to people, not systems. With an API key they answer 403 api_key_route_not_exposed:

  • Sign in, refresh tokens or recover passwords.
  • Create, invite or change users and their permissions.
  • Create, list or revoke API keys: a key cannot mint another.
  • Configure the installation or the account's channels.
  • Export or delete the account.
  • What belongs to one person: their inbox, their assistant conversations, their preferences.
  • What only an administrator can do (for example, change the currency or the active period).

Sending an order or an alert by email or WhatsApp with a write key requires the account to have at least one administrator with a verified email (otherwise: 403 api_key_tenant_unverified).

Limits

Authentication
/ min120 calls per minute per key.
APIThe API and the MCP server come with the Pro, Max and Corporate plans; the Free plan does not include them.

Over the limit you get 429 with a Retry-After header (seconds). The same 429 serves the per-minute limit and the daily cap, and its body has no error_code.

There are no X-RateLimit-* headers: the only signal is the 429 with Retry-After. Count your own calls or wait for the 429.

Metering and purchase

The API comes with the Pro (2,000 calls a day per key), Max (20,000) and Corporate (no daily cap) plans. We count every API-key call that reached an endpoint, by day (UTC) and by key; refused calls (invalid key, no permission or over the limit) do not count. An administrator sees the month's usage in the app, on the API screen.

Errors

Almost every error carries a stable error_code and, where it applies, error_params with the values: branch on the code, not on the detail text, which is an English hint and may change. The framework's own answers (missing header, unknown route, wrong method) and the 429 carry only detail.

api_key_invalid401 the key does not exist, was revoked or has expired.
api_key_route_not_exposed403 that endpoint cannot be called with an API key.
api_key_scope_insufficient403 the key is read-only and the endpoint writes.
api_key_tenant_unverified403 sending anything outside StockAI needs a verified administrator.
validation_error422 the body or parameters are invalid; detail is a list with one object per field.
PLAN_LIMIT_REACHED403 a usage ceiling was reached; detail is an object and error_params says which.
server_busy503 the server is saturated; retry after Retry-After.
(no error_code)401 the Authorization header is missing or is not “Bearer sk_live_…”: detail is “Not authenticated”.
(no error_code)429 per-minute limit or daily cap: wait Retry-After seconds.
(no error_code)404 / 405 unknown route or method not allowed.

The shape of detail

stringMost errors: one English sentence.
list422 validation_error: [{ type, loc, msg, input }], one per invalid field; loc says where (for example ["body", "name"]).
objectPLAN_LIMIT_REACHED: { code, limit, current, max, tier }, the same content as error_params.
403 Example: a read key that writes
{
  "detail": "This endpoint writes and the API key is read-only. Use a write key.",
  "error_code": "api_key_scope_insufficient",
  "error_params": { "required_scope": "write", "key_scope": "read" }
}

Response format

Every JSON response is wrapped: { "success": true, "data": …, "meta": { "timestamp": … } }. Your payload is in data, which is an object or a list depending on the endpoint; paginated lists carry their list in data.items.

200 application/json
{
  "success": true,
  "data": {},
  "meta": {
    "timestamp": "2026-10-02T08:00:00Z"
  }
}

Endpoints that return a file (Excel, PDF, CSV) answer with the file itself, with no wrapper.

The MCP endpoint (POST /mcp) speaks JSON-RPC 2.0 and does not use this wrapper.

Types and formats

DatesDates are YYYY-MM-DD; instants are ISO 8601 in UTC, for example 2026-10-01T08:00:00+00:00.
NumbersQuantities and amounts are JSON numbers, not strings. Amounts are in the account's currency (GET /tenant/currency).
Empty valuesA field with no value usually arrives as null instead of being omitted.
IdentifiersOpaque prefixed strings (sess_…, ds_…, sup_…): store them as they are.
SignalsThe traffic light uses PEDIR_YA, PEDIR_PRONTO, OK and SOBRESTOCK: fixed values that are not translated.

Pagination

There are three forms, and each endpoint declares its own in its parameters:

skip and limitSessions, session summaries, data sources and datasets. The response has items, total, skip and limit.
limit and offsetAlert activity (/alerts/activity). The response has items, total, limit and offset.
limit onlyNewest first, up to limit: alerts, order history, setup gaps, shrinkage and retraining history.
no paginationThe rest return the whole set and are narrowed with their filters, for example signal or supplier on /inventory/status.

Idempotency

POST /inventory/log-po and POST /inventory/po accept the Idempotency-Key header: one unique value (a UUID) per order you mean to place. Repeating the request with the same key returns the order that was already created (200 with replayed: true) instead of a second one; the same key with different lines answers 409 po_idempotency_key_reused. Every other write endpoint is not idempotent: before retrying a write whose result you did not see, check whether it was applied.

HTTP
Idempotency-Key: 3f1c9a5e-7d62-4b0e-9d6a-2c8f4a1b5e70

StockAI in your AI assistant (MCP)

StockAI connects to Claude, ChatGPT and any AI assistant that speaks MCP (Model Context Protocol). Over that connection the assistant can do what the API does, in conversation with you: tell you what to order, draft and send purchase orders, check forecast accuracy or start a retrain. You approve the changes.

MCP server
https://app.stockai.es/api/v1/mcp
Access
Sign in with your StockAI account (OAuth) or use an API key
Tools
Together they reach all 307 API operations21 read8 write

What you can ask

  • "What do I need to order today, and why?"
  • "Draft the order for Distribuidora Andina with the suggested quantities."
  • "Send the Distribuidora Andina order to the supplier."
  • "How accurate was last month's forecast?"
  • "Which products are overstocked, and how much money is sitting in them?"
  • "Retrain the forecast with this week's sales."

How your account stays safe

Read or writeWith read access the assistant only looks. To create or change anything it needs write access: the same rule as the API.
Confirmation for destructive actionsAn action that cannot be undone, such as cancelling an order, is refused unless it arrives with confirm: true. The assistant asks you before sending it.
Metered and recordedEvery call counts toward API usage, under the same per-minute limit, and every change lands in the account's activity log.
RevocableYou withdraw access from the app whenever you want, and the next call no longer gets in.
What it never doesNothing an API key cannot do: no users, no keys, no installation settings.
PlansIt comes with the Pro, Max and Corporate plans, like the API.

Connect your client

The same URL works for all of them. Pick your client:

  1. In claude.ai open Customize → Connectors, click "+ Add" and choose "Add custom connector".
  2. Name it StockAI, paste the URL below and click "Add". Nothing is needed under "Advanced settings".
  3. Click "Connect" next to StockAI. Claude takes you to StockAI: sign in with your account and approve the access.
  4. Turn it on in a chat from "+" → Connectors. Claude Desktop shows it too, because connectors belong to your Claude account.
URL
https://app.stockai.es/api/v1/mcp

On Claude Team and Enterprise plans, an Owner adds the connector in Organization settings → Connectors; each person then clicks "Connect".

Technical details

  • Stateless Streamable HTTP transport: every message is a POST with JSON-RPC 2.0 and the answer comes back on the same POST. A GET answers 405: the server does not open a stream to the client.
  • It shares the API's per-minute limit and daily cap, and answers 429 with Retry-After when you go over.
  • A tool that refuses answers with an error the assistant can read, with its error_code, not with a transport failure.
  • Protocol revision: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05.

Tools

Generated from the server itself: if a tool is listed here, your assistant sees it. The tools in the "The whole API" group search, describe and call any operation in the endpoint reference.

29 tools: 21 read and 8 write (4 destructive, which ask for confirmation).

Planning 3

get_planning_contextReadStart here. Returns which forecast session is active, at what granularity (daily/weekly/monthly) and over how many periods the numbers in the other tools were computed. `active_session_id` is what the other tools accept as `session_id`; read it each time rather than storing it, because it changes when a new run trains.
Arguments

No arguments.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_planning_context",
    "arguments": {}
  }
}
get_morning_briefingReadThe day's purchasing work: the risks worth acting on, the reason behind each recommendation, the suggested supplier and the estimated value. This is the tool for "what should I buy today?"; get_inventory_status is for "what is the state of X?".
Arguments
  • session_idstringoptional

    Forecast session to read. Omit it to use the tenant's active session — the same one the StockAI app is showing on screen.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_morning_briefing",
    "arguments": {}
  }
}
get_purchase_planReadThe purchase plan grouped by supplier, after the constraints are applied (MOQ, order multiples, joint replenishment, budget). Use it for "what should I order from each supplier?" — it returns what to buy per supplier with quantities and values, not the per-SKU traffic light.
Arguments
  • session_idstringoptional

    Forecast session to read. Omit it to use the tenant's active session — the same one the StockAI app is showing on screen.

  • window_daysintegeroptionalmin 1max 90

    How far ahead a product counts as 'needs ordering soon' when grouping a supplier's order.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_purchase_plan",
    "arguments": {}
  }
}

Inventory 3

get_inventory_statusReadThe stock traffic light for every product: what state it is in and how much to order. Signals: PEDIR_YA (order now), PEDIR_PRONTO (order soon), OK, SOBRESTOCK (too much), SIN_DATOS (no stock on record — which means unknown, NOT safe). Per row, `recommended_qty` is how much to order, `coverage_days` how long the stock lasts at the forecast rate, and `lead_time_source` / `unit_cost_source` / `moq_source` say where each assumption came from: `user` (typed into StockAI), `file` (their own export), `supplier_rule`, `learned` (from their receptions) or `default` (StockAI had nothing and assumed). Treat a `default` as an assumption when you report it, not as the customer's own figure. Answers are capped and ordered by urgency; `summary` always counts the whole matching set, and `truncated` says when rows were left out. Filter with `signal` or `supplier` rather than raising `limit` when you can. If a filter matches nothing the answer carries `empty_reason`. That is the filter finding nothing, NOT a catalogue with nothing to order — never report stock as fine on the strength of it.
Arguments
  • session_idstringoptional

    Forecast session to read. Omit it to use the tenant's active session — the same one the StockAI app is showing on screen.

  • signalenumoptional

    Return only SKUs carrying this signal.

    PEDIR_YAPEDIR_PRONTOOKSOBRESTOCKSIN_DATOS
  • supplierstringoptional

    Return only SKUs whose supplier matches this name.

  • limitintegeroptionalmin 1max 500default 50

    How many SKUs to return, most urgent first.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_inventory_status",
    "arguments": {
      "signal": "PEDIR_YA",
      "limit": 20
    }
  }
}
search_productsReadFind products in the stock catalogue by SKU, category or supplier text, with stock on hand, minimum, lead time, cost and supplier per row. Paged: `total` says how many matched. Use it to find the exact SKU code before calling a per-SKU tool.
Arguments
  • querystringoptional

    Text matched against SKU, category or supplier.

  • warehousestringoptional

    Only this warehouse's rows.

  • limitintegeroptionalmin 1max 500default 50
  • offsetintegeroptionalmin 0default 0
Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": {
      "query": "oil",
      "limit": 10
    }
  }
}
get_sku_detailReadEverything about one SKU in one call: its traffic-light signal, coverage and recommended order quantity from the active forecast (`signal_and_recommendation`), and its stock record — on hand, minimum, lead time, cost, MOQ and supplier (`stock_record`). Use the exact SKU code (search_products finds it).
Arguments
  • skustringrequired

    The exact SKU code.

  • session_idstringoptional

    Forecast session to read. Omit it to use the tenant's active session — the same one the StockAI app is showing on screen.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_sku_detail",
    "arguments": {
      "sku": "SKU-001"
    }
  }
}

Purchase orders 7

list_purchase_ordersReadThe tenant's purchase orders, newest first, with number, supplier, status, value, sent and reception state. Paged (`limit`/`offset`); filter by `status` or search the order number with `query`. get_purchase_order returns one order's lines.
Arguments
  • statusstringoptional

    Status filter, e.g. all, pending, received (default all).

  • querystringoptional

    Matches the PO number.

  • limitintegeroptionalmin 1max 100default 50
  • offsetintegeroptionalmin 0default 0
Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_purchase_orders",
    "arguments": {}
  }
}
get_purchase_orderReadOne purchase order's lines: SKU, ordered and received quantities, unit cost and supplier. `po_log_id` comes from list_purchase_orders.
Arguments
  • po_log_idstringrequired

    The order's id.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_purchase_order",
    "arguments": {}
  }
}
list_overdue_purchase_ordersReadOrders whose expected arrival date has passed without a full reception, with how many days late each is. The list to chase suppliers with.
Arguments

No arguments.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_overdue_purchase_orders",
    "arguments": {}
  }
}
create_purchase_orderDestructive · asks for confirmationRecords a purchase order written by hand: one supplier, the lines typed in, no forecast behind it. DESTRUCTIVE: a recorded order cannot be voided through the API and its units start counting as stock on the way. Without `confirm: true` it only describes what it would record. It does NOT send anything to the supplier (send_purchase_order does). Get `supplier_id` from list_suppliers.
Arguments
  • supplier_idstringrequired

    The supplier's id.

  • linesarray of objectrequired
    Each list item
    • skustringrequired
    • qtynumberrequiredmin > 0
    • unit_costnumberoptionalmin 0
  • destination_warehousestringoptional

    Warehouse it goes to (default: the default warehouse).

  • idempotency_keystringoptional

    Optional. A unique value (a UUID) for this one order. Retrying with the same value returns the order already created instead of creating a second one.

  • confirmbooleanoptional

    Must be true for this to run. Without it nothing changes and the answer describes exactly what would happen — show that to the person and only repeat the call with confirm: true after they agree.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_purchase_order",
    "arguments": {
      "supplier_id": "<supplier_id>",
      "lines": [
        {
          "sku": "SKU-001",
          "qty": 24,
          "unit_cost": 3.5
        }
      ]
    }
  }
}
send_purchase_orderDestructive · asks for confirmationEmails and WhatsApps the order's PDF to each of its suppliers and marks it sent. DESTRUCTIVE: a message that left cannot be recalled. Without `confirm: true` it only describes what it would send. Lines whose supplier has no contact details are reported as not sent.
Arguments
  • po_log_idstringrequired

    The order's id.

  • request_confirmationbooleanoptionaldefault false

    Ask the supplier to confirm the date.

  • confirmbooleanoptional

    Must be true for this to run. Without it nothing changes and the answer describes exactly what would happen — show that to the person and only repeat the call with confirm: true after they agree.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "send_purchase_order",
    "arguments": {}
  }
}
receive_purchase_orderWriteRecords that an order arrived — fully (no `lines`) or partially (the received quantity per SKU). Stock on hand rises by the received units and the supplier's real lead time is learned. Reversible: the REST operation post-inventory-po-po_log_id-unreceive undoes it.
Arguments
  • po_log_idstringrequired

    The order's id.

  • linesarray of objectoptional

    Received quantity per SKU. Omit for a full reception.

    Each list item
    • skustringrequired
    • received_qtynumberrequiredmin 0
  • received_atstringoptional

    ISO date it arrived (default: today).

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "receive_purchase_order",
    "arguments": {}
  }
}

Suppliers 3

list_suppliersReadThe tenant's suppliers with id, contact details, lead time and payment terms. Paged; `query` matches name, phone or email. The `id` is what create_purchase_order takes as `supplier_id`.
Arguments
  • querystringoptional
  • limitintegeroptionalmin 1max 200default 50
  • offsetintegeroptionalmin 0default 0
Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_suppliers",
    "arguments": {}
  }
}
get_supplier_scorecardReadHow each supplier actually performs: promised vs learned lead time, on-time and fill rate from the receptions recorded. Use it to answer "which supplier is reliable?".
Arguments

No arguments.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_supplier_scorecard",
    "arguments": {}
  }
}
create_supplierWriteAdds a supplier with contact details, lead time and payment terms. Returns the new supplier with its id. Not destructive: a supplier can be edited or deactivated later.
Arguments
  • namestringrequired
  • emailstringoptional
  • phonestringoptional
  • whatsappstringoptional
  • lead_time_daysintegeroptionalmin 1max 365
  • payment_termsstringoptional
  • notesstringoptional
Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_supplier",
    "arguments": {
      "name": "Distribuidora Andina",
      "lead_time_days": 7
    }
  }
}

Forecasts 2

get_sku_forecastReadThe demand forecast for one SKU: past actuals and forecast values per period, with the prediction interval and the model that produced it. Periods are in the session's granularity (get_planning_context says which).
Arguments
  • skustringrequired

    The exact SKU code.

  • session_idstringoptional

    Forecast session to read. Omit it to use the tenant's active session — the same one the StockAI app is showing on screen.

  • modelstringoptional

    Only this model's forecast (default: the selected one).

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_sku_forecast",
    "arguments": {
      "sku": "SKU-001"
    }
  }
}
get_forecast_accuracyReadHow accurate the forecast session is: error metrics overall and per SKU, compared against simple baselines, and which SKUs are least reliable. Use it before trusting a recommendation for a product with a large error.
Arguments
  • session_idstringoptional

    Forecast session to read. Omit it to use the tenant's active session — the same one the StockAI app is showing on screen.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_forecast_accuracy",
    "arguments": {}
  }
}

Training 3

list_sessionsReadThe tenant's forecast sessions (training runs) with id, name, status, dataset and dates, newest first. `status` filters, e.g. COMPLETED, RUNNING, FAILED.
Arguments
  • querystringoptional

    Search name, description or dataset.

  • statusarray of stringoptional
  • limitintegeroptionalmin 1max 500default 20
  • offsetintegeroptionalmin 0default 0
Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_sessions",
    "arguments": {}
  }
}
get_training_statusReadWhether a forecast session has finished training. `status` goes QUEUED -> RUNNING -> COMPLETED or FAILED. Useful to say whether the numbers being read are the latest run or the previous one.
Arguments
  • session_idstringrequired

    The session to report on. Required.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_training_status",
    "arguments": {}
  }
}
start_trainingWriteQueues a training run for a configured session, or a retrain of a completed one (same configuration, current data). Returns at once; poll get_training_status. Training takes minutes and counts against the plan's job limits.
Arguments
  • session_idstringrequired
  • horizon_daysintegeroptionalmin 1max 365

    How many days ahead to forecast.

  • granularityenumoptional
    autodailyweeklymonthly
Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "start_training",
    "arguments": {}
  }
}

Data 2

list_data_sourcesReadThe sales-history sources this tenant's forecasts are trained on, with the id, the file name and when each was last updated. Use it to answer whether the numbers are based on fresh data.
Arguments
  • limitintegeroptionalmin 1max 200default 50

    How many sources to return.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_data_sources",
    "arguments": {}
  }
}
upload_sales_csvWriteCreates a NEW data source from sales history given as CSV text (header row first; columns such as date, sku, quantity). StockAI detects the columns. It replaces nothing: existing sources and forecasts are untouched. Train on it by creating a session that uses it.
Arguments
  • csv_textstringrequired

    The CSV file's full content.

  • filenamestringoptional

    File name to store (default sales.csv).

  • namestringoptional

    Name for the data source.

  • descriptionstringoptional
Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "upload_sales_csv",
    "arguments": {
      "csv_text": "date,sku,quantity\n2026-10-01,SKU-001,12\n",
      "name": "October sales"
    }
  }
}

Reports 1

get_dashboard_summaryReadThe headline numbers of the inventory dashboard for a forecast session: how many SKUs are in each signal, the value to order, stock value and coverage. One call for "how are we doing?".
Arguments
  • session_idstringoptional

    Forecast session to read. Omit it to use the tenant's active session — the same one the StockAI app is showing on screen.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_dashboard_summary",
    "arguments": {}
  }
}

Alerts 1

list_alertsReadThe tenant's recent alerts (stockouts coming, overdue orders, failed runs, data problems), newest first.
Arguments
  • limitintegeroptionalmin 1max 100default 20
Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_alerts",
    "arguments": {}
  }
}

The whole API 4

search_operationsReadFinds any of StockAI's ~300 public API operations by text, beyond the curated tools: warehouses, transfers, stock counts, demand events, scenarios, webhooks, reports, data-source SQL, inventory sync and more. Returns operation ids with a one-line summary and their kind (read / write / destructive), paginated. Then describe_operation, then call_operation or call_write_operation.
Arguments
  • querystringoptional

    Words to match, e.g. "transfer warehouse".

  • tagstringoptional

    Only this API area (e.g. inventory, sessions, webhooks).

  • kindenumoptional
    readwritedestructive
  • limitintegeroptionalmin 1max 50default 20
  • offsetintegeroptionalmin 0default 0
Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_operations",
    "arguments": {
      "query": "transfer",
      "kind": "read"
    }
  }
}
describe_operationReadEverything needed to call one operation: method and path, each parameter with its type, the request body's shape, the scope it needs, whether it is destructive (and why), and ready-to-use example arguments for call_operation / call_write_operation.
Arguments
  • operation_idstringrequired
Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "describe_operation",
    "arguments": {
      "operation_id": "get-inventory-transfers"
    }
  }
}
call_operationReadRuns any READ operation of the public API by id (kind=read in search_operations), exactly as the REST API would with this connection's credential. Large answers are cut with a note saying how to page; file downloads are described, not returned. Operations that change data are refused here — they run through call_write_operation.
Arguments
  • operation_idstringrequired

    The operation id from search_operations, e.g. "get-inventory-stock-sku".

  • path_paramsobjectoptional

    Values for the {placeholders} in the operation's path.

    Free-form object: it declares no fields.

  • queryobjectoptional

    Query parameters, by name. Only the operation's declared ones.

    Free-form object: it declares no fields.

  • bodyanyoptional

    JSON body, for the few read operations that take one (previews, simulations).

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_operation",
    "arguments": {
      "operation_id": "get-inventory-stock-sku",
      "path_params": {
        "sku": "SKU-001"
      }
    }
  }
}
call_write_operationDestructive · asks for confirmationRuns any operation that CHANGES data (kind=write or destructive in search_operations), exactly as the REST API would with this connection's credential; needs a write-scope credential. A destructive operation (every delete, recording or sending a purchase order, overwriting stock, and the others describe_operation marks) does not run without `confirm: true`: without it the answer states exactly what would happen and nothing changes. Form uploads take the file in `body` as its text, or as {filename, content | content_base64}.
Arguments
  • operation_idstringrequired

    The operation id from search_operations, e.g. "get-inventory-stock-sku".

  • path_paramsobjectoptional

    Values for the {placeholders} in the operation's path.

    Free-form object: it declares no fields.

  • queryobjectoptional

    Query parameters, by name. Only the operation's declared ones.

    Free-form object: it declares no fields.

  • bodyanyoptional

    The JSON body (object or list), or for a form upload an object of form fields.

  • idempotency_keystringoptional

    Sent as Idempotency-Key, for operations that accept one: a retry with the same value does not act twice.

  • confirmbooleanoptional

    Must be true for this to run. Without it nothing changes and the answer describes exactly what would happen — show that to the person and only repeat the call with confirm: true after they agree.

Example call
POST /api/v1/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "call_write_operation",
    "arguments": {
      "operation_id": "post-inventory-warehouses",
      "body": {
        "name": "North warehouse"
      }
    }
  }
}

Endpoint reference

Generated from the service itself: if an endpoint is listed here, it can be called with an API key. Example responses are real calls to a test account.

POST Explain a SKU's recommendation
AI narratives

Explain a SKU's recommendation

POST/api/v1/ai/narrative/forecast-explanation
Read keyReturns 200 · application/json

Explains a specific SKU's inventory signal and recommendation in plain language.

Request

Headers
  • AuthorizationBearer sk_live_…required

    Your API key. Always required.

  • Content-Typeapplication/jsonrequired
Body

application/jsonThe body is required.

object An object.
  • skustringrequired
  • session_idstringrequired
  • profilestringoptionaldefault "distributor"
  • languagestringoptionaldefault "es"

Responses

200 On success

No example response was captured for this endpoint. Every JSON answer comes in this envelope; what data holds depends on the endpoint.

Possible errors

Besides the errors of each endpoint, any call made with a key can answer:

  • 401Authorization header missing, or API key invalid, revoked or expired.
  • 403Key may not call this endpoint, is read-only on a write, or a permission check refused it.
  • 429Per-minute limit or daily ceiling reached; honour Retry-After.
  • 422Validation Error
Errors
Request
curl -X POST "$STOCKAI/ai/narrative/forecast-explanation" \
  -H "Authorization: Bearer $STOCKAI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sku":"SKU-001","session_id":"<session_id>","profile":"distributor","language":"es"}'
Response
200 OK application/json
{
  "success": true,
  "data": {},
  "meta": {
    "timestamp": "2026-10-02T08:00:00Z"
  }
}

Put your own AI to work forecasting your sales. Today.

Three ways to start, depending on how much you want to commit right now. All three lead to the same product.

Create your account

With the whole engine. Upload your sales file and see your first forecast, and with it your first list of what to order.

Create my account

Look before giving your email

An instant trial account with sample data. It lasts 24 hours and is then erased.

Try it without signing up

Talk to us

For the corporate plan, the source code, or to see it with your data and someone beside you. We answer within 24 hours.

Sales and contact: contacto@stockai.es. Phone: +506 7186 2820.

Sales forecasting made in Costa Rica, for companies across Latin America.