Recommendation API reference

Base URL

Replace the host with your deployed Przio app origin (for example https://app.przio.com). Paths below are relative to that origin.

https://YOUR_PRZIO_HOST/api/…

Authentication

In the Przio app: Project settings → Auth token & API key → Copy auth token for Postman. Send it on every protected request:

Authorization: Bearer YOUR_TOKEN

In Postman, store the token in a collection variable (e.g. {{token}}) and set the header to Bearer {{token}}. The same token identifies your user; access is allowed only for projects where you are the creator or a member.

GET /api/sdk/recommendations is intentionally unauthenticated (browser SDK and public widgets). It still requires a valid projectId and respects the activity configuration stored for that project.

Two ways to fetch recommendations

The authenticated activity route forwards only productId, userIdentifier, limit, environment, and excludeProductId. It does not forward recommendationType or catalogId—behavior comes from the saved activity (and its catalog) only.

GET /api/sdk/recommendations

Returns recommended products for a project. Optional activityId loads an activated activity; if it is missing or invalid, the handler may fall back to another activated activity for criteria-based flows.

Query parameters

Recommendation types and required params

Activities can define a mix of behavior types; the server merges and deduplicates IDs up to the effective limit.

Example

GET /api/sdk/recommendations?projectId=YOUR_PROJECT_ID&activityId=ACTIVITY_ID&limit=8&environment=production

GET /api/sdk/recommendations?projectId=YOUR_PROJECT_ID&activityId=ACTIVITY_ID&productId=SKU-100&excludeProductId=SKU-100&limit=6

GET /api/sdk/recommendations?projectId=YOUR_PROJECT_ID&activityId=ACTIVITY_ID&userIdentifier=visitor-uuid-or-id&recommendationType=recentlyViewed&limit=10

Successful response

JSON body:

{
  "recommendations": [
    {
      "id": "SKU-123",
      "thumbnails": ["https://…"],
      "categoryPaths": ["Electronics:Phones:Smartphones"],
      "tags": ["sale"],
      …
    }
  ]
}

Each item includes id (product SKU), thumbnails, categoryPaths, tags, plus any custom fields that were stored on the product feed (keys merged into the object).

The handler shuffles the recommendations array before returning. Do not rely on a fixed order for ranking experiments unless you sort client-side.

CORS and caching

Responses include permissive CORS headers for browser GET from other origins, and Cache-Control: no-store so clients do not cache personalized lists by mistake.

Common errors (SDK route)

• 400 — Missing or invalid projectId; missing productId or userIdentifier when the chosen type requires it.
• 404 — Project not found.
• 500 — Server failure.

GET /api/product-recommendation-activities/{id}/recommendations

Same recommendation engine as the SDK route, but requires Bearer auth and checks that your user can access the activity’s project.

GET /api/product-recommendation-activities/ACTIVITY_ID/recommendations?limit=10&environment=production
Authorization: Bearer YOUR_TOKEN

Query parameters

The path {id} is the activity’s ObjectId. projectId is not passed in the query—the server loads it from the activity and forwards it internally to the SDK handler.

Successful response

{
  "recommendations": [ … ],
  "activityId": "…",
  "projectId": "…",
  "note": "…"
}

If the activity is not activated, the response may still return 200 with a note warning that results may be empty or rely on fallback behavior—activate the activity for production use.

Errors

• 401 — Access token required
• 403 — Access denied (not a member of the project)
• 404 — Activity or project not found

Recommendation activities

GET /api/product-recommendation-activities

List all recommendation activities for a project (newest first).

GET /api/product-recommendation-activities?projectId=YOUR_PROJECT_ID
Authorization: Bearer YOUR_TOKEN

Response shape: { "activities": [ … ] } — each document includes fields such as _id, name, status, recommendationType, recommendationTypes, catalogId, criteria, limit, include/exclude rules, etc.

POST /api/product-recommendation-activities

Create a draft activity. Body (JSON):

• name (required), projectId (required)
• status — optional; defaults to draft in practice when omitted
• criteria — array of rule objects
• limit — number, clamped between 1 and 50
• catalogId — optional ObjectId string
• recommendationType — one of the valid type strings; invalid values fall back to criteria

POST /api/product-recommendation-activities
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "PDP similar",
  "projectId": "YOUR_PROJECT_ID",
  "status": "draft",
  "recommendationType": "similarProduct",
  "limit": 8,
  "catalogId": "OPTIONAL_CATALOG_ID",
  "criteria": []
}

Response: { "activity": { … } } with the created document.

Catalogs

GET /api/catalogs

List catalogs for a project. Each entry includes a computed productCount.

GET /api/catalogs?projectId=YOUR_PROJECT_ID
Authorization: Bearer YOUR_TOKEN

Response: { "catalogs": [ … ] }

POST /api/catalogs

Create a catalog. Body: { "name": "Main store", "projectId": "…" }

POST /api/catalogs
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{ "name": "Main store", "projectId": "YOUR_PROJECT_ID" }

Response: { "catalog": { … } }

GET /api/catalogs/{catalogId}/products

Paginated product feed rows for merchandising and debugging.

GET /api/catalogs/CATALOG_ID/products?limit=20&skip=0
Authorization: Bearer YOUR_TOKEN

Response:

{
  "products": [
    {
      "productId": "SKU-123",
      "environment": "production",
      "thumbnails": [],
      "categoryPaths": [],
      "tags": [],
      "keys": {},
      "updatedAt": "…",
      "viewCount": 0,
      "purchaseCount": 0,
      "cartAbandonCount": 0
    }
  ],
  "total": 100,
  "hasMore": true
}

viewCount uses session-aware aggregation per product; purchase and cart counts come from visitor profiles that have those SKUs in history.

Errors and status codes (summary)

Error bodies are JSON, usually { "error": "message" }.