List AI recommendations enriched with shopName, brandId, collectionId, and sizeIds for direct plan creation

curl --request GET \
  --url https://app.solya.app/api/intelligence/recommendations/full \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "allowedActions": [
        "restock"
      ],
      "brandId": "brand-uuid-adidas",
      "collectionId": "coll-uuid-fw25",
      "createdAt": "2025-09-15T06:00:00.000Z",
      "deficit_units": 12,
      "domain": "restock",
      "forbiddenActions": [],
      "scores": {
        "deficit_score": null,
        "overstock_risk": 0.05,
        "restock_urgency": 0.91,
        "stockout_risk": 0.85,
        "surplus_score": null,
        "transfer_urgency": null
      },
      "shopId": "shop-uuid-paris",
      "shopName": "Paris Flagship",
      "sizeIds": [
        "size-uuid-40",
        "size-uuid-41",
        "size-uuid-42"
      ],
      "snapshotDate": "2025-09-15",
      "surplus_units": null,
      "updatedAt": "2025-09-15T06:00:00.000Z",
      "variantId": "var-uuid-001"
    },
    {
      "allowedActions": [
        "rebalance"
      ],
      "brandId": "brand-uuid-nike",
      "collectionId": null,
      "createdAt": "2025-09-15T06:00:00.000Z",
      "deficit_units": null,
      "domain": "rebalance",
      "forbiddenActions": [],
      "scores": {
        "deficit_score": 0.2,
        "overstock_risk": null,
        "restock_urgency": null,
        "stockout_risk": null,
        "surplus_score": 0.8,
        "transfer_urgency": 0.75
      },
      "shopId": "shop-uuid-lyon",
      "shopName": "Lyon Bellecour",
      "sizeIds": [
        "size-uuid-m",
        "size-uuid-l"
      ],
      "snapshotDate": "2025-09-15",
      "surplus_units": 8,
      "updatedAt": "2025-09-15T06:00:00.000Z",
      "variantId": "var-uuid-002"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 1240
  },
  "success": true
}

Intelligence

List AI recommendations enriched with shopName, brandId, collectionId, and sizeIds for direct plan creation

BFF-style aggregate list endpoint that extends the base /intelligence/decision-vectors response with plan-context enrichments: shopName (human-readable label), and sizeIds (available size taxonomy IDs for that variant in that shop, from the stock snapshot layer). brandId and collectionId are already present on the base decision vector. An agent can use this endpoint to discover what to restock/rebalance/markdown and immediately construct a plan — variantId, shopId, brandId, collectionId, and sizeIds are all available in one call. sizeIds is the list of taxonomy size IDs with stock in the specific variant/shop pair; pass each as sizeId when adding items to an inventory plan. Filter by domain, variantId, or shopId. Per-shop access scoping is enforced. Returns the flat envelope: { success, data: [...], meta: { total, page, pageSize } }.

GET

api

intelligence

recommendations

full

List AI recommendations enriched with shopName, brandId, collectionId, and sizeIds for direct plan creation

curl --request GET \
  --url https://app.solya.app/api/intelligence/recommendations/full \
  --header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "allowedActions": [
        "restock"
      ],
      "brandId": "brand-uuid-adidas",
      "collectionId": "coll-uuid-fw25",
      "createdAt": "2025-09-15T06:00:00.000Z",
      "deficit_units": 12,
      "domain": "restock",
      "forbiddenActions": [],
      "scores": {
        "deficit_score": null,
        "overstock_risk": 0.05,
        "restock_urgency": 0.91,
        "stockout_risk": 0.85,
        "surplus_score": null,
        "transfer_urgency": null
      },
      "shopId": "shop-uuid-paris",
      "shopName": "Paris Flagship",
      "sizeIds": [
        "size-uuid-40",
        "size-uuid-41",
        "size-uuid-42"
      ],
      "snapshotDate": "2025-09-15",
      "surplus_units": null,
      "updatedAt": "2025-09-15T06:00:00.000Z",
      "variantId": "var-uuid-001"
    },
    {
      "allowedActions": [
        "rebalance"
      ],
      "brandId": "brand-uuid-nike",
      "collectionId": null,
      "createdAt": "2025-09-15T06:00:00.000Z",
      "deficit_units": null,
      "domain": "rebalance",
      "forbiddenActions": [],
      "scores": {
        "deficit_score": 0.2,
        "overstock_risk": null,
        "restock_urgency": null,
        "stockout_risk": null,
        "surplus_score": 0.8,
        "transfer_urgency": 0.75
      },
      "shopId": "shop-uuid-lyon",
      "shopName": "Lyon Bellecour",
      "sizeIds": [
        "size-uuid-m",
        "size-uuid-l"
      ],
      "snapshotDate": "2025-09-15",
      "surplus_units": 8,
      "updatedAt": "2025-09-15T06:00:00.000Z",
      "variantId": "var-uuid-002"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 1240
  },
  "success": true
}

Authorizations

Authorization

string

header

required

User session token issued by NextAuth. For human users accessing Solya via the web application.

Query Parameters

page

integer

default:1

Page number, 1-indexed (default: 1)

Required range: 1 <= x <= 9007199254740991

pageSize

integer

default:20

Number of items per page, max 100 (default: 20)

Required range: 1 <= x <= 100

variantId

string

Filter by variant ID

shopId

string

Filter by shop ID

domain

enum<string>

Filter by decision domain: restock, rebalance, or markdown

Available options:

restock,

rebalance,

markdown

Response

Successful response

data

object[]

required

Page of items

Show child attributes