# 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's always in sync with what's deployed. All `/v1` 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.
- 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.

## Notes

- Requests are versioned under `/v1`, so future breaking changes ship as new versions rather than in place.
- Errors return a consistent JSON shape (`ErrorResponse` in the OpenAPI spec: `message` plus an optional `error` detail) rather than ad hoc formats per route.