Get Customizations

Overview

Retrieve a list of existing recommendation customizations. This endpoint supports pagination through query parameters and additional filtering through query parameters or a criteria object in the request body.

Caution

This endpoint requires HMAC authentication. See Authentication for the signing rules.

POST https://live.luigisbox.com/v1/recommender/pin/{TRACKER_ID}/scopes

Request parameters

Send a POST request with the tracker_id in the path. Pagination and simple filters go in the query string.

Path parameters

Parameter	Type	Required	Description
TRACKER_ID	string	✓	Your unique tracker identifier.

Query parameters

Parameter	Type	Description
limit	integer	Number of customizations to return.
offset	integer	Number of results to skip.
model	array[string]	Filter by recommender model, for example model=basket&model=home.
tag	array[string]	Filter by tags.
target_type	array[string]	Filter by scope type: item, criteria, or all.
target_identity	array[string]	Filter by specific target item IDs.
sort	array[string]	Sort by attribute, for example created_at:desc.

Request headers

Header	Value	Description
Content-Type	application/json; charset=utf-8	Required.
Date	HTTP date	Required for HMAC.
Authorization	ApiAuth {TRACKER_ID}:{SIGNATURE}	Required for HMAC.

Request body

The body accepts a JSON object with a criteria array for advanced filtering. The criteria structure follows the same rules described in Recommendations Customization.

Example Request

tracker_id="1234-5678"
private_key="your_private_api_key"
host="https://live.luigisbox.com"

base_path="/v1/recommender/pin/${tracker_id}/scopes"
query_params="?model=basket&limit=10&sort=created_at:desc"
full_path="${base_path}${query_params}"

method="POST"
content_type="application/json; charset=utf-8"
date=$(date -u "+%a, %d %b %Y %H:%M:%S GMT")

string_to_sign="$(printf "${method}\n${content_type}\n${date}\n${base_path}")"
signature=$(echo -n "${string_to_sign}" | openssl dgst -sha256 -hmac "${private_key}" -binary | base64)

curl -X ${method} "${host}${full_path}" \
  -H "Content-Type: ${content_type}" \
  -H "Date: ${date}" \
  -H "Authorization: ApiAuth ${tracker_id}:${signature}" \
  -d ""

How to Make a Request

All requests to this endpoint must be authenticated with HMAC SHA-256.

1. Build the string to sign from the HTTP method, content type, current date, and the resource path.
2. Exclude query parameters from the signed path for this endpoint.
3. Generate the Base64-encoded signature with your private key.
4. Send the request with Date, Content-Type, and Authorization headers.

Code Examples

Ruby

require 'faraday'
require 'base64'
require 'openssl'
require 'time'

def generate_luigisbox_digest(private_key, http_method, endpoint_path, date_header, content_type_header)
  data = "#{http_method}\n#{content_type_header}\n#{date_header}\n#{endpoint_path}"
  hash = OpenSSL::HMAC.digest('sha256', private_key, data)
  Base64.strict_encode64(hash).strip
end

tracker_id = 'YOUR_TRACKER_ID'
private_key = 'your_private_api_key'
host = 'https://live.luigisbox.com'
base_path = "/v1/recommender/pin/#{tracker_id}/scopes"
request_path = "/v1/recommender/pin/#{tracker_id}/scopes?limit=10&offset=0&model=basket"

date_header = Time.now.utc.strftime("%a, %d %b %Y %H:%M:%S GMT")
content_type = 'application/json; charset=utf-8'
signature = generate_luigisbox_digest(private_key, 'POST', base_path, date_header, content_type)

response = Faraday.new(url: host).post(request_path) do |req|
  req.headers['Date'] = date_header
  req.headers['Content-Type'] = content_type
  req.headers['Authorization'] = "ApiAuth #{tracker_id}:#{signature}"
end

puts response.body

PHP

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

function generateLuigisboxDigest($privateKey, $httpMethod, $endpointPath, $dateHeader, $contentTypeHeader) {
    $data = "{$httpMethod}\n{$contentTypeHeader}\n{$dateHeader}\n{$endpointPath}";
    return trim(base64_encode(hash_hmac('sha256', $data, $privateKey, true)));
}

$trackerId = 'YOUR_TRACKER_ID';
$privateKey = 'your_private_api_key';
$host = 'https://live.luigisbox.com';
$basePath = "/v1/recommender/pin/{$trackerId}/scopes";
$requestPath = "/v1/recommender/pin/{$trackerId}/scopes?limit=10&offset=0&model=basket";
$contentType = 'application/json; charset=utf-8';
$date = gmdate('D, d M Y H:i:s') . ' GMT';
$signature = generateLuigisboxDigest($privateKey, 'POST', $basePath, $date, $contentType);

$client = new Client();
$response = $client->request('POST', "{$host}{$requestPath}", [
    'headers' => [
        'Content-Type' => $contentType,
        'Date' => $date,
        'Authorization' => "ApiAuth {$trackerId}:{$signature}",
    ],
]);

echo $response->getBody();

JavaScript

const axios = require('axios');
const crypto = require('crypto');

function generateLuigisBoxDigest(privateKey, httpMethod, endpointPath, dateHeader, contentTypeHeader) {
  const data = `${httpMethod}\n${contentTypeHeader}\n${dateHeader}\n${endpointPath}`;
  return crypto.createHmac('sha256', privateKey).update(data).digest('base64').trim();
}

const trackerId = 'YOUR_TRACKER_ID';
const privateKey = 'your_private_api_key';
const host = 'https://live.luigisbox.com';
const basePath = `/v1/recommender/pin/${trackerId}/scopes`;
const requestPath = `/v1/recommender/pin/${trackerId}/scopes?limit=10&offset=0&model=basket`;
const contentType = 'application/json; charset=utf-8';
const dateHeader = new Date().toUTCString();
const signature = generateLuigisBoxDigest(privateKey, 'POST', basePath, dateHeader, contentType);

axios({
  method: 'POST',
  url: `${host}${requestPath}`,
  headers: {
    'Content-Type': contentType,
    Date: dateHeader,
    Authorization: `ApiAuth ${trackerId}:${signature}`,
  },
}).then((response) => console.log(response.data));

Response structure

The response contains pagination metadata and the list of matching customization objects.

Response attributes

Field	Type	Description
pagination	object	Metadata about the result set.
pagination.total	integer	Total number of items matching the filter.
results	array	List of customization objects.

Example Response

{
  "pagination": {
    "offset": 0,
    "limit": 10
  },
  "results": [
    {
      "id": "199620b4-df1a-46e8-ab59-9e9ed9af7106",
      "model": "basket",
      "target_type": "item",
      "pin_definitions": []
    }
  ]
}

Error handling

HTTP Status	Description
200 OK	Success.
401 Unauthorized	Missing or invalid authentication.
404 Not Found	Tracker not found.
422 Unprocessable Entity	Validation error, for example an invalid sort field.

Example Error

{
  "reason": "Validation error",
  "exception_details": {
    "sort": ["Invalid sort attribute: 'unknown_field'"]
  }
}