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.
- With your coding agent: Claude Code, GitHub Copilot CLI, or Codex does the work through the Relevan MCP server.
- With the API or Python: you send the requests yourself.
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@relevanGitHub Copilot CLI:
copilot plugin marketplace add relevan-dev/agent-plugins
copilot plugin install relevan@relevanCodex:
codex plugin marketplace add relevan-dev/agent-plugins
codex plugin add relevan@relevanStart 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.
- Connect the
relevanMCP server:- Claude Code: run
/mcp, selectrelevan, then select Authenticate. - Copilot CLI: run
/mcp, then selectrelevan. - Codex: run
codex mcp login relevan.
- Claude Code: run
- Sign in to the Relevan console in your browser, and pick your organization.
- Allow
writeaccess. 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)4. Search
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.