# Quickstart

> 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](https://console.solenya.ai), with Google or Microsoft | |
| 2. Add your feed | Console: **Developer tools → Settings → Feeds** | [`add_feed`](https://solenya.ai/docs/setup.md#add-a-feed) |
| 3. Create an index | Console: **Developer tools → Settings → Indexes** | [`add_index`](https://solenya.ai/docs/setup.md#create-an-index) |
| 4. Create an API key | Console: **Developer tools → Settings → Tokens** | [`POST /v1/auth/keys/api-key`](https://solenya.ai/docs/auth.md#api-keys) |
| 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](https://solenya.ai/docs/auth.md#sign-in-and-session-tokens).

## 1. Sign in to the Console

Solenya creates your account and invites you. Sign in at [console.solenya.ai](https://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](https://support.google.com/merchants/answer/7052112): 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](https://solenya.ai/docs/setup.md#feed-requirements).

## 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:

```graphql
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](https://solenya.ai/docs/setup.md#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](https://solenya.ai/docs/auth.md#required-headers). `Solenya-User-UUID` names the shopper; any UUID works for a first test, and [Shopper IDs](https://solenya.ai/docs/search.md#shopper-ids) explains how to make one per shopper.

```bash
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:

```ts
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](https://solenya.ai/docs/track.md#attribution) so Solenya can tie the outcome to the results that led to it.

## Next steps

- [Search and recommendations](https://solenya.ai/docs/search.md): similar products, cart suggestions, personalised browse.
- [Filters and facets](https://solenya.ai/docs/filters.md): narrow results and build filter sidebars.
- [Event tracking](https://solenya.ai/docs/track.md): send views, cart adds and purchases from the browser.
- [Errors and limits](https://solenya.ai/docs/errors.md): what can go wrong, and the limits to design around.

## Live API reference

| Reference | What it covers |
|-----------|----------------|
| [api.solenya.ai/v1/graphql](https://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](https://api.solenya.ai/v1/auth/docs) | Token, key and sign-in endpoints |
| [api.solenya.ai/v1/track/docs](https://api.solenya.ai/v1/track/docs) | Event tracking endpoint |
