Developer docs

From product feed to first query

Connect your product feed, then get ranked results back from your own server. Most of the setup happens in the Solenya Console.

View as Markdown

You need three things: a Solenya account (Solenya sets it up for you), a product feed at a public URL, and a server that can make HTTPS requests.

Building with a coding agent? Give it https://solenya.ai/llms.txt, which links every page of these docs as Markdown.

StepWhereOr over the API
1. Sign inSolenya Console, with Google or Microsoft
2. Add your feedConsole: Developer tools → Settings → Feedsadd_feed
3. Create an indexConsole: Developer tools → Settings → Indexesadd_index
4. Create an API keyConsole: Developer tools → Settings → TokensPOST /v1/auth/keys/api-key
5. Run your first queryYour server, or the Console's PlaygroundPOST /v1/graphql

Steps 2 to 4 need a signed-in team member, not an API key. The API routes for them use your session token.

1. Sign in to the Console#

Solenya creates your account and invites you. Sign in at console.solenya.ai with your Google or Microsoft work account.

2. Add your product feed#

Solenya reads your catalogue from a product feed in the Google product data format: an RSS 2.0 XML file at a URL Solenya can reach. Add the URL under Developer tools → Settings → Feeds.

The checks that most often fail a first ingest:

  • price is an amount, a space and a currency code, such as 49.99 ZAR, with no thousands separators.
  • id and item_group_id hold only letters, digits, spaces, _, - and /.
  • The URL answers a HEAD request with a 2xx status.

One invalid item fails the whole ingest. The full list is in Feeds and indexes.

3. Create an index#

An index is your searchable catalogue. Create one under Developer tools → Settings → Indexes and attach the feed. Copy the index UUID: every item query sends it in the Solenya-Index-UUID header.

Solenya fetches the feed on the index's ingest schedule, hourly by default. Your products are searchable once the first ingest has finished. To see where it stands, ask for the index's recent ingest runs:

query IngestStatus {
  indexes {
    page {
      rows {
        record {
          uuid
          name
          deployment {
            schedules {
              active
              schedule {
                cron
              }
            }
            runs(limit: 3) {
              state_type
              start_time
              end_time
            }
          }
        }
      }
    }
  }
}

A run with state_type: COMPLETED means the catalogue is in. If active is false, the schedule is off and no run will start: switch it on as shown in Ingest schedule.

4. Create an API key#

Create a secret API key for the index under Developer tools → Settings → Tokens. Solenya shows the key once, so store it in your server's secrets straight away. It can change the index, so it never goes into browser or app code.

5. Run your first query#

The quickest look is the Console's Playground: pick the index, type a search, and you see the results the API returns.

From your own server, send a POST to https://api.solenya.ai/v1/graphql with a JSON body and the three required headers. Solenya-User-UUID names the shopper; any UUID works for a first test, and Shopper IDs explains how to make one per shopper.

curl https://api.solenya.ai/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SOLENYA_API_KEY" \
  -H "Solenya-Index-UUID: $SOLENYA_INDEX_UUID" \
  -H "Solenya-User-UUID: 0193a5c2-7f4e-7b8a-9c1d-2e3f4a5b6c7d" \
  -d '{
    "query": "query FirstSearch($text: String) { items { merchant_feed(rank_with: { multimodal_query: { text: $text } }, distinct_on: { selector: item_group_id }) { page(page_size: 10) { rows { record { item_group_id title brand price image_link link } metadata { score } } page_info { has_next_page query_uuid } } } } }",
    "variables": { "text": "blue running shoes" }
  }'

The same request with fetch in Node.js or any server runtime:

TypeScript
const FIRST_SEARCH = `
  query FirstSearch($text: String) {
    items {
      merchant_feed(
        rank_with: { multimodal_query: { text: $text } }
        distinct_on: { selector: item_group_id }
      ) {
        page(page_size: 10) {
          rows {
            record { item_group_id title brand price image_link link }
            metadata { score }
          }
          page_info { has_next_page query_uuid }
        }
      }
    }
  }
`;
 
export async function firstSearch(shopperId: string, text: string) {
  const { SOLENYA_API_KEY = "", SOLENYA_INDEX_UUID = "" } = process.env;
 
  const response = await fetch("https://api.solenya.ai/v1/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${SOLENYA_API_KEY}`,
      "Solenya-Index-UUID": SOLENYA_INDEX_UUID,
      "Solenya-User-UUID": shopperId,
    },
    body: JSON.stringify({ query: FIRST_SEARCH, variables: { text } }),
  });
 
  const { data, errors } = await response.json();
  if (errors) throw new Error(errors[0].message);
  return data.items.merchant_feed.page;
}

An example response, trimmed to one row. Your products and values will differ:

JSON
{
  "data": {
    "items": {
      "merchant_feed": {
        "page": {
          "rows": [
            {
              "record": {
                "item_group_id": "ADI_GN2901_BLANK",
                "title": "Ultraboost Light running shoe",
                "brand": "adidas",
                "price": "2999.00 ZAR",
                "image_link": "https://shop.example.com/images/gn2901.jpg",
                "link": "https://shop.example.com/products/gn2901"
              },
              "metadata": { "score": 0.83 }
            }
          ],
          "page_info": {
            "has_next_page": true,
            "query_uuid": "6f1c2b8e-4d3a-4e5f-9a7b-1c2d3e4f5a6b"
          }
        }
      }
    }
  }
}

Keep query_uuid. When a shopper views, carts or buys something from this page, send it with the event so Solenya can tie the outcome to the results that led to it.

Next steps#

Live API reference#

ReferenceWhat it covers
api.solenya.ai/v1/graphqlGraphQL explorer: the schema, with a place to run queries. Add your headers under Headers first.
api.solenya.ai/v1/auth/docsToken, key and sign-in endpoints
api.solenya.ai/v1/track/docsEvent tracking endpoint