API v1 and the MCP server

In one sentence

Everything the app does with your documents can be done from outside with an Authorization: Bearer sch_… header and nine verbs. The full guide, with a real recorded session, is at /en/api; the specification, in OpenAPI 3.1; and the instructions for models, at /api/v1/llms.txt. Field names are in Spanish.

The verbs

Base: https://scholaris-v2.jlsf2005.workers.dev/api/v1

Every read accepts formato=markdown or the header Accept: text/markdown. What takes time (uploading and citing) waits by default; with esperar=0 or Prefer: respond-async it answers 202 with progreso_url.

export SCHOLARIS=sch_…   # Settings → API keys

# Upload (waits until read, up to 60 s; longer, 202 with progreso_url)
curl -s "https://scholaris-v2.jlsf2005.workers.dev/api/v1/documentos?nombre=articulo.pdf" -H "Authorization: Bearer $SCHOLARIS" \
  -H "Content-Type: application/pdf" --data-binary @articulo.pdf

# Search, in Markdown
curl -sG https://scholaris-v2.jlsf2005.workers.dev/api/v1/buscar -H "Authorization: Bearer $SCHOLARIS" \
  --data-urlencode "q=atención escalada" -d k=5 -d formato=markdown

# Verify a claim
curl -s https://scholaris-v2.jlsf2005.workers.dev/api/v1/verificar -H "Authorization: Bearer $SCHOLARIS" -H "Content-Type: application/json" \
  -d '{"afirmacion": "El Transformer prescinde de la recurrencia."}'

from scholaris.api import Scholaris

s = Scholaris("sch_…")                      # or the SCHOLARIS_CLAVE variable
doc = s.subir("articulo.pdf")                # a URL works too
for p in s.buscar("atención escalada", k=3):
    print(p["cita"], p["texto"][:80], p["enlace"])

Keys and scopes

Keys are created in Ajustes (Settings) → Claves de API (API keys) and shown only once; Scholaris stores only their SHA-256 hash. They can expire after as many days as you choose. Each key has scopes:

lectura (read)

search, read, ask and verify.

escritura (write)

upload and delete documents, and cite a whole text (autocite stores its work).

mcp

use the key with the MCP server.

Without explicit scopes, a new key gets lectura and mcp.

Limits

Going over the rate gives a 429 with Retry-After; using up a quota, a 402 (cuota_superada or requiere_pro). To retry without duplicating, send Idempotency-Key when uploading and citing: with the same key, for 24 hours, you get the same resource back. An identical file (same hash) returns the existing one, with duplicado: true.

Errors

They all have the same shape, with the message in Spanish and English:

{ "error": { "codigo": "prohibido", "mensaje": "Esta clave de API es de solo lectura.", "message": "This key is not allowed to do that.", "estado": 403, "documentacion": "https://scholaris-v2.jlsf2005.workers.dev/api#errores" } }

Codes: no_autenticado (401), prohibido (403), peticion_invalida (400), no_encontrado (404), conflicto (409), demasiado_grande (413), cuota_superada and requiere_pro (402), limite_de_ritmo (429), proveedor_fallo (502), no_disponible and interno.

The MCP server

At https://scholaris-v2.jlsf2005.workers.dev/mcp, over HTTP (stateless Streamable HTTP). It offers four tools:

There are two ways to connect:

• OAuth 2.1, for Claude (web and desktop) and any client that speaks it: Settings → Connectors → Add custom connector, with the address https://scholaris-v2.jlsf2005.workers.dev/mcp. The client registers itself, you sign in to Scholaris and grant access. That access is read-only: search, open pages, cite and verify; it cannot upload, change or delete. Tokens last an hour and are refreshed.
• A key with the mcp scope, for Claude Code, Cursor, Windsurf and the rest:

claude mcp add --transport http scholaris https://scholaris-v2.jlsf2005.workers.dev/mcp \
  --header "Authorization: Bearer sch_…"

{
  "mcpServers": {
    "scholaris": {
      "url": "https://scholaris-v2.jlsf2005.workers.dev/mcp",
      "headers": { "Authorization": "Bearer sch_…" }
    }
  }
}

The OAuth metadata is where clients look for it: /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp. There is also a server card at /.well-known/mcp/server-card.json.

For agents

The rules of use (cite only what the API returns, copy the citation verbatim, give the link, say when nothing is found) are on the page for agents.