Predictions endpoint

Request purchase or recommendation predictions for a specific model.

POST /client/predict/:modelName

Path parameters

Name	Type	Description
modelName	string	Model identifier (e.g. ecommerce_shopify_product_recommendations_1761946359270). Use GET /client/models to discover names.

Request headers

• Content-Type: application/json
• X-Flexsee-Api-Key: fk_xxxxxxx or Authorization: Bearer fk_xxxxxxx

Request body

{
  "input": {
    "user_id": "abc123",
    "product_id": "optional",
    "additional_feature": 42
  }
}

Notes

• user_id is required and must exist in the model's training dataset.
• product_id is optional for models that score a single product. Recommendation models ignore it and return ranked items.
• Additional keys are forwarded to the model pipeline and aligned to the trained feature order; missing values default to 0 or a sensible fallback.

Response

{
  "success": true,
  "predictions": [
    {
      "product_id": "gym-sneaker",
      "score": 0.87,
      "reason": "High engagement with similar items"
    }
  ],
  "model_info": {
    "model_name": "ecommerce_shopify_product_recommendations_1761946359270",
    "freshness_status": {
      "is_stale": false,
      "recommended_retrain": false
    },
    "api_key_prefix": "fk_cf61f039"
  }
}

When a prediction fails (e.g., unknown user), you receive a structured error:

{
  "success": false,
  "predictions": [],
  "message": "User abc123 was not in training dataset. Available users: 29"
}

Usage reporting

• Each call increments the model's usageStats.total_predictions and updates last_prediction_date.
• Billing metadata records the API key prefix/label along with the prediction count.
• Expect future rate-limit headers (X-Flexsee-Usage-Remaining).

Troubleshooting

Symptom	Action
401 Missing Flexsee API key	Ensure the header is present and not revoked.
User ... was not in training dataset	Pick a user returned by GET /client/models metadata or retrain the model.
Model 'foo' not found	Verify the modelName or refresh GET /client/models.