# Little Linked Librarian API

LLL catalogs book boxes, books and physical-copy journeys. Public discovery needs no login or guest token. The API returns JSON with links where supported; the browser UI uses the same underlying capabilities.

## Supported public access

- [Limited discovery manifest](/.well-known/lll.json)
- [Book boxes UI](/boxes)

Use this site's origin for the following requests and send `Accept: application/json`.
This is a curated guide, not a complete API reference. Full schemas and interactive
Swagger are not publicly published. Cloudflare may independently reject requests;
report HTTP status and response type rather than treating HTML as empty catalog data.

## Read books without authentication

1. `GET /api/library-boxes?limit=20&page=1` returns boxes under `data`.
2. `GET /api/library-boxes/nearby?latitude=40&longitude=-74&radius=5&limit=20` finds nearby boxes; radius is kilometers.
3. Select a real box ID returned by the API. `GET /api/library-boxes/{id}` reads details; `/boxes/{id}` opens the human UI.
4. `GET /api/books?libraryBoxId={id}&page=1&limit=100` lists books under `data`. Follow `pagination.hasMore` with increasing pages.
5. `GET /api/search/books?q=math&limit=20&offset=0` returns keyword matches under `results`. `/books/{id}` opens book details.

These reads never grant access to private vaults, scanner sessions, account data or mutations. Anonymous and guest refer to the same participation stage; a guest bearer is needed only for operations whose contract requires it.

## Remote MCP

Endpoint: `https://beta.littlelinkedlibrarian.com/mcp`. Transport: stateless Streamable HTTP, POST. No credentials. GET is intentionally 405, not a webpage.

Tools: `search_books(query, lat?, lng?)`, `list_books(box_id)`, `find_boxes(lat, lng, radius_miles?)`.

Search without location returns box-held results from the first 100 public keyword matches. With both coordinates, it searches up to 20 boxes within 5 km. Responses disclose limits. `list_books` follows pagination, failing explicitly if more than 2000 books or the request time budget is exceeded. Listings are not transactional snapshots. Nearby radius uses miles in MCP, kilometers in REST.

Cursor `.cursor/mcp.json`:

```json
{"mcpServers":{"lll":{"url":"https://beta.littlelinkedlibrarian.com/mcp"}}}
```

Claude: add the endpoint as a custom remote connector where supported. A chat without browsing, HTTP or an MCP connector cannot fetch live data merely because these links exist.

## Photos, accounts and private resources

Open [the book-box UI](/boxes), choose the intended box, upload a photo, review
uncertain candidates and explicitly confirm before saving. The read-only MCP
adapter does not upload or save photos. Never claim a save without its receipt.
Missing books in a photo are not deletion authority, and matching titles/ISBNs
do not identify the same physical copy.

Use the web app for registration, login and private vault actions. Owner checks
still apply. Never put credentials in links or ask users to paste passwords into chat.