# 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://feat-650-agent-skills.api.dev.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://feat-650-agent-skills.api.dev.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: the `relevan-mapping` skill 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. ## Skills Each skill is a Markdown file for one task. Fetch the skill for your task, or save each file as `//SKILL.md` to install it. - [relevan-setup](https://feat-650-agent-skills.api.dev.relevan.dev/skills/relevan-setup/SKILL.md): Set up Relevan search from the start: authenticate, create an index, load documents, run the first search, and send the first feedback. Use when a user asks you to add Relevan search to a product. - [relevan-ranking-signals](https://feat-650-agent-skills.api.dev.relevan.dev/skills/relevan-ranking-signals/SKILL.md): Find the data that tells Relevan which result is the best one, such as prices, sales, or activity, and add it to each document. Use before you design a Relevan mapping. - [relevan-mapping](https://feat-650-agent-skills.api.dev.relevan.dev/skills/relevan-mapping/SKILL.md): Draft and deploy a RelevanMapping from a sample of documents. Use when a Relevan index has no mapping, or when the documents get new fields. - [relevan-feedback](https://feat-650-agent-skills.api.dev.relevan.dev/skills/relevan-feedback/SKILL.md): Send click, conversion, and llm_judgment feedback to Relevan after a search, so the ranking gets better. Use when you build search into an app, or when an agent acts on a search result. Start with `relevan-setup`. It links the other skills at the step that needs them. ## 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. - Monthly search quota: the free tier allows 10,000 searches per calendar month (UTC) for each organization. Each search response has the `X-Search-Quota-Limit`, `X-Search-Quota-Remaining`, and `X-Search-Quota-Reset` headers. Read them after your first search, and plan your work so that you do not use all the searches. A search over the quota gets a 402 response with `code: "search_quota_exceeded"` and a `Retry-After` header that gives the seconds until the quota resets. Do not retry a 402 before that time. A search that fails does not count. ## Other Relevan documents - [Relevan overview](https://feat-650-agent-skills.dev.relevan.dev/llms.txt): What Relevan is, who it suits, and what it costs. - [Documentation index](https://feat-650-agent-skills.docs.dev.relevan.dev/llms.txt): Each page of the Relevan documentation and blog.