{"openapi":"3.1.0","info":{"title":"Stokis API","version":"v1","description":"Read-only API for a Stokis workspace: products, suppliers, purchase orders, sales and forecasts. Needs an API key (sk_live_…) that the workspace owner creates in Settings › Developers, on the Scale plan or during the 30-day trial."},"externalDocs":{"url":"https://stokis.io/docs/api"},"servers":[{"url":"https://stokis.io/api/v1"}],"security":[{"apiKey":[]}],"paths":{"/":{"get":{"operationId":"getApiRoot","summary":"Check your key","description":"Answers 200 with the API version and its resources when the key works. Use it to test a new key.","parameters":[],"responses":{"200":{"description":"Check your key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiRoot"},"example":{"object":"api","version":"v1","documentation":"https://stokis.io/docs/api","resources":["products","suppliers","purchase-orders","sales","forecasts"]}}}},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/products":{"get":{"operationId":"listProducts","summary":"List products","description":"Newest first.","parameters":[{"name":"limit","in":"query","required":false,"description":"Items per page, 1–100. Default 50.","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Items to skip. Default 0.","schema":{"type":"integer"}}],"responses":{"200":{"description":"List products","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","limit","offset"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"has_more":{"type":"boolean","description":"More items after this page."},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"example":{"object":"list","data":[{"object":"product","id":"m2x8c4q9v1z7b3n5k0w6r8ty","sku":"TEA-EG-250","name":"Earl Grey loose leaf tea 250 g","reference":"EG250","barcode":"4771234567890","stock":42,"min_stock":20,"max_stock":120,"status":"ok","cost":{"amount":"3.40","currency":"EUR"},"category_path":"Tea/Black tea","supplier_id":"k3v9qz2m8xw1r7c4p6n0bd5t","is_active":true,"created_at":"2026-03-02T09:14:00.000Z","updated_at":"2026-11-16T06:02:11.000Z"}],"has_more":false,"limit":2,"offset":0}}}},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/products/{id}":{"get":{"operationId":"getProduct","summary":"Retrieve a product","description":"One product by its Stokis id.","parameters":[{"name":"id","in":"path","required":true,"description":"The product's Stokis id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Retrieve a product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"},"example":{"object":"product","id":"m2x8c4q9v1z7b3n5k0w6r8ty","sku":"TEA-EG-250","name":"Earl Grey loose leaf tea 250 g","reference":"EG250","barcode":"4771234567890","stock":42,"min_stock":20,"max_stock":120,"status":"ok","cost":{"amount":"3.40","currency":"EUR"},"category_path":"Tea/Black tea","supplier_id":"k3v9qz2m8xw1r7c4p6n0bd5t","is_active":true,"created_at":"2026-03-02T09:14:00.000Z","updated_at":"2026-11-16T06:02:11.000Z"}}}},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/suppliers":{"get":{"operationId":"listSuppliers","summary":"List suppliers","description":"By name, A to Z.","parameters":[{"name":"limit","in":"query","required":false,"description":"Items per page, 1–100. Default 50.","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Items to skip. Default 0.","schema":{"type":"integer"}}],"responses":{"200":{"description":"List suppliers","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","limit","offset"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Supplier"}},"has_more":{"type":"boolean","description":"More items after this page."},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"example":{"object":"list","data":[{"object":"supplier","id":"k3v9qz2m8xw1r7c4p6n0bd5t","name":"Nordic Leaf Trading","email":"orders@nordicleaf.example","country":"DE","default_currency":"EUR","lead_time_days":10,"tier":"preferred","status":"active","on_time_percent":92,"reliability_score":95,"reliability_grade":"excellent","created_at":"2026-02-20T11:00:00.000Z"}],"has_more":false,"limit":2,"offset":0}}}},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/suppliers/{id}":{"get":{"operationId":"getSupplier","summary":"Retrieve a supplier","description":"One supplier by its Stokis id.","parameters":[{"name":"id","in":"path","required":true,"description":"The supplier's Stokis id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Retrieve a supplier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"},"example":{"object":"supplier","id":"k3v9qz2m8xw1r7c4p6n0bd5t","name":"Nordic Leaf Trading","email":"orders@nordicleaf.example","country":"DE","default_currency":"EUR","lead_time_days":10,"tier":"preferred","status":"active","on_time_percent":92,"reliability_score":95,"reliability_grade":"excellent","created_at":"2026-02-20T11:00:00.000Z"}}}},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/purchase-orders":{"get":{"operationId":"listPurchaseOrders","summary":"List purchase orders","description":"Newest first, without lines.","parameters":[{"name":"limit","in":"query","required":false,"description":"Items per page, 1–100. Default 50.","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Items to skip. Default 0.","schema":{"type":"integer"}}],"responses":{"200":{"description":"List purchase orders","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","limit","offset"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrder"}},"has_more":{"type":"boolean","description":"More items after this page."},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"example":{"object":"list","data":[{"object":"purchase_order","id":"p7n2w9c4x1v8m3q6z0k5r2hb","number":"PO-2026-0042","status":"received","source":"auto","supplier_id":"k3v9qz2m8xw1r7c4p6n0bd5t","currency":"EUR","total_amount":"340.00","expected_at":"2026-11-10T00:00:00.000Z","sent_at":"2026-10-31T08:30:00.000Z","received_at":"2026-11-09T13:20:00.000Z","created_at":"2026-10-30T07:00:00.000Z"}],"has_more":false,"limit":2,"offset":0}}}},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/purchase-orders/{id}":{"get":{"operationId":"getPurchaseOrder","summary":"Retrieve a purchase order","description":"One order with its lines.","parameters":[{"name":"id","in":"path","required":true,"description":"The purchase order's Stokis id.","schema":{"type":"string"}}],"responses":{"200":{"description":"Retrieve a purchase order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrderDetail"},"example":{"object":"purchase_order","id":"p7n2w9c4x1v8m3q6z0k5r2hb","number":"PO-2026-0042","status":"received","source":"auto","supplier_id":"k3v9qz2m8xw1r7c4p6n0bd5t","currency":"EUR","total_amount":"340.00","expected_at":"2026-11-10T00:00:00.000Z","sent_at":"2026-10-31T08:30:00.000Z","received_at":"2026-11-09T13:20:00.000Z","created_at":"2026-10-30T07:00:00.000Z","lines":[{"id":"l4c8x2v6n1m9q3z7w0k5r8bp","sku":"TEA-EG-250","name":"Earl Grey loose leaf tea 250 g","qty":100,"qty_received":100,"unit_cost":{"amount":"3.40","currency":"EUR"}}]}}}},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/sales/{sku}":{"get":{"operationId":"getSalesHistory","summary":"Daily sales for a SKU","description":"The last 90 days. An unknown SKU gives an empty data array, not 404.","parameters":[{"name":"sku","in":"path","required":true,"description":"The product's SKU, exactly as in the store.","schema":{"type":"string"}}],"responses":{"200":{"description":"Daily sales for a SKU","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesHistory"},"example":{"object":"sales_history","sku":"TEA-EG-250","window_days":90,"data":[{"date":"2026-11-14","qty":3},{"date":"2026-11-15","qty":5},{"date":"2026-11-16","qty":2}]}}}},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/forecasts":{"get":{"operationId":"listForecasts","summary":"List forecasts","description":"By SKU, without the daily series.","parameters":[{"name":"limit","in":"query","required":false,"description":"Items per page, 1–100. Default 50.","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Items to skip. Default 0.","schema":{"type":"integer"}}],"responses":{"200":{"description":"List forecasts","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","limit","offset"],"properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Forecast"}},"has_more":{"type":"boolean","description":"More items after this page."},"limit":{"type":"integer"},"offset":{"type":"integer"}}},"example":{"object":"list","data":[{"object":"forecast","sku":"TEA-EG-250","horizon_days":30,"forecast_qty":118,"demand_qty":96,"last_computed_at":"2026-11-17T02:00:00.000Z"}],"has_more":false,"limit":2,"offset":0}}}},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/forecasts/{sku}":{"get":{"operationId":"getForecast","summary":"Forecast for a SKU","description":"One SKU's forecast with its daily series.","parameters":[{"name":"sku","in":"path","required":true,"description":"The product's SKU, exactly as in the store.","schema":{"type":"string"}}],"responses":{"200":{"description":"Forecast for a SKU","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForecastDetail"},"example":{"object":"forecast","sku":"TEA-EG-250","horizon_days":30,"forecast_qty":118,"demand_qty":96,"last_computed_at":"2026-11-17T02:00:00.000Z","daily_series":{"observed":[3,0,4,5,2],"projected":[3,3,3,3,3]}}}}},"401":{"$ref":"#/components/responses/Error401"},"402":{"$ref":"#/components/responses/Error402"},"404":{"$ref":"#/components/responses/Error404"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Authorization: Bearer sk_live_…"}},"schemas":{"Money":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"string","description":"Decimal amount as a string with two decimals, e.g. \"9.90\"."},"currency":{"type":"string","description":"ISO 4217 currency code, e.g. \"EUR\"."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","message"],"properties":{"type":{"type":"string"},"message":{"type":"string"}}}}},"ApiRoot":{"type":"object","required":["object","version","documentation","resources"],"properties":{"object":{"type":"string","enum":["api"],"description":"Always \"api\"."},"version":{"type":"string","description":"API version, \"v1\"."},"documentation":{"type":"string","description":"This reference."},"resources":{"type":"array","items":{"type":"string"},"description":"Resource names under the base URL."}}},"Product":{"type":"object","required":["object","id","sku","name","reference","barcode","stock","min_stock","max_stock","status","cost","category_path","supplier_id","is_active","created_at","updated_at"],"properties":{"object":{"type":"string","enum":["product"],"description":"Always \"product\"."},"id":{"type":"string","description":"Stokis id of the product."},"sku":{"type":"string","description":"SKU from the store. A combination or variation is its own product."},"name":{"type":"string","description":"Product name."},"reference":{"type":["string","null"],"description":"The store's product reference."},"barcode":{"type":["string","null"],"description":"EAN/UPC barcode."},"stock":{"type":"integer","description":"Units in stock as Stokis last recorded them. 0 when status is untracked."},"min_stock":{"type":["integer","null"],"description":"Minimum stock level."},"max_stock":{"type":["integer","null"],"description":"Maximum stock level."},"status":{"type":"string","enum":["ok","low","out_of_stock","untracked","paused"],"description":"paused: deactivated in Stokis; untracked: the store keeps no stock level; out_of_stock: stock is 0 or less; low: stock below min_stock; otherwise ok."},"cost":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"Unit cost price."},"category_path":{"type":["string","null"],"description":"Category path from the store, e.g. \"Tea/Black tea\"."},"supplier_id":{"type":["string","null"],"description":"Id of the product's supplier."},"is_active":{"type":"boolean","description":"false when the product is paused."},"created_at":{"type":"string","format":"date-time","description":"When Stokis first saw the product."},"updated_at":{"type":"string","format":"date-time","description":"When Stokis last updated the product."}}},"Supplier":{"type":"object","required":["object","id","name","email","country","default_currency","lead_time_days","tier","status","on_time_percent","reliability_score","reliability_grade","created_at"],"properties":{"object":{"type":"string","enum":["supplier"],"description":"Always \"supplier\"."},"id":{"type":"string","description":"Stokis id of the supplier."},"name":{"type":"string","description":"Supplier name."},"email":{"type":["string","null"],"description":"Ordering email address."},"country":{"type":["string","null"],"description":"Country."},"default_currency":{"type":"string","description":"ISO 4217 code, the default currency of this supplier's orders."},"lead_time_days":{"type":["integer","null"],"description":"Quoted lead time in days."},"tier":{"type":"string","enum":["preferred","standard","probation","blocked"],"description":"Tier the merchant gave the supplier."},"status":{"type":"string","enum":["active","paused"],"description":"Whether the supplier is active or paused in Stokis."},"on_time_percent":{"type":["integer","null"],"description":"Share of received purchase orders with an expected date that arrived on or before it, 0–100. null with none."},"reliability_score":{"type":["integer","null"],"description":"0–100, from on-time delivery, fill rate and reply time. null below 3 received orders with an expected date."},"reliability_grade":{"type":["string","null"],"enum":["excellent","good","fair","at-risk",null],"description":"Band of reliability_score: excellent 90+, good 75+, fair 60+, otherwise at-risk."},"created_at":{"type":"string","format":"date-time","description":"When the supplier was added."}}},"PurchaseOrder":{"type":"object","required":["object","id","number","status","source","supplier_id","currency","total_amount","expected_at","sent_at","received_at","created_at"],"properties":{"object":{"type":"string","enum":["purchase_order"],"description":"Always \"purchase_order\"."},"id":{"type":"string","description":"Stokis id of the purchase order."},"number":{"type":"string","description":"Purchase order number, e.g. \"PO-2026-0042\"."},"status":{"type":"string","enum":["draft","awaiting","sent","confirmed","received","cancelled","bounce"],"description":"Usual path: draft → awaiting (approval) → sent → confirmed → received. cancelled can happen before that; bounce: sending the email failed."},"source":{"type":"string","enum":["auto","manual"],"description":"auto: drafted by Stokis; manual: created by a person."},"supplier_id":{"type":"string","description":"Id of the supplier."},"currency":{"type":"string","description":"ISO 4217 currency of the order."},"total_amount":{"type":"string","description":"Order total as a decimal string, in currency."},"expected_at":{"type":["string","null"],"format":"date-time","description":"Expected delivery."},"sent_at":{"type":["string","null"],"format":"date-time","description":"When it was sent to the supplier."},"received_at":{"type":["string","null"],"format":"date-time","description":"When it was received."},"created_at":{"type":"string","format":"date-time","description":"When the order was created."}}},"PurchaseOrderDetail":{"type":"object","required":["object","id","number","status","source","supplier_id","currency","total_amount","expected_at","sent_at","received_at","created_at","lines"],"properties":{"object":{"type":"string","enum":["purchase_order"],"description":"Always \"purchase_order\"."},"id":{"type":"string","description":"Stokis id of the purchase order."},"number":{"type":"string","description":"Purchase order number, e.g. \"PO-2026-0042\"."},"status":{"type":"string","enum":["draft","awaiting","sent","confirmed","received","cancelled","bounce"],"description":"Usual path: draft → awaiting (approval) → sent → confirmed → received. cancelled can happen before that; bounce: sending the email failed."},"source":{"type":"string","enum":["auto","manual"],"description":"auto: drafted by Stokis; manual: created by a person."},"supplier_id":{"type":"string","description":"Id of the supplier."},"currency":{"type":"string","description":"ISO 4217 currency of the order."},"total_amount":{"type":"string","description":"Order total as a decimal string, in currency."},"expected_at":{"type":["string","null"],"format":"date-time","description":"Expected delivery."},"sent_at":{"type":["string","null"],"format":"date-time","description":"When it was sent to the supplier."},"received_at":{"type":["string","null"],"format":"date-time","description":"When it was received."},"created_at":{"type":"string","format":"date-time","description":"When the order was created."},"lines":{"type":"array","items":{"type":"object","required":["id","sku","name","qty","qty_received","unit_cost"],"properties":{"id":{"type":"string","description":"Line id."},"sku":{"type":"string","description":"SKU at the time of ordering."},"name":{"type":"string","description":"Product name at the time of ordering."},"qty":{"type":"integer","description":"Units ordered."},"qty_received":{"type":"integer","description":"Units received so far."},"unit_cost":{"anyOf":[{"$ref":"#/components/schemas/Money"},{"type":"null"}],"description":"Unit cost in the order's currency."}}},"description":"Order lines."}}},"SalesHistory":{"type":"object","required":["object","sku","window_days","data"],"properties":{"object":{"type":"string","enum":["sales_history"],"description":"Always \"sales_history\"."},"sku":{"type":"string","description":"The SKU asked for."},"window_days":{"type":"integer","description":"Days covered, always 90."},"data":{"type":"array","items":{"type":"object","required":["date","qty"],"properties":{"date":{"type":"string","format":"date","description":"Day, YYYY-MM-DD."},"qty":{"type":"integer","description":"Units sold that day."}}},"description":"One entry per day with a sales record, oldest first. Empty for an unknown SKU."}}},"Forecast":{"type":"object","required":["object","sku","horizon_days","forecast_qty","demand_qty","last_computed_at"],"properties":{"object":{"type":"string","enum":["forecast"],"description":"Always \"forecast\"."},"sku":{"type":"string","description":"SKU."},"horizon_days":{"type":"integer","description":"Days the forecast covers (30)."},"forecast_qty":{"type":"integer","description":"Suggested order quantity: demand over the horizon plus the lead-time and safety buffer."},"demand_qty":{"type":["integer","null"],"description":"Expected units sold over the horizon, before the buffer."},"last_computed_at":{"type":"string","format":"date-time","description":"When the forecast was last computed."}}},"ForecastDetail":{"type":"object","required":["object","sku","horizon_days","forecast_qty","demand_qty","last_computed_at","daily_series"],"properties":{"object":{"type":"string","enum":["forecast"],"description":"Always \"forecast\"."},"sku":{"type":"string","description":"SKU."},"horizon_days":{"type":"integer","description":"Days the forecast covers (30)."},"forecast_qty":{"type":"integer","description":"Suggested order quantity: demand over the horizon plus the lead-time and safety buffer."},"demand_qty":{"type":["integer","null"],"description":"Expected units sold over the horizon, before the buffer."},"last_computed_at":{"type":"string","format":"date-time","description":"When the forecast was last computed."},"daily_series":{"type":"object","required":["observed","projected"],"properties":{"observed":{"type":"array","items":{"type":"number"},"description":"Units sold per day in the sales window used, oldest first."},"projected":{"type":"array","items":{"type":"number"},"description":"Projected units per day over the horizon."}},"description":"Daily units behind the forecast."}}}},"responses":{"Error401":{"description":"The Authorization header is missing, or the key is malformed, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"type":"auth_error","message":"Invalid or revoked API key."}}}}},"Error402":{"description":"The key is valid, but its workspace is not on the Scale plan and not in its 30-day trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"type":"auth_error","message":"The public API requires the Scale plan."}}}}},"Error404":{"description":"No product, supplier, purchase order or forecast with that id or SKU in the key's workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"type":"not_found","message":"Product not found"}}}}},"RateLimited":{"description":"More than 30 requests in a minute from one IP address to one path.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time in milliseconds when the window resets.","schema":{"type":"integer"}}},"content":{"application/json":{"example":{"error":"Too many requests","retryAfter":42,"limit":30,"remaining":0,"reset":"2026-11-17T09:30:42.000Z"}}}}}}}