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.
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.
| Step | Where | Or over the API |
|---|---|---|
| 1. Sign in | Solenya Console, with Google or Microsoft | |
| 2. Add your feed | Console: Developer tools → Settings → Feeds | add_feed |
| 3. Create an index | Console: Developer tools → Settings → Indexes | add_index |
| 4. Create an API key | Console: Developer tools → Settings → Tokens | POST /v1/auth/keys/api-key |
| 5. Run your first query | Your server, or the Console's Playground | POST /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:
priceis an amount, a space and a currency code, such as49.99 ZAR, with no thousands separators.idanditem_group_idhold only letters, digits, spaces,_,-and/.- The URL answers a
HEADrequest 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:
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:
{
"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#
- Search and recommendations: similar products, cart suggestions, personalised browse.
- Filters and facets: narrow results and build filter sidebars.
- Event tracking: send views, cart adds and purchases from the browser.
- Errors and limits: what can go wrong, and the limits to design around.
Live API reference#
| Reference | What it covers |
|---|---|
| api.solenya.ai/v1/graphql | GraphQL explorer: the schema, with a place to run queries. Add your headers under Headers first. |
| api.solenya.ai/v1/auth/docs | Token, key and sign-in endpoints |
| api.solenya.ai/v1/track/docs | Event tracking endpoint |