Quickstart

Get up and running in five steps.

Step 1: Prepare Your Product Feed

Your feed must conform to the Google Product Feed specification as advised by Google Merchant Center. Solenya ingests the feed directly via URL, so it must be publicly accessible (or accessible to Solenya's ingest service).

Key requirements:

• Format: RSS 2.0 or Atom 1.0 XML, or a Google Sheets-based feed
• Required fields: id, title, description, link, image_link, availability, price, brand
• Recommended fields: item_group_id, sale_price, product_type, size, color
• The URL must remain stable; Solenya re-fetches it on your configured schedule

Once your feed is live and returning valid XML, copy the URL.

Step 2: Add Your Feed

Register your feed URL with Solenya using the add_feed mutation:

mutation AddFeed {
  add_feed(feed_url: "https://example.com/feed.xml") {
    url
  }
}

You can verify it was registered by querying your feeds:

query GetFeeds {
  feeds {
    page(page_size: 10, page_number: 1) {
      rows {
        record {
          url
        }
      }
    }
  }
}

Step 3: Create an Index and Configure the Ingest Schedule

An index is the queryable view over your feed. Create one and attach your feed:

mutation AddIndex {
  add_index(
    feed_list: ["https://example.com/feed.xml"]
    ingest_schedule: "0 * * * *"
  ) {
    uuid
  }
}

ingest_schedule is a cron expression; "0 * * * *" runs hourly. Save the returned uuid; you'll need it as the Solenya-Index-UUID header on all item queries.

To confirm successful ingestion, query the index and check for associated feeds:

query GetIndexes {
  indexes {
    page(page_size: 10, page_number: 1) {
      rows {
        record {
          uuid
          feeds {
            url
          }
        }
      }
    }
  }
}

Once the first ingest runs (within the first hour by default), your catalog items will be available.

Step 4: Obtain an API Key

Access tokens are short-lived JWTs (2 hours) issued via OAuth2.1. Contact your Solenya account manager to provision your initial credentials. Once you have them, authenticate using the token refresh flow to obtain a bearer token:

{
  "Authorization": "Bearer <access_token>",
  "Solenya-Index-UUID": "<index_uuid>",
  "Solenya-User-UUID": "<user_uuid>"
}

All three headers are required for item queries. See Authentication for full details.

Step 5: Run Your First Query

With your index UUID and an access token in hand, run a search query against the GraphQL API at https://api.solenya.ai/v1/graphql:

query QuickstartSearch {
  items {
    merchant_feed(
      rank_with: {
        multimodal_query: {
          text: "blue running shoes"
        }
      }
      distinct_on: { selector: item_group_id }
    ) {
      page(page_size: 10, page_number: 1) {
        rows {
          record {
            item_group_id
            title
            brand
            price
            image_link
          }
          metadata {
            score
          }
        }
        page_info {
          has_next_page
        }
      }
    }
  }
}

You should get back ranked results from your catalog. From here, explore personalisation, filters, facets, and event tracking.

API Reference

Live interactive documentation for each part of the API: