Skip to Content
GuidesGet your data in

Get your data in

This guide takes you from a new organization to your first search on your own data. Pick one path. Each path takes about 3 minutes.

Video coming soon: “From API key to first search with your agent”, a walkthrough by David in under 3 minutes.

With your coding agent

1. Install the plugin

The Relevan agent plugin adds the hosted MCP server and the Relevan skills to your agent.

Claude Code:

claude plugin marketplace add relevan-dev/agent-plugins claude plugin install relevan@relevan

GitHub Copilot CLI:

copilot plugin marketplace add relevan-dev/agent-plugins copilot plugin install relevan@relevan

Codex:

codex plugin marketplace add relevan-dev/agent-plugins codex plugin add relevan@relevan

Start a new session after the install. For another MCP client, add https://api.relevan.dev/v1/mcp as described in Connect an AI assistant with MCP.

2. Sign in

The MCP server uses OAuth, so you need no API key.

  1. Connect the relevan MCP server:
    • Claude Code: run /mcp, select relevan, then select Authenticate.
    • Copilot CLI: run /mcp, then select relevan.
    • Codex: run codex mcp login relevan.
  2. Sign in to the Relevan console in your browser, and pick your organization.
  3. Allow write access. The agent needs it to create an index and upload documents. Only an owner of the organization can allow it.

3. Ask the agent

Give the agent this prompt. To use your own data, replace the sample catalog with the path of your CSV or JSON export.

Use the relevan-setup skill. Create a Relevan index named "products". Make a sample catalog of 20 products with a title, a brand, a category, and a price, deploy a mapping for it, and upload it. Then search the index for "waterproof hiking boots" and show me the results with the explanation of each match.

The agent gives you a link to the index in the console. Open it to see the build progress.

Each MCP tool call takes a maximum of 8 KB of JSON. For a large export, ask the agent to write a script that uses the bulk endpoint in the next section.

With the API or Python

1. Create an API key

Create a write API key in the console. A read key gets 403 when it creates an index or uploads documents. Keep the key in a server environment variable named RELEVAN_API_KEY.

Find the id of your organization. Use it as {orgId} in each request below.

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

To use Python, install the client with pip install relevan. The client reads RELEVAN_API_KEY from the environment.

2. Create an index and a mapping

A mapping tells Relevan which fields to search, filter, and sort on. Relevan rejects documents until the index has a mapping.

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" }' 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" } } }'
from relevan import Client client = Client() org = client.organizations.list()[0] client.indexes.create(org.id, name="products") client.mappings.create( org.id, "products", 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.

3. Upload documents

Send a maximum of 1000 documents in each request. If one document does not agree with the mapping, Relevan rejects the full request and writes no documents.

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 } }, { "id": "sku-2", "content": { "title": "Summit Hiking Boot", "brand": "Northpeak", "price": 189.0 } } ] }'
client.documents.bulk_ingest( org.id, "products", documents=[ ("sku-1", {"title": "Trail Runner 2", "brand": "Northpeak", "price": 129.99}), ("sku-2", {"title": "Summit Hiking Boot", "brand": "Northpeak", "price": 189.0}), ], )

Relevan builds the index and indexes the documents in the background. Before you search, wait until the index status is ready and readyToSearch is true. This takes from a few seconds to a few minutes. If the status is failed, reply to the email that sent you here.

curl https://api.relevan.dev/v1/{orgId}/indexes/products \ -H "x-api-key: $RELEVAN_API_KEY"
import time while True: index = client.indexes.get(org.id, "products") if index.status == "failed": raise RuntimeError("The index failed to build") if index.status == "ready" and index.ready_to_search: break time.sleep(5)
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": "hiking boot" }'
results = client.search.search(org.id, "products", query="hiking boot") for hit in results.results: print(hit.id, hit.explanation)

Each result has an id and an explanation of why it matched. Keep searchContext.queryId from the response (results.search_context.query_id in Python). The feedback call needs it.

Next: send click feedback

Feedback trains the ranking of your index. The next step is a click event each time a user clicks a result. Send feedback in the Getting started guide shows the request. The feedback skill gives each event type.

Questions

Reply to the email that sent you here. The reply goes to David, the founder of Relevan.

Last updated on