# LoiLoNote Explorer

> Self-hosted file manager for a teacher's LoiLoNote material boxes (資料盒) and courses, version 0.12.1. The page at https://loilonote.jacklee.vip/ is a JavaScript web app for people. AI agents and scripts should use the HTTP API described here.

API base URL: https://loilonote.jacklee.vip/api/v1
Paths below are relative to the API base URL.

Authentication: send `Authorization: Bearer <Explorer API key>` on every request, including downloads and previews. Keys start with `lle_` and are created by the teacher in the web app (account menu > Agent keys). Keep the key in the EXPLORER_API_KEY environment variable; never put it in URLs, files, logs or chat. Without a valid key every call except GET /health returns 401.

## Read before calling anything else (needs the key)

- Full agent guide, Markdown: GET https://loilonote.jacklee.vip/api/v1/agent-guide
- OpenAPI 3 contract, JSON: GET https://loilonote.jacklee.vip/api/v1/openapi.json

The guide explains the job model, conflict handling, uploads, downloads, previews, batch operations and search. Read it once per session before making changes.

## Quick start

1. GET /health (no key) and GET /auth (key) confirm the service and the teacher's LoiLoNote login.
2. Discover real IDs with GET /roots, GET /courses and GET /folders/{id}. Never guess IDs; file and folder IDs are not interchangeable.
3. Before any change, POST /operations/preview with the proposed operation to see the destination, name conflicts and warnings.
4. POST /operations with a stable idempotencyKey that you saved first. The response is a durable job, not the finished result.
5. Poll GET /jobs/{id} until job.state is "completed". Handle "waiting-input" (conflict decision), "waiting-auth", "needs-review", "failed" and "cancelled" as described in the guide.

## Rules

- Scopes: materials:read, materials:write, materials:delete and auth:manage. 403 SCOPE_DENIED means the key lacks that scope; ask the teacher instead of working around it.
- Retry a write only with the exact same JSON body and idempotencyKey. Never invent a new key to recover an uncertain write.
- Errors are JSON `{"error":{"code","message"}}` with messages in Traditional Chinese. Branch on error.code.
- Downloads, previews and SSE events are not JSON.