Skip to Content
Relevan Beta is here šŸŽ‰
GuidesGetting started with Relevan

Getting started with Relevan

This guide takes you from an empty account to a search that learns. You create an index, load your documents, run a search, and send the first feedback.

If you use a coding agent, give it the setup skill. The skill gives the agent the same steps.

Before you start

You need:

  • A Relevan account. Sign up in the console.
  • A sample of your documents, such as products, articles, or profiles, as JSON.

1. Create an API key

Create an API key in the console. Keep the key in a server environment variable, such as RELEVAN_API_KEY. Do not put the key in browser code.

Send the key in the x-api-key header on each request. Then find your organization:

curl https://api.relevan.dev/v1/organizations \
  -H "x-api-key: $RELEVAN_API_KEY"

The response is a list with one organization. Use its id or its slug as {orgId} in each request below.

2. Create an index

curl -X POST https://api.relevan.dev/v1/{orgId}/indexes \
  -H "x-api-key: $RELEVAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "name": "products" }'

The consoleUrl field of the response links to the index list in the console. Open it to see the build progress.

3. Find the ranking signals

Text matching finds the documents that contain the query words. It cannot tell which of those documents is the best one. Find the values in your data that can tell this, such as a price, a sales count, a stock level, or the date of the last activity. Add each one to your documents as a field before you upload them.

The ranking signals skill gives the steps and examples.

4. Deploy a mapping

A mapping tells Relevan which fields to search, filter, and sort on. Relevan rejects a document until the index has a mapping. Declare each field that your documents contain:

curl -X POST https://api.relevan.dev/v1/{orgId}/indexes/products/mappings \
  -H "x-api-key: $RELEVAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "fields": {
      "title": { "use": ["searchable", "autocompletable"], "kind": "text" },
      "brand": { "use": ["filterable"] },
      "price": { "use": ["filterable", "sortable"], "kind": "number" }
    }
  }'

The mapping skill gives each rule for use, kind, and language.

5. Upload your documents

Send a maximum of 1000 documents in each request:

curl -X POST https://api.relevan.dev/v1/{orgId}/indexes/products/documents/_bulk \
  -H "x-api-key: $RELEVAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "documents": [
      { "id": "sku-1", "content": { "title": "Trail Runner 2", "brand": "Northpeak", "price": 129.99 } }
    ]
  }'

If one document does not agree with the mapping, Relevan rejects the full request and writes no documents. The response names each document with a problem.

curl -X POST https://api.relevan.dev/v1/{orgId}/indexes/products/search \
  -H "x-api-key: $RELEVAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "query": "trail shoe" }'

Each result has an id and an explanation of why it matched. Keep searchContext.queryId from the response. The feedback call needs it.

7. Send feedback

Feedback tells Relevan which results were good. It trains the ranking of your index. When a user clicks a result, send a click event from your server:

curl -X POST https://api.relevan.dev/v1-beta/{orgId}/indexes/products/feedback \
  -H "x-api-key: $RELEVAN_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "actionName": "click", "queryId": "<queryId>", "objectId": "sku-1", "position": 1 }'

Send a conversion event for a closing event, such as a purchase. The feedback skill gives each event type.

Next steps

Last updated on
GuidesReleases