# Scholaris

> Scholaris is a personal research library that reads anything (PDF, EPUB, DOCX, slides, audio, video, web pages, YouTube) and lets you search, ask and cite it with the exact printed page or second of every passage. Citations always come from stored anchors, never from a model: if a passage is not in the library, Scholaris will not cite it.

En español: Scholaris es una biblioteca leída y citable. Subes cualquier cosa, buscas, preguntas y citas, con la página impresa o el segundo exactos y ninguna cita inventada. Los nombres de los campos de la API están en español; abajo se explican en inglés.

## Quick start

- Base URL: https://scholaris.joseluissaorin.com/api/v1
- Auth: one header, `Authorization: Bearer sch_…`. Keys are created by the user in Scholaris → Ajustes (Settings) → Claves de API (https://scholaris.joseluissaorin.com/ajustes/claves). Scopes: `lectura` (read, search, ask), `escritura` (upload, delete, cite), `mcp`.
- JSON in, JSON out. Add `?formato=markdown` (or `Accept: text/markdown`) to any read to get Markdown, which is usually best for you.
- Errors: `{ "error": { "codigo", "mensaje" (Spanish), "message" (English), "estado", "documentacion" } }`. On 429, wait `Retry-After` seconds.
- Ids are short and stable: a document is like `dmuwtm9kmsanlrbm5`; a passage (fragment) id starts with its document id (`dmuwtm9kmsanlrbm5:t0.0`).

## The verbs

- `POST https://scholaris.joseluissaorin.com/api/v1/documentos`: add something. Body: the raw file (any Content-Type; pass `?nombre=file.pdf`), multipart field `archivo`, or JSON `{"url": "…"}`. Waits up to `?esperar=60` seconds; if not ready, returns 202 with `progreso_url`. Same file twice (SHA-256) returns the existing document with `duplicado: true`. Send `Idempotency-Key` when retrying URL uploads.
- `GET https://scholaris.joseluissaorin.com/api/v1/documentos`: list (`q`, `estado`, `limite`, `cursor`).
- `GET https://scholaris.joseluissaorin.com/api/v1/documentos/{id}`: metadata, `estado` (en_cola | procesando | listo | error), `progreso` 0-1, APA `referencia`. `?esperar=30` long-polls until done.
- `DELETE https://scholaris.joseluissaorin.com/api/v1/documentos/{id}`.
- `GET https://scholaris.joseluissaorin.com/api/v1/documentos/{id}/texto?desde=23&hasta=25`: read pages by printed folio («23», «xiv») or physical position («[12]»); in audio/video by time (`desde=1:02:00&hasta=1:05:00`). Without `hasta` returns 20 units and `siguiente` (pass it as `desde`).
- `GET https://scholaris.joseluissaorin.com/api/v1/buscar?q=…&k=10&documento=ID`: passages with `cita` («(Cortázar, 1977, 1:06:56)»), `localizador` («p. 23»), `ancla`, `enlace` (deep link to the reader at that page or second) and literal `texto`. Quote a phrase ("…") for literal search.
- `POST https://scholaris.joseluissaorin.com/api/v1/preguntar {"pregunta": "…"}`: Markdown answer with footnotes [^n] and `fuentes` (each a passage with its citation). `"stream": true` for SSE (`pasajes`, `texto`, `fuente`, `fin`).
- `POST https://scholaris.joseluissaorin.com/api/v1/citar {"texto": "…", "estilo": "apa"}`: returns the text with verified citations inserted, the list of `citas` (claim, citation, passage, `respaldo` 0-1) and the `bibliografia`. Any CSL style. A .docx body with `Accept: application/vnd.openxmlformats-officedocument.wordprocessingml.document` returns the cited .docx. Slow (often 20-90 s): waits `?esperar=120`, then 202 + `GET https://scholaris.joseluissaorin.com/api/v1/citar/{id}`.
- `POST https://scholaris.joseluissaorin.com/api/v1/verificar {"afirmacion": "…"}`: `veredicto` (respaldada | parcial | sin_respaldo | contradicha), `probabilidad` and the supporting or contradicting passages.

## Rules for agents

1. Cite only what the API returns. Copy `cita` and `localizador` verbatim; never build a page number yourself.
2. Quote `texto` literally when you quote. If you paraphrase, still attach the `cita`.
3. Give the user the `enlace` so they can check the page or the second.
4. If `buscar` returns nothing relevant, say so. Do not fill the gap from memory.
5. Before asserting something as supported by the user's sources, call `verificar`.

## Examples

```sh
export SCHOLARIS=sch_…   # Ajustes → Claves de API
curl -s https://scholaris.joseluissaorin.com/api/v1/documentos -H "Authorization: Bearer $SCHOLARIS" -H "Content-Type: application/pdf" --data-binary @articulo.pdf
curl -s "https://scholaris.joseluissaorin.com/api/v1/buscar?q=atención+escalada&k=3&formato=markdown" -H "Authorization: Bearer $SCHOLARIS"
curl -s https://scholaris.joseluissaorin.com/api/v1/preguntar -H "Authorization: Bearer $SCHOLARIS" -H "Content-Type: application/json" -d '{"pregunta":"¿Qué es la atención multicabeza?"}'
```

## More

- [Human guide (Spanish and English)](https://scholaris.joseluissaorin.com/api): copy-paste examples in curl, JavaScript and Python.
- [OpenAPI 3.1](https://scholaris.joseluissaorin.com/api/v1/openapi.json)
- [MCP server](https://scholaris.joseluissaorin.com/mcp): Streamable HTTP with OAuth or a key with the `mcp` scope. Tools: search, cite, open_page, verify_claim.
- [Python](https://scholaris.joseluissaorin.com/api#python): `pip install scholaris-sdk` (import name `scholaris`), then `from scholaris.api import Scholaris; Scholaris("sch_…").buscar("…")`.