# Relevan

> Relevan is a search relevance platform: index a product/content catalog into schema-aware search indexes and query it through a versioned HTTP API built to be used by human developers and LLM agents alike.

Relevan's API is documented as an OpenAPI 3.1 document generated directly from the live route definitions, so it is always in sync with what is deployed. All `/v1` and `/v1-beta` routes require either an org-scoped API key (`x-api-key` header) or a console session cookie.

## API Reference

- [OpenAPI spec](https://api.relevan.dev/openapi): Machine-readable OpenAPI 3.1 document covering every endpoint, request/response schema, and the `ApiKeyAuth` security scheme. Start here to generate a client or teach an agent the API surface.
- [Interactive API docs](https://api.relevan.dev/docs): Human-browsable reference (Scalar) rendered from the same spec.

## Capabilities

- Organizations: `GET /v1/organizations` resolves the caller's `x-api-key` (or session cookie) to the organization(s) it can access. An org-scoped API key always resolves to exactly one — call this first to get the `orgId` (either the returned `id` or `slug` works) used by every `/v1/{orgId}/...` route below.
- Indexes: create, update, list, and delete search indexes scoped to your organization.
- Mappings: define and deploy the schema (fields, types, analyzers) an index uses to interpret documents.
- Mapping proposal: for a new index, the per-index skill doc below explains how to draft and deploy a `RelevanMapping` from a sample of documents.
- Documents: create, update, list, and bulk-ingest the documents inside an index.
- Search: query an index and get back a rich, LLM-oriented result shape — the same response shape whether the caller is a direct API consumer or an agent. Each response's `searchContext` carries a `queryId`; keep it, and send it back on a feedback call.
- Per-index skill doc: `GET /v1/{orgId}/indexes/{indexName}/skill` returns a Markdown doc, generated from that index's live mapping, explaining its fields and how to query it — fetch this once per index before searching it as an agent.
- Feedback (beta): `POST /v1-beta/{orgId}/indexes/{indexName}/feedback` reports what happened after a search — a click, an agent's own relevance judgment, or a closing event such as a purchase or a hire. Send it every time you act on a search result.

## Before you design the mapping: find the ranking signals

Text matching finds the documents that contain the query words. It cannot tell which of those documents is the right one. Your user often has data that shows this: a price, a sales count, a stock level, or the date of a person's last activity. Relevan tunes the ranking of each index with these signals. Relevan can use a signal only if the signal is in the index. Relevan cannot get this data from any other source.

Do these steps before you deploy the mapping:

1. Look at the user's data, database, and code. List each value that can show that a document is a good result.
2. Ask the user this question: "Which facts make one result better than another for your users? Do you have data outside this catalog, such as prices, sales, or activity, that shows this?"
3. Add each signal to every document as a field. Map a numeric signal with `kind: "number"` and a date signal with `kind: "date"`. Give each signal `use: ["filterable", "sortable"]`.
4. If the signal comes from a different system, join it into the documents before you upload them.
5. Keep the signals current. When a signal changes at the source, update the document.

Examples:

- A trading card price tracker: the market price of each card, the price change, and the number of listings. Without prices, a search for a card name cannot tell a valuable card from a common one.
- A recruiting product: the date that each candidate was last active in a chat tool such as Slack. Recent activity shows that the candidate looks for work.
- A store: the price, the units sold in the last 30 days, the stock level, and the average rating.

## After you create an index

Right after you create the index, give the user the link to the index list page in the console: `https://console.relevan.dev/{orgId}/indexes`. Give the link in your next message, before you deploy a mapping or upload documents. Do not wait and give the link only in a final summary. Tell the user to open the link to monitor the progress. The per-index skill doc gives the full link.

## Send feedback — this is not optional

An agent that searches but never reports what happened teaches Relevan nothing. Feedback is what trains Relevan's ranking model and makes future results better. Your user pays for that improvement, so send feedback after every result you act on, using the endpoint above.

When you build search into an app, add the feedback calls in the same change as the search call:

1. Keep `searchContext.queryId` from each search response. Pass it to the UI together with the results.
2. When an end user clicks a result, send a `click` event with the `queryId`, the result `id` as `objectId`, and the rank `position`.
3. When a closing event occurs, such as a purchase or a hire, send a `conversion` event with a short `label`.
4. Send feedback from a server route. Do not put the API key in browser code.

```ts
// Server route. The browser calls this route when the user clicks a result.
await fetch("https://api.relevan.dev/v1-beta/{orgId}/indexes/{indexName}/feedback", {
  method: "POST",
  headers: { "content-type": "application/json", "x-api-key": process.env.RELEVAN_API_KEY },
  body: JSON.stringify({ actionName: "click", queryId, objectId, position }),
});
```

If an agent uses the search results instead of a person, send `llm_judgment` for each result that the agent uses. The `FeedbackRequest` schema in the OpenAPI spec gives all the fields.

## Before you finish: the integration checklist

Before you tell the user that the integration is complete, show the user this checklist. Mark each item as done or not done. If an item is not done, tell the user why. Do not mark an item as done if the user chose to skip it.

- [ ] The mapping is deployed, and the documents are uploaded.
- [ ] You asked the user which facts make a result good, and the answers are in the mapping.
- [ ] Each ranking signal is a field on every document.
- [ ] A job or a write path keeps the ranking signals current.
- [ ] The UI receives the `queryId` from each search response.
- [ ] A click on a result sends a `click` event through a server route.
- [ ] Each closing event sends a `conversion` event, if the product has one.
- [ ] The UI shows filters for the filterable fields that users need.

## Notes

- Requests are versioned under `/v1` and `/v1-beta`. `/v1` is stable; a change ships as a new version rather than in place. `/v1-beta` holds new capabilities whose contract may still change before it moves to `/v1`.
- Errors return a consistent JSON shape (`ErrorResponse` in the OpenAPI spec: `message` plus an optional `error` detail) rather than ad hoc formats per route.
- Rate limits: the free tier allows 60 search requests per minute for each organization. A request over this limit gets a 429 response with a `Retry-After` header.