> ## 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.
# Recommendations API
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
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.
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.
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`](#param-items) instead. `item_ids` and `items` are mutually exclusive — provide one or the other.
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`.
```json Example theme={null}
"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.
The unique identifier of the model to use.
Example: `model_baseline-v1_4jbsb1qkzFJx3tQY7hB5`
Alternatively, 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](#mock-models-for-testing) for reserved `model_id` values that return deterministic mock data and canned error responses.
The maximum number of items to return.
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.
```json Example Request (item_ids) theme={null}
{
"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"
}
}
```
```json Example Request (items with per-item context) theme={null}
{
"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"
}
}
```
```bash cURL (item_ids) theme={null}
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"
}
}'
```
```bash cURL (items) theme={null}
curl -X POST https://api.sequen.com/v1/recommend \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"user_id": "2f396d29fb98",
"items": [
{ "id": "ST678VG", "attributes": { "price": 34.99, "stock": 12 } },
{ "id": "QW1234", "attributes": { "price": 19.50, "stock": 0, "on_sale": true } }
],
"limit": 10,
"model_id": "model_baseline-v1_4jbsb1qkzFJx3tQY7hB5",
"context": {
"user_region": "US-CA",
"os_platform": "iOS",
"device_type": "mobile",
"referrer_source": "email_campaign"
}
}'
```
```json JSON Body (item_ids) theme={null}
{
"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"
}
}
```
```json JSON Body (items) theme={null}
{
"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"
}
}
```
## Response
```json Example Response theme={null}
{
"rec_id": "rec_0ujsswThIGTUYm2K8FjOOfXtY1K",
"items": [
{"id": "EC5792", "score": 0.95},
{"id": "FC7890", "score": 0.87},
{"id": "QW1234", "score": 0.78}
]
}
```
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.
A unique identifier for this specific set of recommendations.
Example: `rec_0ujsswThIGTUYm2K8FjOOfXtY1K`
```json Example Response theme={null}
{
"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_id` | Behaviour |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `test_model_item_200` | Returns `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_400` | Returns `400 Bad Request`. Useful for testing client-side validation/error handling. |
| `test_model_item_429` | Returns `429 Too Many Requests`. Useful for testing client-side backoff/retry. |
| `test_model_item_503` | Returns `503 Service Unavailable`. Useful for testing client-side fallback paths. |