# miscite Search API - LLM Guide

Welcome! If you are an AI assistant or LLM attempting to use the miscite Search API on behalf of a user, please follow these instructions.

## 1. Search Works (`POST /api/search`)
Use this endpoint to search the literature index. It supports semantic, lexical, and hybrid search.

**Payload schema (JSON):**
- `query` (string, required): The search text.
- `limit` (integer, optional): Number of results (max 100, default 20).
- `retrieval_mode` (string, optional): "hybrid" (default), "semantic", or "lexical".
- `hybrid_alpha` (float, optional): Balance of hybrid search (0.0 to 1.0, default 0.7).
- `sort_by` (string, optional): "relevance" (default), "citations_desc", or "year_desc".
- `filters` (object, optional): Includes parameters like `publication_year_min`, `publication_year_max`, `has_fulltext` (boolean), `work_types` (list of strings like "article", "review"), etc.

**Response:**
Returns a JSON object with `hits`. Each hit contains an `openalex_id`, `title`, `doi`, `publication_year`, and `score`.

## 2. Search Health (`GET /api/search/health`)
Use this endpoint to check whether the search backend is available.

**Response:**
Returns a JSON object with a `status` field.

## 3. Get Work Details & Fulltext (`GET /api/search/works/{openalex_id}`)
Use this endpoint to retrieve the full metadata and fulltext preview for a single work.

**Query Parameters:**
- `include_fulltext` (boolean, optional): Set to `true` to attempt to retrieve the full Markdown text for the work.
- `fulltext_max_markdown_chars` (integer, optional): Limit the return size of the markdown (recommended: 4000 to 10000 for previewing).

**Response:**
Returns a JSON object containing `openalex_id`, a detailed `payload` object with metadata (including an array of `authorships` resolved dynamically), and a sanitized `fulltext` preview object (if requested) that only exposes preview-safe markdown fields.