REST API

When to use REST?

REST is the preferred option when:

• LIM is called from a backend service

• The agent orchestration layer is not MCP-native

• You want maximum control over request timing and retries

Endpoint

POST https://lim.nosto.com/api

Authentication

Requests must include a bearer token in the header.

Authorization: Bearer xxx-xx-xxxxxxxxxxxx

API keys are merchant-specific, and partners should allow merchants to provide their token as part of the integration user experience.

Merchants can find their token by going to the Nosto Admin Portal > Account Settings > Authentication Tokens > API_LIM and click Decrypt (If as a merchant you don't see the token it's because LIM is not enabled in your account, please contact Support or your Customer Success Manager)

Request Payload

At a minimum, LIM requires the fields below:

• prompt : Free-form text describing the inferred user intent. This can be:

  • A direct user prompt

  • A normalized intent string generated by an agent

  • A short task-oriented description (e.g. “a gift for a tea lover”)

• customerId : The Nosto unique identifier representing the shopper.

  Used to enable session-level and cross-session personalization when available. Partners can get the customerId by accessing the Nosto's 2c.cId cookie for each visitor.

• partnerId (NEW): Your unique Nosto partner identifier provided by the partner management team.

• chatId (NEW): Your unique identifier for the conversation, to help answer follow up questions within a conversation

Example request:

{
  "prompt": "What dresses do you recommend for a summer party?",
  "customerId": "xxxxx",
  "partnerId": "xx-xxxxxx",
  "chatId": "xxxxx"
}

Required Fields for Shopify Merchants (NEW):

For merchants using Shopify Markets, Nosto LIM resolves the correct catalog — currency, availability, and language — based on the storefront's country and locale. To support this, partners must send two additional fields for all Shopify merchants:

• country : The ISO 3166 alpha-2 country code of the Shopify store. Supported values.

• locale : The language code of the Shopify store. Supported values.

Note: Shopify Markets merchants authenticate using the API token from their Nosto Markets Master account, not a per-storefront token. This is the single account Nosto uses to resolve catalog data across all connected markets — see Authentication.

Optional Fields:

LIM supports the following optional fields:

• Ranking-Only Mode: The /api endpoint supports a rankingOnly (boolean) flag that controls how the LLM processes product results:

  • rankingOnly: false (default): The LLM returns both a ranked selection of products and the agent response (a natural language conversational response).

  • rankingOnly: true: The LLM only ranks/selects the best matching products without generating agent insights. Using this option reduces latency.

• Max Agent Recommendations Controls: The /api endpoint supports the maxAgentRecommendations (integer | null) field that controls the number of products returned. The default is 3, and the value range is 1 to 20.

• Agent Context: The /api endpoint supports the giveAgentContext (boolean) flag. When true, LIM returns a concise context describing why LIM selected the returned products.

• Agent Insight Format: The /api endpoint supports the responseFormat (string) field to define how the natural language response is returned; by default is plain text, but for partners looking to show the response directly to shoppers, the markdown option is also supported.

Response

Nosto LIM returns a ranked list of product recommendations, suitable for direct rendering or further reasoning by an agent.

• agentInsight : A natural language conversational response (returned by default. When the flag rankingOnly is set to true, it's returned as an empty string)

Example “These shoes feature air-cushioned soles: Dr. Martens Cherry Shoe - An original 3-eye shoe with distinctive air-cushioned soles and classic Docs DNA, priced at €100. 3989 Bex Brogue - This shoe combines durability and comfort with Dr. Martens’ air-cushioned sole, priced at €120. NMD_R1 Primeknit ‘Tricolor Black’ - Offers responsive cushioning with a Boost sole, priced at €100.”

• agentContext: A concise context for agents describing why LIM selected the returned products (returned when the giveAgentContext flag is set to true)

Example: "User asks for a sweater recommendation for summer; shopping intent true; Selected in-catalog 100% cashmere sweaters as lightweight layering options; Chose 3 products from the keyword/vector summer cashmere search results"

• agentProductRecommendations : A list of products based on agentic recommendations (which combines Nosto Semantic Search, Core Recommendation Pipeline with Predictive, Semantic, and Visual AI + LLM ranking)

agentProductRecommendations (array<object> | null)
    Any of (array<object> | null)
            Items object
                productId string
                name (string | null)
                url (string | null)
                description (string | null)
                imageUrl (string | null)
                price (number | null)
                currencyCode (string | null)
                brand (string | null)
                availability (string | null)
                priceCurrencyCode (string | null)
                listPrice (number | null)
                ratingValue (number | null)
                reviewCount (integer | null)
                inventoryLevel (integer | null)
                isExcluded (boolean | null)
                onDiscount (boolean | null)
                skus (array<object> | null)
                    Any of (array<object> | null)
                        Items object
                            id string
                            inventoryLevel (integer | null)
                            availability (string | null)
                            name(string | null)