Raccomando Client API

Use the Raccomando Client API to power search, autocomplete, and recommendations in your storefront.

Base URL

https://api.raccomando.ai

Authentication

Pass an active client API key using the X-API-Key header.
Include X-Request-ID for traceability (optional).

X-API-Key: rck_live_<keyId>.<secret>
X-Request-ID: 99f2d0bf-f3d8-4f28-9dcf-1af5aa7c4ca2

Response format

All responses use a standard envelope with requestId and payload metadata.

{
  "apiVersion": "v1",
  "requestId": "99f2d0bf-f3d8-4f28-9dcf-1af5aa7c4ca2",
  "data": {},
  "meta": {}
}

Runtime endpoints

POST/client/v1/search

Run a ranked product search for a customer query.

GET/client/v1/suggest

Fetch autocomplete suggestions for a partial query.

POST/client/v1/recommend

Return recommendation candidates for an anchor, cart, or query.

POST/client/v1/events

Submit interaction events such as impressions and clicks.

POST/client/v1/events/single

Submit a single interaction event.

Search

`POST /client/v1/search`

Run semantic search and ranking with optional filter and pipeline settings.

{
  "query": "dry red under 20 euro",
  "sessionId": "sess-123",
  "page": 0,
  "size": 20,
  "filter": {
    "clauses": [
      {
        "scope": "ATTRIBUTE",
        "field": "country",
        "operator": "EQ",
        "valueType": "STRING",
        "values": ["france"]
      },
      {
        "scope": "CORE",
        "field": "price",
        "operator": "RANGE",
        "valueType": "NUMBER",
        "min": 0,
        "max": 20
      }
    ]
  }
}

{
  "apiVersion": "v1",
  "requestId": "99f2d0bf-f3d8-4f28-9dcf-1af5aa7c4ca2",
  "data": {
    "hits": [
      {
        "id": "f4546d03-f3a9-4c03-a97d-901f9ec7f6d4",
        "externalId": "81",
        "title": "2024 Doisy-Daene Bordeaux Blanc",
        "imageUrl": "https://cdn.example.com/81.jpg",
        "status": true,
        "price": 24.50,
        "attributes": { "country": "france", "region": "bordeaux" },
        "score": 0.717
      }
    ],
    "pageInfo": { "page": 0, "size": 20, "totalElements": 1, "totalPages": 1 },
    "queryFeedback": {
      "originalQuery": "wijn uit frankrijk",
      "parsedQuery": "wijn",
      "extractedFilter": {
        "clauses": [
          {
            "scope": "ATTRIBUTE",
            "field": "country",
            "operator": "EQ",
            "valueType": "STRING",
            "values": ["frankrijk"],
            "min": null,
            "max": null
          }
        ]
      }
    }
  },
  "meta": { "page": 0, "size": 20, "totalElements": 1, "totalPages": 1 }
}

Suggest

`GET /client/v1/suggest?query=bor&sessionId=sess-123&size=8`

{
  "apiVersion": "v1",
  "requestId": "8f72556e-3f34-4e6e-93a8-f72e287a5fd4",
  "data": {
    "items": [
      {
        "query": "Bordeaux",
        "label": "Bordeaux",
        "kind": "PRODUCT_TITLE",
        "productId": "f4546d03-f3a9-4c03-a97d-901f9ec7f6d4",
        "attributeKey": null
      },
      {
        "query": "Bordeaux",
        "label": "Region: Bordeaux",
        "kind": "ATTRIBUTE_VALUE",
        "productId": null,
        "attributeKey": "region"
      }
    ]
  }
}

Recommend

`POST /client/v1/recommend`

{
  "strategyId": "10f2e7c8-9d56-4277-9f3a-986af577d786",
  "anchorProductId": "f4546d03-f3a9-4c03-a97d-901f9ec7f6d4",
  "cartProductIds": [],
  "query": null,
  "context": { "slot": "pdp" },
  "filters": { "country": "france" },
  "limit": 12
}

{
  "apiVersion": "v1",
  "requestId": "9a8fab42-4f7f-49ce-97e4-a298a6e16db0",
  "data": {
    "items": [
      {
        "productId": "ec5c7f34-3ef4-4ab1-a5af-0baec9eef757",
        "score": 1.283,
        "title": "Chateau Carbonnieux Rouge",
        "price": 19.95
      }
    ]
  }
}

Events

`POST /client/v1/events`

{
  "events": [
    {
      "type": "IMPRESSION",
      "productId": "ec5c7f34-3ef4-4ab1-a5af-0baec9eef757",
      "sessionId": "sess-123",
      "payload": { "strategyId": "10f2e7c8-9d56-4277-9f3a-986af577d786" },
      "timestamp": "2026-02-16T10:40:32"
    },
    {
      "type": "CLICK",
      "productId": "ec5c7f34-3ef4-4ab1-a5af-0baec9eef757",
      "sessionId": "sess-123",
      "payload": { "position": 1 },
      "timestamp": "2026-02-16T10:40:40"
    }
  ]
}

{
  "apiVersion": "v1",
  "requestId": "1e7c6b95-f548-4dd7-980f-41834516c290",
  "data": {
    "ingestedCount": 2
  }
}

Error responses

Check the HTTP status and request payload details for diagnostics.

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "X-API-Key header is required",
  "instance": "https://api.raccomando.ai/client/v1/search"
}