Developer docs
GraphQL basics
How the pieces fit together, what a request looks like, and the conventions every query shares.
How the pieces fit#
- YouProduct feedAn XML file of your products at a public URL.
- SolenyaScheduled ingestFetches the feed on the index's schedule, hourly by default.
- SolenyaIndexYour searchable catalogue, with its own ranking settings.
- Your backendItem queryA GraphQL request for search, similar products or browse.
- SolenyaResult pageRanked products, plus a query_uuid that names this page.
- Browser or appEventsViews, cart adds and purchases, carrying the query_uuid.
- SolenyaPersonalisationEach shopper's views shape the next page they see.
| Piece | What it is |
|---|---|
| Feed | Your product catalogue as a Google-format XML file at a public URL. |
| Index | A searchable copy of one feed, refreshed on a schedule, with its own ranking settings. One feed can back several indexes, for example staging and production. |
| Shopper | Someone browsing your shop, named by a UUID you create and keep. There is nothing to register: Solenya creates the shopper record the first time it sees the UUID. |
| Item | A product or variant from the feed, returned by the items query. |
Endpoint and request#
All GraphQL operations go to one endpoint:
POST https://api.solenya.ai/v1/graphqlThe body is JSON with query and, optionally, variables and operationName. Every request needs the required headers. Field and argument names are written in snake_case, exactly as in the schema.
{
"query": "query Feeds { feeds { page { rows { record { url } } } } }",
"variables": {}
}The answer is JSON with data, plus errors when something went wrong. See Errors and limits for both.
Lists and pages#
Every list (feeds, indexes, items, experiments, team members) comes back in the same wrapper. You ask for one page and read the rows inside it:
query Indexes {
indexes {
page(page_size: 25, page_number: 1) {
rows {
record {
uuid
name
}
}
page_info {
has_next_page
}
}
}
}page_sizedefaults to 25; item pages take up to 100.page_numberstarts at 1.rows[].recordholds the object itself. Some lists addrows[].metadata, such as an item's ranking score.- On item pages,
has_next_pageis true when the page came back full. A full last page also says true, and the next page is then empty. - Lists that take a filter take it as
filter_term, with the samewhere/and/or/notshape described in Filters and facets.
The GraphQL explorer#
api.solenya.ai/v1/graphql opens in the browser as an explorer: browse the schema and its descriptions, and run queries. It sends no credentials of its own, so open its Headers panel and add yours before running anything:
{
"Authorization": "Bearer <api_key>",
"Solenya-Index-UUID": "<index_uuid>",
"Solenya-User-UUID": "<user_uuid>"
}Each GraphQL example in these docs has an Open in explorer link that loads it there.
Where to go next#
| To | Read |
|---|---|
| Add feeds, create indexes, check ingests | Feeds and indexes |
| Search, show similar products, personalise | Search and recommendations |
| Narrow results and count filter options | Filters and facets |