# 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.
- 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.

## 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. See the per-index skill doc for the exact request shape.

## 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.