Getting started

Welcome to the getting started page for developers. If you are new to the Search and Recommendation Engine APIs, we recommend that you first review the Building Blocks before continuing.

Otherwise, you need to complete the three steps below to be ready for implementation.

1. Ensure you have access

To work with our services, you need a Server URL, a Dataset ID, and an API Credential. You can retrieve these from My Relewise. Navigate to Administration -> API Credentials, and create an API Key or OAuth 2.0 client credential for your application. The SDK examples in this guide use an API Key.

We recommend that you have access to My Relewise yourself so you can inspect API calls and other information while implementing Relewise. If your organization already uses Relewise, ask your administrator or Relewise contact for access to the relevant Dataset.

If you are exploring Relewise for your business, book a tailored demo to discuss your requirements with our team.

Keep in mind that different Datasets will point to different servers depending on the purpose of the Dataset, so you should always double-check My Relewise to ensure you are directing your calls to the correct server.

Create an API Credential

Create a separate API Credential for each application or integration and grant only the permissions it requires. Keep backend API Keys and Client Secrets in secure server-side configuration, and configure allowed origins for browser API Keys.

2. Choose your technology

Any technology can be used to call the Relewise API. For the fastest start, choose an SDK guide:

• .NET SDK
• TypeScript / JavaScript SDK
• PHP SDK
• Java SDK

3. Authenticate

The Relewise API supports API Keys and OAuth 2.0 client credentials. The OAuth 2.0 client credentials grant is intended for trusted backend-to-backend integrations; browser-based token requests are not supported. See API Credentials for setup, permissions, restrictions, and rotation guidance, and OAuth Authentication for token acquisition and API requests.

The examples below use API Key authentication. The .NET SDK supports both methods, including a complete OAuth example. The TypeScript / JavaScript, PHP, and Java SDKs currently use API Keys. For direct HTTP integration with either method, see the JSON API authentication guide.

The Dataset ID is used in the API request URL. API Key requests use Authorization: APIKey <api-key>; OAuth requests use Authorization: Bearer <access-token>.

Datakeys are Case Sensitive

Most datakeys in Relewise are case sensitive. Ensure that your data adheres to this case sensitivity to avoid unnecessary issues during implementation.

To learn more, click here.

Below is an example of a tracking request sent to Relewise, which is one of the first things you will do when implementing our system. The request tracks that a user has viewed a product.

.NET

string apiKeySecret = "<Your API Key>";
Guid datasetId = Guid.Parse("<Dataset ID>");
string serverUrl = "<Your Server URL>";
Relewise.Client.ITracker tracker = new Tracker(datasetId, apiKeySecret, serverUrl);
await tracker.TrackAsync(
   new ProductView(
       User.ByTemporaryId("<unique Id>"), //Depend on how much you know about the user
       new Product("p-1")
       )
   );

TS/JS

import { Tracker, UserFactory } from "@relewise/client"

const tracker = new Tracker("<Your Dataset ID>", "<Your API Key>", { serverUrl: "<Your Server Url>" });

tracker.trackProductView({ 
  productId: 'p-1', 
  user: UserFactory.anonymous() 
})

PHP

use Relewise\Client\Tracker;
use Relewise\Client\UserFactory;

$tracker = new Tracker("<Your Dataset ID>", "<Your API Key>", ["serverUrl" => "<Your Server Url>"]); 

$tracker->trackProductView([
    'productId' => 'p-1',
    'user' => UserFactory::anonymous()
]);

With authentication complete, you are ready to proceed in your integration of Relewise. We urge you to read our Best Practices to ensure that you set things up correctly the first time around.

UI components and reference implementation

• Web Components: Use our ready-made UI components to add search, recommendations, and tracking quickly. See Web Components for install steps, attributes, and styling options.
• Relewise Demo Shop: Explore our Demo Shop to see Web Components running in a full storefront. That page explains what the shop is, how to run it locally, and where to grab reusable markup and tracking patterns for your own build.

Third-party integrations

• Shopify: Install the Relewise Shopify App for one-click import, tracking, search, and recommendations in Shopify themes. If you prefer to wire it yourself, follow the manual Shopify setup guide.
• Other platforms: See our third-party integrations overview for connectors and guides across marketing, pricing, and ecommerce tools.