Skip to main content

Documentation Index

Fetch the complete documentation index at: https://client-integrations-api-dev.sequen.ai/llms.txt

Use this file to discover all available pages before exploring further.

Retrieve item recommendations given a user_id and/or session_id. Recommendations combine long‑term user signals with short‑term session context to return relevant items in real time. 
POST /v1/recommend

​
Request Body

​
user_id
string
required
Unique identifier for the user. Optional if session_id is provided. Please check with our team for your specific account configuration. In some cases session_id is disabled and only user_id is supported.
​
session_id
string
required
Unique identifier for the user’s current session. Optional if user_id is provided. Please check with our team if your account supports session_id.
​
item_ids
array<string>
required
A list of item IDs to consider for recommendations.Use this field when you only need to pass item identifiers. If you need to attach per‑item context attributes (e.g. a session‑specific price), use items instead. item_ids and items are mutually exclusive — provide one or the other.
​
items
array<object>
required
A list of item objects to consider for recommendations. Use this field instead of item_ids when you want to pass item‑specific context attributes that are relevant for ranking inference (for example, the current price of an item in the user’s session, an inventory level, a promotion flag, or any other dynamic per‑item signal).Each entry must include an id and may include an attributes object holding any per‑item context the ranking model is configured to consume.Item Object Fields:
  • id (string, required): The unique identifier of the item.
  • attributes (object, optional): Per‑item context as key/value pairs. Values may be strings, numbers, booleans, or arrays of strings. Common examples include price, discount, and stock.
Example
"items": [
  { "id": "ST678VG", "attributes": { "price": 34.99, "stock": 12 } },
  { "id": "QW1234",  "attributes": { "price": 19.50, "stock": 0, "on_sale": true } }
]
The set of per‑item attributes the model actually uses is determined by your model configuration. Attribute names must match the corresponding field names in your catalog — anything else will be ignored by the ranking model. Please coordinate with our team to ensure the attributes you send are wired into ranking inference for the target model.
When the same id appears multiple times in items, response items in that duplicate group will additionally include the request attributes whose values differ across the group, so each result can be unambiguously matched back to its source row. Items whose id is unique in the request will not include these fields.
​
model_id
string
required
The unique identifier of the model to use.Example: model_baseline-v1_4jbsb1qkzFJx3tQY7hB5Alternatively, older client versions can use the model_name field instead of model_id. Please confirm with our team if you are unsure.
Need to test integration before your model is wired up? See Mock models for testing for reserved model_id values that return deterministic mock data and canned error responses.
​
limit
integer
The maximum number of items to return.
​
context
object
Optional session or user context for improved ranking. Can include fields like user_region, os_platform, device_type, referrer_source, or any custom context relevant to your use case.
Example Request (item_ids)
{
  "user_id": "2f396d29fb98",
  "item_ids": ["EC5792", "FC7890", "QW1234"],
  "limit": 10,
  "model_id": "model_baseline-v1_4jbsb1qkzFJx3tQY7hB5",
  "context": {
    "user_region": "US-CA",
    "os_platform": "iOS",
    "device_type": "mobile",
    "referrer_source": "email_campaign"
  }
}
Example Request (items with per-item context)
{
  "user_id": "2f396d29fb98",
  "items": [
    { "id": "EC5792", "attributes": { "price": 49.99, "stock": 5 } },
    { "id": "FC7890", "attributes": { "price": 12.00, "stock": 120, "on_sale": true } },
    { "id": "QW1234", "attributes": { "price": 199.00, "stock": 0 } }
  ],
  "limit": 10,
  "model_id": "model_baseline-v1_4jbsb1qkzFJx3tQY7hB5",
  "context": {
    "user_region": "US-CA",
    "os_platform": "iOS",
    "device_type": "mobile",
    "referrer_source": "email_campaign"
  }
}

curl -X POST https://api.sequen.com/v1/recommend \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "2f396d29fb98",
    "item_ids": ["ST678VG", "QW1234"],
    "limit": 10,
    "model_id": "model_baseline-v1_4jbsb1qkzFJx3tQY7hB5",
    "context": {
      "user_region": "US-CA",
      "os_platform": "iOS",
      "device_type": "mobile",
      "referrer_source": "email_campaign"
    }
  }'

​
Response

{
  "rec_id": "rec_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "items": [
    {"id": "EC5792", "score": 0.95},
    {"id": "FC7890", "score": 0.87},
    {"id": "QW1234", "score": 0.78}
  ]
}
​
items
array
An array of recommended item objects sorted by rank (highest-ranked item first).Item Object Fields:
  • id (string, required): The unique identifier of the recommended item
  • score (float, required): The recommendation score assigned by the model
  • Additional fields (optional): When the same id appears multiple times in the request, items in that duplicate group will additionally include the request attributes whose values differ across the group, so each result can be unambiguously matched back to its source row.
​
rec_id
string
A unique identifier for this specific set of recommendations.Example: rec_0ujsswThIGTUYm2K8FjOOfXtY1K
Example Response
{
  "rec_id": "rec_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "items": [
    {"id": "EC5792", "score": 0.95},
    {"id": "FC7890", "score": 0.87},
    {"id": "QW1234", "score": 0.78},
    {"id": "AB4567", "score": 0.72},
    {"id": "XY9876", "score": 0.68}
  ]
}

​
Rate Limiting

Requests are rate‑limited. If you exceed your quota, the API returns 429 Too Many Requests.

​
Response Codes

Successful response with recommendations.
Malformed JSON or invalid parameters in the request body.
Missing or invalid Authorization header in request headers.
API key lacks permission to access this endpoint.
Request timed out. Please retry with exponential backoff.
Input failed validation. Check that required fields are present and correctly formatted.
Rate limit exceeded. Please retry with exponential backoff.
Temporary server issue. Please retry with exponential backoff.

​
Mock models for testing

A small set of reserved model_id values short-circuits the ranking pipeline and returns deterministic mock data, so you can exercise the full request/response chain (auth, request decode, response encode) before your real model is wired up. The mock models honour the same request schema described above, including the attributes object and the duplicate-id echo behaviour, so they’re suitable for end-to-end integration and load tests.
model_idBehaviour
test_model_item_200Returns 200 OK with one mock-scored response item per request item, in input order. Scores are deterministic but synthetic. Honours limit, the attributes object, and the duplicate-id attribute echo described above.
test_model_item_400Returns 400 Bad Request. Useful for testing client-side validation/error handling.
test_model_item_429Returns 429 Too Many Requests. Useful for testing client-side backoff/retry.
test_model_item_503Returns 503 Service Unavailable. Useful for testing client-side fallback paths.