Navigation

Export Customizations

Export all existing customizations for a tracker.

Overview

Important This endpoint requires HMAC authentication.

Export all existing customizations for a tracker. This endpoint allows bulk retrieval of all pinning rules, which is useful for backups, audits, or synchronization.

Authentication

This endpoint requires HMAC authentication. You must include the Date and Authorization headers. See Authentication for details.

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

Request Parameters

To export customizations, send a POST request to the export endpoint. You can filter the results using query parameters.

Path Parameters

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

Query Parameters

Parameter Type Required Description
model String Filter export by recommender model.
tag String Filter by a specific tag.
target_type String Filter by scope type (item, criteria, all).
target_identity String Filter by a specific item ID (requires target_type=item).
remove_expired_pins Boolean If true, excludes pins that are past their active_to date.
remove_nonexisting_item_pins Boolean If true, checks if pinned item IDs still exist in the catalog and excludes them if not.

Request Headers

Header Value Description
Content-Type application/json Required.
Date HTTP Date Required for HMAC.
Authorization Signature Required for HMAC.

Example Request

tracker_id="1234-5678"
private_key="your_private_api_key"
host="https://live.luigisbox.tech"
base_path="/v1/recommender/pin/${tracker_id}/scopes/export"
full_path="${base_path}?model=basket&target_type=item"
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}"

How to make a request

All requests to this endpoint must be authenticated using HMAC SHA-256. The examples on the right demonstrate the implementation in various languages, but the core logic follows these steps:

1. Construct the String to Sign

Create a string using the following components, separated by newlines (\n):

  1. HTTP Method: POST
  2. Content-Type: application/json; charset=utf-8
  3. Date: The current timestamp in RFC 1123 format (e.g., Mon, 20 Jan 2025 12:00:00 GMT).
  4. Request Path: The resource path excluding query parameters.

2. Generate the HMAC Signature

  1. Create an HMAC SHA-256 hash of the string above using your Private API Key.
  2. Encode the result in Base64 and trim whitespace.

3. Send the Headers

Include Date, Content-Type, and Authorization: ApiAuth {TRACKER_ID}:{SIGNATURE} in your request.

Example Code

require 'faraday'
require 'base64'
require 'openssl'
require 'json'
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.tech'



# Base path for signing (Exclude query parameters)
base_path = "/v1/recommender/pin/#{tracker_id}/scopes/export"
# Full URL with query parameters
request_full_path = "/v1/recommender/pin/#{tracker_id}/scopes/export?model=basket&target_type=item"



conn = Faraday.new(url: host)



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



# Sign only the base path
signature = generate_luigisbox_digest(private_key, http_method, base_path, date_header, content_type)
authorization_header = "ApiAuth #{tracker_id}:#{signature}"



response = conn.post(request_full_path) do |req|
  req.headers['Date'] = date_header
  req.headers['Content-Type'] = content_type
  req.headers['Authorization'] = authorization_header
end



puts response.body

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


use GuzzleHttp\Client;



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



$TRACKER_ID       = "YOUR_TRACKER_ID";
$YOUR_PRIVATE_KEY = "your_private_api_key";
$LUIGISBOX_HOST   = 'https://live.luigisbox.tech';



$BASE_PATH        = "/v1/recommender/pin/{$TRACKER_ID}/scopes/export";
$REQUEST_FULL_PATH = "/v1/recommender/pin/{$TRACKER_ID}/scopes/export?model=basket&target_type=item";



$http_method  = 'POST';
$content_type = 'application/json; charset=utf-8';
$current_date = gmdate('D, d M Y H:i:s') . ' GMT';



$signature = generateLuigisboxDigest($YOUR_PRIVATE_KEY, $http_method, $BASE_PATH, $current_date, $content_type);
$authorization_header = "ApiAuth {$TRACKER_ID}:{$signature}";



$client = new GuzzleHttp\Client();
$response = $client->request($http_method, "{$LUIGISBOX_HOST}{$REQUEST_FULL_PATH}", [
        'headers' => [
            'Content-Type'  => $content_type,
            'Date'          => $current_date,
            'Authorization' => $authorization_header,
        ]
    ]);



echo $response->getBody();
?>

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


function generateLuigisBoxDigest(privateKey, httpMethod, endpointPath, dateHeader, contentTypeHeader) {
  const data = </span><span class="p">${</span><span class="nx">httpMethod</span><span class="p">}</span><span class="s2">\n</span><span class="p">${</span><span class="nx">contentTypeHeader</span><span class="p">}</span><span class="s2">\n</span><span class="p">${</span><span class="nx">dateHeader</span><span class="p">}</span><span class="s2">\n</span><span class="p">${</span><span class="nx">endpointPath</span><span class="p">}</span><span class="s2">;
  const hmac = crypto.createHmac('sha256', privateKey);
  hmac.update(data);
  return hmac.digest('base64').trim();
}



const TRACKER_ID = "YOUR_TRACKER_ID";
const YOUR_PRIVATE_KEY = "your_private_api_key";
const LUIGISBOX_HOST = 'https://live.luigisbox.tech';



const BASE_PATH = /v1/recommender/pin/</span><span class="p">${</span><span class="nx">TRACKER_ID</span><span class="p">}</span><span class="s2">/scopes/export;
const REQUEST_FULL_PATH = /v1/recommender/pin/</span><span class="p">${</span><span class="nx">TRACKER_ID</span><span class="p">}</span><span class="s2">/scopes/export?model=basket&amp;target_type=item;



const httpMethod = 'POST';
const contentType = 'application/json; charset=utf-8';
const dateHeader = new Date().toUTCString();



const signature = generateLuigisBoxDigest(YOUR_PRIVATE_KEY, httpMethod, BASE_PATH, dateHeader, contentType);
const authorizationHeader = ApiAuth </span><span class="p">${</span><span class="nx">TRACKER_ID</span><span class="p">}</span><span class="s2">:</span><span class="p">${</span><span class="nx">signature</span><span class="p">}</span><span class="s2">;



axios({
  method: httpMethod,
  url: </span><span class="p">${</span><span class="nx">LUIGISBOX_HOST</span><span class="p">}${</span><span class="nx">REQUEST_FULL_PATH</span><span class="p">}</span><span class="s2">,
  headers: {
    'Content-Type': contentType,
    'Date': dateHeader,
    'Authorization': authorizationHeader
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Response Structure

The response is a JSON object containing the list of all matching customizations.

Response Attributes

Field Type Description
results Array List of customization objects.

The Response Object

{
  "results": [
    {
      "id": "199620b4-df1a-46e8-ab59-9e9ed9af7106",
      "model": "basket",
      "target_type": "item"
    },
    {
      "id": "b3e6e3c1-1a3b-4c2d-8e4f-2a3b4c5d6e7f",
      "model": "basket",
      "target_type": "all"
    }
  ]
}

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 (e.g., invalid sort attribute).

Error Responses

{
  "reason": "Validation error",
  "exception_details": {
    "target_type": ["Must be one of: item, criteria, all"]
  }
}